JetBrains phpstorm-stubs for PhpStorm Runtime Awareness

PhpStub's Role in PhpStorm PHP Analysis

JetBrains/phpstorm-stubs solves a specific IDE problem: PHP has many built-in functions, classes, constants, and extension APIs whose signatures are not represented by ordinary application code. PhpStorm can use the repository's stubs to provide completion, code inspection, type inference, and documentation popups for that built-in surface.

The target audience is split between PhpStorm users and people maintaining PHP tooling metadata. An IDE user needs a reliable local copy that can be updated with Git. A contributor needs to edit the correct stub file, preserve PHPDoc, and run the repository's validation suites.

The repository is not a replacement for PHP itself, and it is not a package intended to execute PHP APIs. Its contents are normal, syntactically correct PHP files containing signatures, constants, and related declarations. The README specifically says that complete PHPDoc is needed, especially proper @return annotations, because much of the IDE behavior depends on those annotations.

What the Stub Tree Contains

The repository organizes stubs by PHP feature area rather than presenting a single generated file. The top-level tree includes Core/ and numerous extension directories, including Reflection/, SPL/, PDO/, FFI/, curl/, and apcu/. The exact extension set represented by a branch is therefore determined by the files present in the checkout.

PhpStormStubsMap.php records the stub map used to associate stubs with runtime features. The README gives a separate command for regenerating that file after changing the stub set. This map is a project artifact that contributors must update deliberately rather than assume is automatically derived during a normal test run.

Some stubs cover PHP Core and bundled extensions. Others cover extensions described by the project as non-standard. The README says that non-standard extension stubs are supplied as they are and that their support is community-driven. The project validates their PHPDoc, but it does not check whether those stubs match the actual extension implementation or whether the descriptions are correct. That distinction matters when adopting the files as an IDE reference for less central extensions.

Connecting a Git Checkout to PhpStorm

The README does not document a Composer installation procedure for end users. Instead, it describes a source checkout workflow for PhpStorm. Make a full copy of the Git repository, then configure its path in the IDE. This makes the stub source directly editable and updatable through normal Git operations.

In PhpStorm, open the settings path documented by the README and set the default stubs path to the checkout root. The exact path is local to the reader, so no example path should be invented. After configuring it, a PHP project can use the repository as its default stub source for completion and inspection.

This workflow is useful when the bundled stubs need to be updated before or alongside a PhpStorm release. It also creates a maintenance responsibility. A contributor changing declarations or PHPDoc should not assume that the checkout automatically matches the runtime installed on the developer's machine.

Validating Stub Changes Across PHP Versions

The repository provides Docker-based tests because a single local PHP runtime does not represent every supported PHP version. The bundled scripts install dependencies, regenerate the local stubs cache, and run the Unit, Structure, PhpDoc, and General suites in order. The documentation states that the normal run uses committed reflection caches, matching the CI behavior.

On macOS or Linux, the documented all-suite command is:

Running the PHP Stub Test Suite

The repository's easiest documented test path is the bundled script. On macOS or Linux, run the following command from the repository root. The script installs dependencies, regenerates the cache used for the edited stubs, and runs the Unit, Structure, PhpDoc, and General suites. Docker is required because the scripts use the test_runner image defined in docker-compose.yml.

./runTests.sh

For a narrower local iteration, the README documents selecting one PHP version. The command below runs the checks that apply to PHP 5.6. Unit and Structure still run in full because they are not tied to a PHP version. A version-specific suite can be reported as empty when no applicable cases exist.

./runTests.sh --php-version 5.6

The Windows equivalents are `runTests.bat` and `runTests.bat --php-version 5.6`. The README says CI runs every version, while local iteration can target one version. For manually running individual steps, the project documents dependency installation, stub-cache regeneration, and PHPUnit suite selection through Docker Compose. The reflection caches are committed so ordinary validation does not rewrite them. Passing `--refresh-reflection` is possible, but the README describes it as slow and says the result should not be committed.

Checking Validation Boundaries and Exception Tags

The validation system has a clear limit around thrown exceptions. The README explicitly states that there are no tests for thrown exceptions and that @throws tags should be checked manually against official documentation or PHP source code. This is a meaningful adoption constraint for teams relying on precise exception metadata. A green test run does not establish that every @throws declaration is correct.

There is a second limit for non-standard extensions. Their PHPDoc is validated, but the repository does not check whether the stub matches the actual extension or whether its descriptions are correct. For those APIs, the source of truth must be the extension implementation, its official documentation, or another independently verified reference.

The test architecture also uses per-version reflection caches under tests/cache/Reflection<version>.json. The Docker Compose file pins services to linux/amd64 because reflection values can depend on the CPU ABI. The project documents that this choice keeps generated caches reproducible across host architectures, including Apple Silicon, although emulation may be slower.

Maintenance, Releases, and Licence Boundaries

The repository is not archived, and its last push was on 2026-10-11. Recent releases include v2026.2 on 2026-07-22, v2026.1 on 2026-04-28, and v2025.3 on 2026-01-19. The README does not define a stable release cadence or a compatibility policy beyond the release information and the PhpStorm release names.

The project uses Apache 2.0. The README also says that it contains material by the PHP Documentation Group under CC-BY 3.0. Some @link tags point to php-legacy-docs.zend.com because the corresponding php.net manual pages were retired. Those links are intentionally preserved, and contributors are told not to replace them with php.net links. A user distributing or incorporating the stubs must account for both the Apache 2.0 project licence and the documented CC-BY 3.0 material.

Editorial conclusion

PhpStorm users should adopt this repository when they need an editable stub source for completion, inspection, type inference, and documentation popups. Contributors should verify signature accuracy against PHP source or official documentation before merging, especially for @throws tags and community-maintained extensions. This is a development metadata project, not a PHP runtime package.

Frequently asked questions

Official sources

1. JetBrains/phpstorm-stubs on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases