Phpstorm Stubs Laravel Package

Getting Started

Install as a dev dependency to bring in official PhpStorm stubs for accurate IDE support:

composer require --dev jetbrains/phpstorm-stubs

This package doesn’t affect runtime—it only enhances static analysis and IDE intelligence. First use case: configure your IDE to use local stubs (e.g., in PhpStorm: Settings > Languages & Frameworks > PHP > PHP Runtime > Advanced settings > Default stubs path → vendor/jetbrains/phpstorm-stubs). Instantly gain better autocomplete, parameter hints, and type inference for core PHP functions and standard extensions. No code changes needed—just restart the IDE or reindex.

Implementation Patterns

• Static analysis alignment: Reference stubs in PHPStan or Psalm config to ensure analysis matches actual API signatures and PHPDoc:

  // phpstan.neon
  parameters:
    stubFiles: [vendor/jetbrains/phpstorm-stubs/PhpStormStubs.php]
  

• IDE extensibility: Point PhpStorm to a cloned repo of this repo for bleeding-edge updates; run git pull to stay current without waiting for IDE updates.
• Per-project versioning: Pin to a specific stub version (e.g., v2024.2) in composer.json to match your PHP runtime—critical when supporting multiple PHP versions or large teams.
• CI safety net: Run static analysis tools in CI using the project’s stubs to catch subtle API mismatches (e.g., @return types differing across PHP minor versions).
• Extension stub injection: For third-party extensions missing from core stubs, place custom stub files (e.g., myext.stub.php) in a stubs/ directory and register it in your IDE’s PHP settings.

Gotchas and Tips

• @throws annotations are often missing or outdated—the package explicitly warns: verify exception behavior against PHP docs or source code manually. Relying solely on stub-based error analysis may suppress legitimate static analysis warnings.
• PECL/non-standard extension stubs are community-maintained—check coverage for extensions like swoole, msgpack, or ext-redis in src/; outdated stubs can cause false positives/negatives in autocomplete and type checking.
• Stubs ≠ runtime behavior: They’re declarative only. No runtime impact, and missing stubs won’t break your app—only degrade IDE/analysis quality.
• Regenerate PhpStormStubsMap.php after upgrades (especially PHP version bumps) using docker compose run test_runner /usr/local/bin/php tests/Tools/generate-stub-map. Skipping this may cause incomplete symbol indexing or missing hints.
• Use -dev versions or direct git repos in PhpStorm settings for active development on stubs themselves (e.g., fixing a function signature)—just avoid committing IDE settings pointing to local paths.