Swoole Ide Helper Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require eaglewu/swoole-ide-helper --dev
   

   Run the publish command to generate IDE helper files:

   php artisan swoole-ide-helper:generate
   

   This creates bootstrap/cache/swoole-ide-helper.php (or your configured cache path).

2. First Use Case

   • Open a PHP file where you use Swoole classes (e.g., Swoole\Server, Swoole\Coroutine).
   • Type Swoole\ and press Ctrl+Space (or your IDE's autocomplete shortcut).
   • Verify methods like start(), on(), or coroutine() appear with proper signatures.

3. Where to Look First

   • Check config/swoole-ide-helper.php for customization (e.g., cache path, excluded classes).
   • Review bootstrap/cache/swoole-ide-helper.php to inspect generated stubs.
   • Refer to the Swoole PHP extension docs for missing methods not auto-generated.

Implementation Patterns

Workflow Integration

1. Autocomplete in Swoole Projects

   • Use alongside phpstorm.meta.php or phpDocumentor for hybrid IDE support.
   • Example: Autocomplete Swoole\Server->on('request', ...) with parameter hints for $request, $response.

2. CI/CD Pipeline

   • Add to your CI script to ensure IDE helpers are regenerated before merging:

     php artisan swoole-ide-helper:generate --force
     

   • Commit the generated file to version control (or exclude it with .gitignore).

3. Custom Swoole Extensions

   • Extend the helper for your custom Swoole classes:

     // config/swoole-ide-helper.php
     'classes' => [
         'App\\Swoole\\CustomServer' => [
             'methods' => [
                 'customMethod' => ['return' => 'void', 'params' => []],
             ],
         ],
     ];
     

   • Regenerate helpers after updates:

     php artisan swoole-ide-helper:generate
     

4. Laravel-Swoole Integration

   • Pair with beberlei/assert or spatie/laravel-swoole for type safety in async routes:

     // Route with Swoole coroutine
     Swoole\Coroutine::create(function () {
         $user = User::find(1); // IDE hints for DB methods
     });
     

Gotchas and Tips

Pitfalls

1. Cache Invalidation

   • Issue: Stale stubs after Swoole version upgrades.
   • Fix: Use --force to regenerate:

     php artisan swoole-ide-helper:generate --force
     

   • Tip: Add a post-update hook in composer.json:

     "scripts": {
         "post-update-cmd": "php artisan swoole-ide-helper:generate --force"
     }
     

2. IDE-Specific Quirks

   • PhpStorm: May require manual mapping for Swoole\* classes in Settings > Languages & Frameworks > PHP > Include.
   • VSCode: Ensure the PHP Intelephense extension is configured to scan bootstrap/cache/.

3. Missing Methods

   • Issue: Some Swoole methods (e.g., undocumented or dynamic) won’t appear.
   • Workaround: Manually add stubs to config/swoole-ide-helper.php or use PHPDoc comments:

     /**
      * @method static void customMethod(string $param)
      */
     class_alias('Swoole\\Server', 'Swoole\\ServerWithCustomMethods');
     

4. Performance

   • Issue: Large projects may slow down IDE on helper generation.
   • Fix: Exclude unused classes in config:

     'exclude' => [
         'Swoole\\Process\\Pool',
         'Swoole\\Http\\Server',
     ],
     

Debugging Tips

1. Verify Generation Check the generated file for errors:

   grep -E "parse error|syntax error" bootstrap/cache/swoole-ide-helper.php
   

2. Log Missing Classes Enable debug mode in config:

   'debug' => true,
   

   Check logs for unresolved classes during generation.

3. Fallback to PHPDoc For unsupported methods, use inline PHPDoc:

   /** @var \Swoole\Server $server */
   $server->on('request', function ($request, $response) {
       /** @var \Swoole\Http\Request $request */
       $request->get['id']; // IDE hints work here
   });
   

Extension Points

1. Custom Class Mappings Override default Swoole classes in config:

   'classes' => [
       'Swoole\\Server' => [
           'file' => 'custom/Swoole/Server.php', // Path to your stub file
       ],
   ],
   

2. Dynamic Method Generation Use a service provider to inject runtime stubs:

   // app/Providers/SwooleIdeHelperServiceProvider.php
   public function boot()
   {
       $helper = new \Eaglewu\SwooleIdeHelper\Generator();
       $helper->addClass('App\\Swoole\\Custom', [
           'methods' => ['dynamicMethod' => ['return' => 'mixed']],
       ]);
       $helper->generate();
   }
   

3. Integration with Laravel Mix Auto-generate helpers on npm run dev:

   // webpack.mix.js
   mix.scripts(['resources/js/app.js'], 'public/js')
       .exec('php artisan swoole-ide-helper:generate');