Phpstorm Stubs Laravel Package

Getting Started

Minimal Steps to Enable

1. Install via Composer (dev dependency):

   composer require --dev jetbrains/phpstorm-stubs
   

2. Configure PhpStorm:

   • Go to Settings > Languages & Frameworks > PHP.
   • Under PHP Runtime, click Advanced Settings.
   • Set Default stubs path to the local path of the cloned jetbrains/phpstorm-stubs repository (e.g., ./vendor/jetbrains/phpstorm-stubs/stubs).
   • Ensure Use composer autoloader is checked.

3. Invalidate Caches:

   • In PhpStorm, go to File > Invalidate Caches / Restart to refresh IDE indexing.

4. Verify:

   • Test autocompletion on core PHP functions (e.g., array_* or str_*) and Laravel classes (e.g., Illuminate\Support\Collection).

First Use Case: Laravel Development

• Problem: PhpStorm shows incomplete or incorrect method signatures for Laravel’s Collection or Facade classes.
• Solution: After enabling stubs, PhpStorm will:
  • Provide accurate autocompletion for Collection::where(), Facade::call(), etc.
  • Show correct @return types (e.g., Collection<int, Model> instead of mixed).
  • Highlight deprecated methods with IDE warnings.

Quick Checklist for Laravel Teams

Implementation Patterns

Workflow: Integrating with Laravel Projects

1. Project Setup:

   • Add stubs as a dev dependency in composer.json:

     {
       "require-dev": {
         "jetbrains/phpstorm-stubs": "^2024.2"
       }
     }
     

   • Run composer update to install.

2. PhpStorm Configuration:

   • Per-Project Stubs: For monorepos or multi-project setups, configure stubs per project:
     • Settings > PHP > PHP Runtime > Advanced > Default stubs path.
   • Global Stubs: Use a global stubs directory (e.g., ~/phpstorm-stubs) for all projects.

3. Version Management:

   • Pin to a specific stubs version (e.g., 2024.2) to avoid breaking changes:

     composer require jetbrains/phpstorm-stubs:2024.2 --dev
     

   • Update stubs quarterly (aligned with PhpStorm releases).

4. CI/CD Integration:

   • Pre-Commit Hook: Add a script to validate PHPDoc consistency:

     # .github/workflows/pre-commit.yml
     - name: Check PHPDoc
       run: |
         php -r "require 'vendor/jetbrains/phpstorm-stubs/stubs/stdlib.php';"
         # Custom script to lint docblocks against stubs
     

   • CI Validation: Run phpstan with --level=5 to ensure IDE and static analysis align.

Patterns for Extension Support

1. Standard Extensions (e.g., Redis, PDO, DOM):

   • Stubs are pre-bundled and require no additional setup.
   • Example: Redis methods like Redis::connect() will show correct signatures.

2. Non-Standard Extensions (e.g., MongoDB, GMP):

   • Stubs are community-maintained (PHPDoc validated but API accuracy not guaranteed).
   • Workaround: Extend stubs manually or contribute fixes via GitHub.

3. Custom Extensions:

   • Generate stubs using php -r 'reflection_function("your_function");' and add to stubs/ext-<extension>/.
   • Example for a custom MyExtension:

     // stubs/ext-myextension/MyExtension.php
     namespace MyExtension;
     /**
      * @method static string myCustomFunction(array $input)
      * @return string
      */
     class MyExtension {}
     

Integration with Static Analysis Tools

1. PHPStan/Psalm Alignment:

   • Ensure @return types in stubs match your static analysis tool’s expectations.
   • Example: Use array<int, string> instead of array for stricter typing.

2. Laravel-Specific Stubs:

   • Stubs for Illuminate\Support\Collection include modern PHP types (e.g., Collection<int, Model>).
   • Tip: Extend stubs for custom Collection macros:

     // stubs/framework/Illuminate/Support/Collection.php
     /**
      * @method static Collection<int, Model> customMacro(array $data)
      * @return Collection<int, Model>
      */
     

3. Testing Stub Accuracy:

   • Run phpstan analyze --level=5 and compare results with IDE hints.
   • Use php -r 'var_dump(reflection_function("array_map"));' to verify stubs match runtime behavior.

Gotchas and Tips

Pitfalls

1. Stub Version Mismatch:

   • Issue: Using stubs from PhpStorm 2021 with PhpStorm 2024 causes missing method signatures.
   • Fix: Pin stubs to the same major version as your PhpStorm (e.g., 2024.2 for PhpStorm 2024.2).

2. Non-Standard Extension Gaps:

   • Issue: Stubs for MongoDB or GMP may lack @throws or @param tags.
   • Fix: Manually extend stubs or contribute fixes via PRs.

3. IDE Caching Issues:

   • Issue: Changes to stubs aren’t reflected in PhpStorm.
   • Fix: Always Invalidate Caches (File > Invalidate Caches) after updating stubs.

4. PHPDoc Inconsistencies:

   • Issue: Stubs use @return mixed where @return array<int, T> is expected.
   • Fix: Override stubs locally or patch via stubs/overrides/.

5. Composer Autoloader Conflicts:

   • Issue: Stubs not loading due to autoloader conflicts.
   • Fix: Ensure composer dump-autoload is run after installing stubs.

Debugging Tips

1. Verify Stub Loading:

   • Check PhpStorm’s PHP Runtime settings to confirm the stubs path is correct.
   • Use php -r 'var_dump(class_exists("stdClass"));' to test basic stub functionality.

2. Inspect Stub Files:

   • Navigate to vendor/jetbrains/phpstorm-stubs/stubs/ and manually check files like:
     • stdlib.php (core PHP functions)
     • ext-redis.php (Redis extension)
     • framework/Illuminate/Support/Collection.php (Laravel)

3. Compare with Runtime:

   • Use php -r 'print_r(reflection_function("array_map"));' to compare stubs with actual runtime behavior.

4. Enable Debug Logging:

   • In PhpStorm, enable PHP Debug Log (Settings > PHP > Debug) to diagnose stub-related issues.

Extension Points

1. Custom Stub Overrides:

   • Override stubs by placing custom files in stubs/overrides/ (e.g., stubs/overrides/ext-redis.php).
   • Example override for Redis::connect():

     /**
      * @param string $host
      * @param int $port
      * @param float $timeout
      * @return Redis
      * @throws RedisException
      */
     function connect(string $host, int $port = 6379, float $timeout = 0.0): Redis {}
     

2. Contributing New Stubs:

   • Follow the contribution guide to add stubs for missing extensions.
   • Use docker compose run --rm test_runner php tests/run-stubs-parser.php to validate new stubs.

3. Generating Stubs for Custom Extensions:

   • Use reflection to generate stubs:

     php -r 'print_r(reflection_class("MyCustomClass"));' > stubs/ext-mycustom/MyCustomClass.php
     

   • Manually add PHPDoc annotations