Php Amqp Stubs Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package to your composer.json:

   composer require empi89/php-amqp-stubs
   

   Ensure pdezwart/php-amqp is also installed (required dependency):

   composer require pdezwart/php-amqp
   

2. Purpose This package provides stubs (type hints) for php-amqp to enable static analysis tools (e.g., PHPStan, Psalm) and IDE autocompletion without requiring the php-amqp extension to be installed on your development machine.

3. First Use Case

   • Static Analysis: Run PHPStan with php-amqp stubs:

     vendor/bin/phpstan analyse --level=5 src/
     

   • IDE Autocomplete: Open a Laravel project in PhpStorm/VSCode—stubs will now provide method signatures, parameter hints, and error detection for php-amqp classes (e.g., AMQPConnection, AMQPChannel).

Implementation Patterns

Workflows

1. Development Without AMQP Extension

   • Use stubs in CI/CD pipelines where the php-amqp extension isn’t available (e.g., GitHub Actions).
   • Example .github/workflows/phpstan.yml:

     jobs:
       phpstan:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - run: composer install --prefer-dist
           - run: vendor/bin/phpstan analyse --level=5
     

2. Laravel Integration

   • Queue Workers: Leverage stubs to catch type mismatches in App\Jobs using php-amqp (e.g., AMQPQueue).

     use PhpAmqpLib\Connection\AMQPStreamConnection;
     use PhpAmqpLib\Message\AMQPMessage;
     
     public function handle()
     {
         $connection = new AMQPStreamConnection('localhost', 5672, 'user', 'pass');
         $channel = $connection->channel();
         $channel->queue_declare('jobs', false, true, false, false);
         $channel->basic_publish(new AMQPMessage('Hello AMQP!'), '', 'jobs');
     }
     

   • Service Providers: Use stubs to validate AMQP configurations in config/amqp.php:

     return [
         'host' => env('AMQP_HOST', 'localhost'), // IDE will hint `string` type
         'port' => env('AMQP_PORT', 5672),       // IDE will hint `int` type
     ];
     

3. Testing

   • Mock php-amqp in unit tests with stubs + Mockery:

     $mockConnection = Mockery::mock('overload:PhpAmqpLib\Connection\AMQPStreamConnection');
     $mockConnection->shouldReceive('channel')->andReturnSelf();
     

Integration Tips

• Composer Autoload: Ensure stubs are autoloaded by adding to composer.json:

  "autoload": {
      "psr-4": {
          "App\\": "src/"
      },
      "files": [
          "vendor/empi89/php-amqp-stubs/stubs.php" // Explicitly include stubs
      ]
  }
  

• IDE-Specific Setup:
  • PhpStorm: Mark vendor/empi89/php-amqp-stubs as "Sources Root" in project settings.
  • VSCode: Add to php.suggest.stubs in settings.json:

    "php.suggest.stubs": [
        "vendor/empi89/php-amqp-stubs/stubs.php"
    ]
    

Gotchas and Tips

Pitfalls

1. Stub vs. Runtime Mismatch

   • Issue: Stubs provide type hints, but runtime errors (e.g., AMQPConnection failing to connect) still occur if the php-amqp extension is missing.
   • Fix: Use if (extension_loaded('amqp')) checks or feature flags:

     if (!extension_loaded('amqp')) {
         throw new RuntimeException('php-amqp extension is required.');
     }
     

2. Outdated Stubs

   • Issue: Stubs may lag behind php-amqp updates, causing false positives in static analysis.
   • Fix: Update stubs manually or report issues to the package maintainer:

     composer update empi89/php-amqp-stubs
     

3. IDE False Positives

   • Issue: IDEs may flag stub-only methods (e.g., __toString()) as undefined.
   • Fix: Configure IDE to ignore stubs in analysis:
     • PhpStorm: Add @mixin annotations or suppress inspections for stub files.

Debugging

• Static Analysis Errors:
  • Run PHPStan with --error-format=github for actionable PR feedback:

    vendor/bin/phpstan analyse --error-format=github
    

• Runtime Debugging:
  • Use AMQPConnection::isConnected() to verify connections:

    $connection = new AMQPStreamConnection('localhost', 5672);
    if (!$connection->isConnected()) {
        throw new \RuntimeException('AMQP connection failed.');
    }
    

Extension Points

1. Custom Stubs

   • Extend stubs by creating a stubs.php file in your project:

     // Custom stub for a non-standard AMQP method
     class_alias('PhpAmqpLib\Connection\AMQPConnection', 'AMQPConnection');
     class AMQPConnection {
         public function customMethod() { /* ... */ }
     }
     

   • Reference it in composer.json under "autoload.files".

2. CI-Specific Configs

   • Use php-amqp stubs in Docker-based CI to avoid extension dependencies:

     # Dockerfile
     RUN pecl install amqp && docker-php-ext-enable amqp
     

     Or skip installation entirely and rely on stubs for static checks.

3. Laravel Queue Drivers

   • If using php-amqp as a Laravel queue driver, stubs help validate:
   • config/queue.php:

     'connections' => [
         'amqp' => [
             'driver' => 'amqp', // IDE hints: driver must be 'amqp'
             'host' => env('AMQP_HOST'),
             'queue' => 'laravel',
             'exchange_options' => ['name' => 'laravel', 'type' => 'direct'], // IDE hints: 'type' must be 'direct'|'fanout'|etc.
         ],
     ],