Laravel Ide Helper Laravel Package

Getting Started

Minimal Steps

1. Installation:

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

2. First Use Case: Generate PHPDocs for Laravel Facades (creates _ide_helper.php):

   php artisan ide-helper:generate
   

3. Where to Look First:

   • Check the generated _ide_helper.php in your project root.
   • Review the published config (php artisan vendor:publish --provider="Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider" --tag=config) for customization.
   • Run php artisan ide-helper:models to generate PHPDocs for Eloquent models (requires a working DB connection).

Implementation Patterns

Core Workflows

1. Facades and Helpers:

   • Automatically generate PHPDocs for Laravel Facades (e.g., Auth, Cache) via ide-helper:generate.
   • Integrate with composer.json for auto-generation on dependency updates:

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

2. Eloquent Models:

   • Generate PHPDocs for models dynamically (columns, relations, getters/setters):

     php artisan ide-helper:models --write  # Writes to model files
     php artisan ide-helper:models --nowrite  # Generates _ide_helper_models.php
     

   • Use --write-mixin to avoid IDE duplicate warnings:

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

3. Custom Macros and Mixins:

   • Ensure type hints for macros (e.g., Str::macro('concat', function(string $str1, string $str2): string)).
   • Regenerate helpers after adding new macros:

     php artisan ide-helper:generate
     

4. Fluent Methods (Migrations):

   • Enable support for fluent method chains (e.g., $table->string()->nullable()):

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

   • Regenerate helpers:

     php artisan ide-helper:generate
     

5. PhpStorm Meta Files:

   • Generate meta files for container instances (e.g., factories):

     php artisan ide-helper:meta
     

   • Publish the meta file for IDE integration:

     php artisan vendor:publish --provider="Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider" --tag=meta
     

Integration Tips

• CI/CD Pipelines: Run ide-helper:generate in CI to ensure PHPDocs are up-to-date before merging.
• Team Onboarding: Commit _ide_helper.php and _ide_helper_models.php to version control (exclude from .gitignore).
• IDE-Specific Configs:
  • PhpStorm: Enable "Store PHP language level metadata in..." in Settings > Languages & Frameworks > PHP.
  • VSCode: Use the "PHP Intelephense" extension with ide-helper support enabled.

Gotchas and Tips

Pitfalls

1. Database Connection Required:

   • ide-helper:models fails if the default DB connection is misconfigured. Use -M for SQLite:

     php artisan ide-helper:models -M
     

2. Real-Time Facades:

   • Real-time facades (e.g., Route::get()) require prior usage to generate cache files in storage/framework/cache. Regenerate helpers after triggering them.

3. Duplicate PHPDocs:

   • Writing directly to models (--write) may cause conflicts with existing PHPDocs. Use --reset to overwrite:

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

4. Custom Relationships:

   • Non-standard relationships (e.g., hasManyThrough) require config definitions:

     'additional_relation_types' => [
       'hasManyThroughCustom' => \Custom\HasManyThrough::class,
     ],
     

5. IDE Caching:

   • Clear IDE caches (e.g., PhpStorm: File > Invalidate Caches) after regenerating helpers.

Debugging

• Missing Facade Methods:

  • Check config/ide-helper.php for facades overrides or missing class mappings.
  • Verify the facade’s underlying class exists (e.g., Auth → Illuminate\Auth\AuthManager).

• Model PHPDocs Not Updating:

  • Ensure --write or --nowrite is used correctly. Reset with --reset if needed.
  • Check for ignored models in config:

    'ignored_models' => [App\IgnoredModel::class],
    

• Fluent Methods Not Recognized:

  • Confirm include_fluent is true in config and regenerate helpers.

Extension Points

1. Model Hooks:

   • Extend generation with custom logic via ModelHookInterface:

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

   • Register in config/ide-helper.php:

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

2. Custom Generics:

   • Disable generics annotations (e.g., Collection<User>) for older IDEs:

     'use_generics_annotations' => false,
     

3. Excluding Magic Methods:

   • Disable auto-generated where* methods or *_count properties:

     'write_model_magic_where' => false,
     'write_model_relation_count_properties' => false,
     

4. Helper File Naming:

   • Customize output filenames in config:

     'filename' => 'custom_ide_helper.php',
     'models_filename' => 'custom_models_helper.php',
     

Pro Tips

• Partial Generations:

  • Regenerate only models or facades as needed to save time:

    php artisan ide-helper:models App\Models\Post  # Single model
    php artisan ide-helper:generate --facades-only  # Facades only
    

• Git Ignore:

  • Add helper files to .gitignore if they’re auto-generated:

    /_ide_helper.php
    /_ide_helper_models.php
    

• IDE-Specific Annotations:

  • Use @method for custom query scopes:

    /**
     * @method static \Illuminate\Database\Eloquent\Builder<static>|Post published()
     */
    

• Performance:

  • Exclude large models or directories from generation to speed up runs:

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