Phpstorm Stubs Laravel Package

Getting Started

Minimal Steps

1. Installation: Add to your Laravel project’s composer.json under require-dev:

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

   Run composer update jetbrains/phpstorm-stubs.

2. PhpStorm Configuration:

   • Open Settings > Languages & Frameworks > PHP.
   • Under PHP Runtime, ensure the Default stubs path points to:

     vendor/jetbrains/phpstorm-stubs/stubs
     

   • Click Apply and OK.

3. First Use Case:

   • Open a Laravel controller or service file.
   • Test autocompletion for built-in PHP functions (e.g., array_map, json_decode).
   • Verify type hints appear for extension methods (e.g., Redis::command()).

Implementation Patterns

Usage Patterns

1. Leveraging Stubs for Framework Code:

   • Laravel Collections: Use @method annotations in custom classes to mirror Illuminate\Support\Collection stubs.

     /**
      * @method static self make(array $attributes)
      */
     class CustomCollection extends Collection {}
     

   • Service Providers: Stub bind()/singleton() methods for better IDE support:

     /**
      * @method $this bind(string $abstract, $concrete = null, bool $shared = false)
      */
     class AppServiceProvider extends ServiceProvider {}
     

2. Extension-Specific Workflows:

   • Redis: Autocomplete for RedisArray and RedisCluster methods:

     $redis->$ // Triggers completion for 'hget', 'lpush', etc.
     

   • PDO: Type hints for prepared statements:

     $stmt = $pdo->prepare("SELECT * FROM users WHERE id = ?");
     $stmt->bindParam(1, $id, \PDO::PARAM_INT); // $id gets type hinting
     

3. Integration with Static Analysis:

   • Psalm/PhpStan: Use stubs to resolve ambiguous types (e.g., array vs. array<string>).

     // Without stubs: Psalm may warn about mixed return types.
     // With stubs: IDE shows `@return array<int, string>` for `array_column()`.
     

4. Custom Stub Generation:

   • For unsupported extensions (e.g., ext-mongodb), generate stubs using:

     docker run --rm -v $(pwd):/stubs jetbrains/phpstorm-stubs:latest generate ext-mongodb
     

   • Place generated stubs in stubs/ext-mongodb/ and reference them in PhpStorm.

5. Per-Project Configuration:

   • Override default stubs for specific projects via .idea/phpstorm.stubs.paths.xml:

     <component name="ProjectStubPaths">
       <stub-paths>
         <stub-path>vendor/jetbrains/phpstorm-stubs/stubs</stub-path>
         <stub-path>stubs/custom-extensions</stub-path>
       </stub-paths>
     </component>
     

Integration Tips

• Laravel Valet/Laragon: Ensure stubs are included in shared paths to avoid per-project setup.
• Docker Dev Containers: Mount stubs into the container:

  COPY vendor/jetbrains/phpstorm-stubs/stubs /stubs
  

  Configure PhpStorm to use /stubs as the stubs path.
• CI/CD: Exclude stubs from deployment (they’re dev-only):

  # .gitignore
  /vendor/jetbrains/phpstorm-stubs/
  

Gotchas and Tips

Pitfalls

1. Stub Version Mismatch:

   • Issue: Using stubs for PHP 8.2 in a PHP 8.1 project causes errors (e.g., array_unpack not found).
   • Fix: Pin the stub version to match your PHP version:

     "jetbrains/phpstorm-stubs": "2022.3" // For PHP 8.1
     

2. IDE Caching:

   • Issue: Changes to stubs aren’t reflected until PhpStorm caches are invalidated.
   • Fix: Run File > Invalidate Caches / Restart or toggle Settings > Appearance & Behavior > System Settings > Clear Cache.

3. Custom Extensions:

   • Issue: Non-PECL extensions (e.g., php-amqplib) lack stubs.
   • Fix: Generate stubs manually or use community-provided stubs (e.g., php-amqplib-stubs).

4. False Positives in Static Analysis:

   • Issue: Stubs may conflict with Psalm/PhpStan’s type systems (e.g., @return array vs. @return list<int>).
   • Fix: Use @template or @mixin annotations to align stubs with static analysis tools:

     /**
      * @template TKey of array-key
      * @template TValue
      * @template-extends \ArrayObject<TKey, TValue>
      */
     class ArrayObject {}
     

5. Performance in Large Projects:

   • Issue: Slow indexing in monorepos with thousands of stubs.
   • Fix: Exclude unused stubs via .idea/phpstorm.stubs.exclude:

     vendor/jetbrains/phpstorm-stubs/stubs/ext-curl
     vendor/jetbrains/phpstorm-stubs/stubs/ext-soap
     

Debugging

1. Missing Method Signatures:

   • Debug: Check if the stub file exists for the extension (e.g., stubs/ext-redis.php).
   • Action: Regenerate stubs or report missing stubs to JetBrains YouTrack.

2. Incorrect Type Hints:

   • Debug: Compare stub annotations with PHP’s official docs (e.g., json_decode()).
   • Action: Override stubs locally or contribute fixes via PR.

3. PhpStorm Not Picking Up Stubs:

   • Debug: Verify the stub path in Settings > PHP > PHP Runtime > Advanced settings.
   • Action: Restart PhpStorm or manually sync stubs via File > Sync Project with Gradle (if using Gradle).

Extension Points

1. Custom Stub Templates:

   • Extend stubs for internal frameworks using @mixin:

     /**
      * @mixin \Illuminate\Support\Collection
      */
     class ApiResourceCollection extends Collection {}
     

2. Stub Prioritization:

   • Control stub precedence via phpstorm.meta.php:

     namespace PHPSTORM_META {
         override(\App\Models\User::find(0), map([
             'return' => '@return \App\Models\User'
         ]));
     }
     

3. CI/CD Integration:

   • Add a pre-commit hook to validate stubs against Psalm:

     ./vendor/bin/psalm --init --no-cache --output-format=json | jq '.errors[] | select(.message | contains("Stub mismatch"))'
     

4. Community Contributions:

   • Submit missing stubs via GitHub Issues.
   • Follow the contribution guide for PECL extensions.

Pro Tips

• Laravel-Specific:

  • Use stubs to enable method chaining in custom Eloquent models:

    /**
     * @method static self whereIn(string $column, array $values)
     */
    class User extends Model {}
    

  • Stub Artisan commands for better autocompletion:

    /**
     * @method static void make(string $command, array $parameters = [])
     */
    class Artisan {}
    

• Performance:

  • For monorepos, use PhpStorm’s "Project-Level Stubs" to avoid duplicating stubs across projects.

• Future-Proofing:

  • Monitor JetBrains YouTrack for upcoming PHP 9.0+ stubs.