Plugins Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require php-http/plugins
   

   (Note: This package is deprecated as of v1.1.0. Most functionality has been merged into php-http/client-common and standalone plugins like php-http/cache-plugin. Use these instead for new projects.)

2. Basic Usage (Legacy)

   use Http\Client\Common\PluginClient;
   use Http\Client\Common\Plugin\PluginInterface;
   
   $client = new \GuzzleHttp\Client();
   $pluginClient = new PluginClient($client);
   
   // Add a plugin (e.g., logging)
   $pluginClient->addPlugin(new class implements PluginInterface {
       public function handleRequest($request, callable $next) {
           // Modify request
           return $next($request->withHeader('X-Legacy', 'Plugin'));
       }
   });
   
   $response = $pluginClient->sendRequest($request);
   

3. First Use Case (Migrate to Modern Alternatives)

   • Logging: Use php-http/logger-plugin.

     composer require php-http/logger-plugin
     

     use Http\Client\Common\Plugin\LoggerPlugin;
     use Http\Client\Common\PluginClient;
     
     $client = new PluginClient(new \GuzzleHttp\Client());
     $client->addPlugin(new LoggerPlugin());
     

   • Caching: Use php-http/cache-plugin.

     composer require php-http/cache-plugin
     

     use Http\Client\Common\Plugin\CachePlugin;
     use Http\Client\Common\PluginClient;
     
     $client = new PluginClient(new \GuzzleHttp\Client());
     $client->addPlugin(new CachePlugin());
     

Implementation Patterns

Middleware Composition (Legacy)

• Stackable Plugins: Plugins execute in reverse order of addition (LIFO).

  $client->addPlugin(new AuthPlugin());
  $client->addPlugin(new LoggingPlugin());
  

  (Requests pass through LoggingPlugin first, then AuthPlugin.)

• Conditional Logic: Use closures for dynamic behavior.

  $client->addPlugin(new class implements PluginInterface {
      public function handleRequest($request, callable $next) {
          if ($request->getUri()->getPath() === '/admin') {
              return $next($request->withHeader('X-Admin', 'true'));
          }
          return $next($request);
      }
  });
  

Modern Integration (Recommended)

1. PSR-18 Clients with Plugins Use httplug/httplug for PSR-18 compliance:

   use Http\Client\Common\PluginClient;
   use Http\Client\Common\Plugin\PluginInterface;
   use Http\Client\Common\Plugin\CachePlugin;
   use Http\Client\Common\Plugin\LoggerPlugin;
   use Http\Client\Common\Plugin\StopwatchPlugin;
   
   $client = new PluginClient(new \GuzzleHttp\Client());
   $client->addPlugin(new CachePlugin());
   $client->addPlugin(new LoggerPlugin());
   $client->addPlugin(new StopwatchPlugin());
   

2. Laravel Integration (v8+) Bind plugins via service provider:

   use Http\Client\Common\PluginClient;
   use Illuminate\Support\ServiceProvider;
   
   class HttpPluginServiceProvider extends ServiceProvider {
       public function register() {
           $this->app->singleton('http.client', function ($app) {
               $client = new PluginClient(new \GuzzleHttp\Client());
               $client->addPlugin(new \Http\Client\Common\Plugin\LoggerPlugin());
               return $client;
           });
       }
   }
   

3. Facade Usage (Laravel)

   use Illuminate\Support\Facades\Http;
   
   // Modern Laravel HTTP client (v8+) with middleware
   Http::withOptions(['debug' => true])->get('https://api.example.com');
   

Common Workflows (Modern)

• Request Transformation: Use standalone plugins (e.g., php-http/stopwatch-plugin for timing).
• Response Handling: Decorate responses with plugins like LoggerPlugin.
• Retry Logic: Use php-http/retry-plugin.

Gotchas and Tips

Deprecation and Migration

• Avoid php-http/plugins: This package is fully deprecated. Migrate to:
  • php-http/client-common (core plugins).
  • Standalone plugins (e.g., logger, cache, stopwatch).
• PSR-18 Compliance: New projects should use PSR-18 clients (e.g., guzzlehttp/guzzle v7+ with PSR-7).
• Laravel v8+: Prefer Laravel’s built-in Http client with middleware over legacy plugins.

Debugging (Legacy)

• Plugin Order: Middleware executes in reverse order of addition. Test with dd($request) in each plugin.
• Immutability: Plugins must return new MessageInterface instances (avoid direct mutations).

  // ❌ Avoid
  $request->withHeader('X-Foo', 'bar');
  
  // ✅ Correct
  $request = $request->withHeader('X-Foo', 'bar');
  

Performance

• Legacy Warning: Avoid heavy logic in plugins (executes on every request).
• Modern Optimization: Use caching plugins (e.g., CachePlugin) for static endpoints.

Extension Points (Modern)

• Custom Plugins: Implement PluginInterface for reusable logic:

  use Http\Client\Common\Plugin\PluginInterface;
  
  class RateLimitPlugin implements PluginInterface {
      public function handleRequest($request, callable $next) {
          // Rate-limiting logic
          return $next($request);
      }
  }
  

• Error Handling: Wrap $next($request) in try-catch for graceful failures.

Laravel-Specific Tips

• Use Laravel’s HTTP Client: For new projects, leverage:

  Http::withOptions(['timeout' => 5])->post('/api', $data);
  

• Middleware Stack: Register middleware via app/Http/Kernel.php:

  protected $middleware = [
      \App\Http\Middleware\TransformResponse::class,
  ];
  

• Service Container: Bind plugins as singletons:

  $this->app->singleton(\Http\Client\Common\Plugin\LoggerPlugin::class);