Laravel Ide Helper Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev barryvdh/laravel-ide-helper
   

2. Generate Facade PHPDocs (core use case):

   php artisan ide-helper:generate
   

   This creates _ide_helper.php in your project root, enabling IDE autocompletion for Laravel facades.

3. Verify IDE Integration:

   • In PhpStorm: Go to Settings > Languages & Frameworks > PHP > PHP Doc Parsers and ensure the _ide_helper.php file is included.
   • In VSCode: Install the "PHP Intelephense" extension and configure it to parse the helper file.

First Use Case

Debugging a Facade Method:

Route::get('/posts', function () {
    return Post::where('published', true)->get(); // Autocomplete works for `where()` and `get()`
});

Without the helper, IDEs show generic Builder methods. After running ide-helper:generate, you get full method signatures (e.g., where(string $column, mixed $operator = null, mixed $value = null)).

Implementation Patterns

Core Workflows

1. Facade Autocompletion (Daily Use)

   • Run php artisan ide-helper:generate after dependency updates or when adding new facades.
   • Automate via composer.json:

     "scripts": {
         "post-update-cmd": [
             "@php artisan ide-helper:generate"
         ]
     }
     

2. Model PHPDocs (Development Workflow)

   • Generate docs for all models:

     php artisan ide-helper:models --write
     

   • Target specific models:

     php artisan ide-helper:models App\Models\User App\Models/Post
     

   • Use mixins (avoids IDE duplicates):

     php artisan ide-helper:models --write-mixin
     

3. Custom Facades/Real-Time Facades

   • For real-time facades (e.g., Route::cache()), trigger the facade first, then regenerate:

     php artisan route:cache
     php artisan ide-helper:generate
     

4. Macros and Mixins

   • Ensure type hints in macros for autocompletion:

     Str::macro('concat', function(string $str1, string $str2): string { ... });
     

   • Regenerate after adding macros:

     php artisan ide-helper:generate
     

Integration Tips

• Database Connection: Use -M for SQLite if your default connection fails:

  php artisan ide-helper:models -M
  

• Exclude Models: Ignore specific models via config or CLI:

  php artisan ide-helper:models --ignore="App\Models\Test*"
  

• Custom Directories: Scan non-standard model paths:

  php artisan ide-helper:models --dir="app/Domain/Models"
  

• Fluent Methods: Enable for migrations:

  // config/ide-helper.php
  'include_fluent' => true,
  

  Then regenerate.

Gotchas and Tips

Pitfalls

1. Real-Time Facades Not Included

   • Issue: Real-time facades (e.g., cached routes) won’t appear until triggered.
   • Fix: Run the facade method first, then regenerate:

     php artisan route:cache
     php artisan ide-helper:generate
     

2. Duplicate PHPDocs in Models

   • Issue: Writing docs directly to models (--write) may cause duplicates.
   • Fix: Use --write-mixin to separate docs into _ide_helper_models.php.

3. Database Connection Errors

   • Issue: ide-helper:models fails if the default connection is misconfigured.
   • Fix: Use -M for SQLite or specify a working connection in .env.

4. Macros Without Type Hints

   • Issue: Macros without return/type hints won’t generate PHPDocs.
   • Fix: Add type hints:

     Str::macro('slugify', function(string $str): string { ... });
     

5. IDE Not Picking Up Helpers

   • PhpStorm: Ensure _ide_helper.php is in the "PHP Doc Parsers" list.
   • VSCode: Add to intelephense.environment.php.projects in settings:

     {
       "projects": ["your-project-path/_ide_helper.php"]
     }
     

Debugging Tips

• Verify Generated Files: Check _ide_helper.php for missing methods/facades.
• Clear IDE Cache: Restart your IDE or invalidate caches after regenerating.
• Check Config Overrides: Published config (config/ide-helper.php) may override defaults.

Extension Points

1. Custom Model Hooks

   • Add logic via ModelHookInterface for unsupported model features:

     class CustomHook implements ModelHookInterface {
         public function run(ModelsCommand $command, Model $model) {
             $command->setProperty('custom_field', 'string', false, false, 'Custom value');
         }
     }
     

   • Register in config/ide-helper.php:

     'model_hooks' => [CustomHook::class],
     

2. Custom Relationship Types

   • Define non-standard relationships:

     'additional_relation_types' => [
         'customHasMany' => \Your\CustomHasMany::class,
     ],
     

3. Generics Annotations (Laravel 9+)

   • Enable for PhpStorm 2022.3+:

     'use_generics_annotations' => true,
     

   • Example output:

     @property-read Collection<User> $users
     

4. Exclude Magic Methods

   • Disable auto-generated where* methods:

     'write_model_magic_where' => false,
     

Pro Tips

• Partial Regeneration: Use --only to target specific facades:

  php artisan ide-helper:generate --only="Auth,Cache"
  

• CI/CD Integration: Add to your test suite to catch PHPDoc regressions:

  php artisan ide-helper:generate && git diff --exit-code
  

• Performance: Exclude unused facades in config to speed up generation:

  'facades' => [
      'Auth' => Illuminate\Support\Facades\Auth::class,
      // Exclude others if not used
  ],