Laravel Actions Ide Helper Laravel Package

Getting Started

Install the package as a dev dependency:

composer require --dev wulfheart/laravel-actions-ide-helper

Run the Artisan command to generate IDE helper files:

php artisan ide-helper:actions

First Use Case: After installation, immediately generate IDE helpers for your existing app/Actions classes. This will enable autocompletion for:

• Action method signatures (parameters, return types)
• Dependency injection (e.g., Handle method parameters)
• IDE navigation within Action classes

Verify the generated stubs appear in bootstrap/cache/ide-helper-actions.php (or your configured cache path).

Implementation Patterns

Core Workflow

1. Development Setup:

   composer require --dev wulfheart/laravel-actions-ide-helper
   php artisan ide-helper:actions
   

   Add to composer.json for automatic regeneration:

   "scripts": {
       "post-autoload-dump": [
           "@php artisan ide-helper:actions"
       ]
   }
   

2. IDE Configuration (PHPStorm example):

   • Go to Settings > Languages & Frameworks > PHP > Stub files
   • Add path to bootstrap/cache/ide-helper-actions.php

3. Action Class Structure:

   namespace App\Actions;
   
   use App\Models\User;
   use Illuminate\Support\Facades\Log;
   
   class CreateUserAction
   {
       public function handle(string $name, string $email): User
       {
           // IDE will now show:
           // - $name and $email as parameters
           // - User as return type
           // - Method signature autocompletion
       }
   }
   

Integration Patterns

• Action Service Integration: When using ActionService, IDE helpers will autocomplete:

  $action = app(ActionService::class)
      ->run(new CreateUserAction(), [
          'name' => '', // Autocompleted as string
          'email' => '' // Autocompleted as string
      ]);
  

• Dependency Injection: For constructor-injected dependencies:

  class ProcessOrderAction
  {
      public function __construct(
          private readonly OrderRepository $orders,
          private readonly PaymentGateway $gateway
      ) {}
  
      public function handle(Order $order): void
      {
          // IDE shows $orders and $gateway as available
      }
  }
  

• Return Type Handling: Complex return types (collections, custom objects) are properly typed:

  public function getUsers(): Collection
  public function validateRequest(Request $request): void
  

Advanced Patterns

• Custom Action Locations: Override default scan paths via config (config/ide-helper-actions.php):

  'paths' => [
      app_path('Actions'),
      app_path('Domain/Actions'),
  ],
  

• Excluding Actions: Use skip config to exclude specific actions:

  'skip' => [
      'App\Actions\Deprecated\*',
  ],
  

• CI/CD Integration: Add to GitHub Actions or GitLab CI:

  - name: Generate IDE Helpers
    run: php artisan ide-helper:actions
  

Gotchas and Tips

Common Pitfalls

1. Missing Stub Files:

   • Cause: Artisan command not run or cache cleared
   • Fix: Run php artisan ide-helper:actions manually

2. IDE Not Recognizing Helpers:

   • Cause: IDE not configured to use stub files
   • Fix: Verify stub path in IDE settings (PHPStorm: Settings > PHP > Stub files)

3. Dependency Conflicts:

   • Cause: Version mismatch with lorisleiva/lody or phpdocumentor/reflection
   • Fix: Use composer why-not to resolve conflicts or lock versions

4. Actions Not Scanned:

   • Cause: Actions outside default app/Actions path
   • Fix: Configure custom paths in config/ide-helper-actions.php

5. Performance Issues:

   • Cause: Large number of Actions (>500)
   • Fix: Exclude unnecessary actions or run during build process

Debugging Tips

• Verify Generation:

  php artisan ide-helper:actions --verbose
  

  Check output for scanned files and any errors.

• Manual Stub Inspection: Open bootstrap/cache/ide-helper-actions.php to verify:

  // Should contain class definitions like:
  class_alias('App\Actions\CreateUserAction', 'App\Actions\CreateUserAction');
  

• IDE-Specific Issues:

  • PHPStorm: Ensure "Generate stubs on the fly" is disabled
  • VSCode: Use PHP Intelephense extension with stub file path

Configuration Quirks

• Cache Path: Defaults to bootstrap/cache/ide-helper-actions.php Override via config:

  'cache_path' => storage_path('framework/cache/ide-helpers.php'),
  

• File Naming: Generated file uses ide-helper-actions.php by default Customize via config:

  'filename' => 'actions-ide-helpers.php',
  

Extension Points

1. Custom Action Classes: Extend the helper to support custom Action implementations:

   // In ServiceProvider
   $this->app->bind('ide-helper-actions', function ($app) {
       return new CustomActionHelper();
   });
   

2. Pre/Post Generation Hooks: Add logic before/after generation:

   // config/ide-helper-actions.php
   'hooks' => [
       'pre_generate' => function () {
           // Custom logic
       },
       'post_generate' => function () {
           // Post-processing
       }
   ],
   

3. Custom Reflection: Override reflection logic for special cases:

   // In ServiceProvider
   $this->app->singleton('ide-helper-actions.reflection', function () {
       return new CustomReflectionService();
   });
   

Performance Optimization

• Exclude Test Actions:

  'skip' => [
      'tests/Actions/*',
  ],
  

• Parallel Generation: For large codebases, consider running in parallel:

  php artisan ide-helper:actions --parallel
  

• Cache Generated Files: Add to .gitignore to avoid committing:

  bootstrap/cache/ide-helper-actions.php
  

Laravel-Specific Tips

• Action Service Integration: When using ActionService, ensure your IDE is configured to recognize the service container resolution.

• Dynamic Actions: For dynamically resolved actions, regenerate helpers after adding new actions:

  php artisan ide-helper:actions --force
  

• Laravel 13+ Compatibility: If using Laravel 13+, ensure you're on v0.11.0+:

  composer require wulfheart/laravel-actions-ide-helper:^0.11