Plugins Laravel Package

Technical Evaluation

Architecture Fit

• Deprecation Impact: The package is now officially deprecated in favor of php-http/client-common and standalone plugins (e.g., php-http/logger-plugin, php-http/cache-plugin). This eliminates redundancy with Laravel’s built-in Http client and aligns with modern PHP-HTTP standards.
• Modernization Opportunity: Migration to php-http/client-common (or symfony/http-client) removes legacy baggage and leverages actively maintained libraries. Laravel’s Http facade already uses symfony/http-client under the hood, reducing the need for this package entirely.
• Legacy Use Cases: Only relevant for:
  • Projects locked into this package’s middleware stack (e.g., custom plugins not yet ported to php-http).
  • Monolithic apps where incremental migration is preferred over big-bang replacement.

Integration Feasibility

• Breaking Change: The package’s core functionality is split into separate packages, requiring:
  • Replacement of PluginClient with Http\Client\Common\PluginClient (from php-http/client-common).
  • Individual installation of plugins (e.g., php-http/logger-plugin).
• Laravel Compatibility:
  • No native integration: Still requires manual wiring (e.g., decorating Laravel’s HttpClient).
  • Symfony Alignment: symfony/http-client (used by Laravel) is now the recommended path, as it’s natively supported and actively maintained.
• Dependency Risks:
  • Version Conflicts: php-http/client-common may conflict with Laravel’s bundled guzzlehttp/guzzle or symfony/http-client.
  • Plugin Gaps: Some legacy middlewares may not have direct equivalents in php-http ecosystem.

Technical Risk

• Deprecation Certainty: High—no future updates expected. Migration is mandatory for long-term viability.
• Migration Complexity:
  • Plugin-by-Plugin Replacement: Each middleware must be mapped to its php-http equivalent (e.g., LoggerPlugin → php-http/logger-plugin).
  • Custom Middleware: Non-standard plugins may require rewriting or replacement with Laravel’s middleware or symfony/http-client extensions.
• Testing Overhead:
  • Validate all HTTP clients (Guzzle, Symfony) behave identically post-migration.
  • Test middleware order in Laravel’s stack (e.g., auth, retries, logging).
• Performance Regression: Decorator patterns may introduce subtle overhead; benchmark against Laravel’s native Http client.

Key Questions

1. Why migrate now?
   • Avoid technical debt from using a deprecated package. The php-http ecosystem is the de facto standard for PHP HTTP clients.
2. Which plugins are critical?
   • Audit usage of PluginClient middlewares and prioritize migration of high-impact ones (e.g., auth, retries).
3. Can Laravel’s Http client replace this entirely?
   • Yes, for most use cases. Laravel’s Http facade already uses symfony/http-client, which supports plugins natively.
4. What’s the fallback if a plugin lacks an equivalent?
   • Implement custom middleware for Laravel’s Http client or use symfony/http-client directly with HttpClientInterface.
5. How will this affect CI/CD?
   • Update dependency checks to flag http-interop/http-client (deprecated) and enforce php-http/client-common or symfony/http-client.

Integration Approach

Stack Fit

• Target Use Cases:
  • Full Migration to php-http: Replace PluginClient with Http\Client\Common\PluginClient + individual plugins (e.g., CachePlugin, LoggerPlugin).
  • Laravel-Native Replacement: Use Laravel’s Http client (backed by symfony/http-client) with custom middleware or symfony/http-client plugins.
  • Legacy Plugin Preservation: For custom middlewares without php-http equivalents, rewrite them as Laravel middleware or symfony/http-client extensions.
• Avoid Use Cases:
  • New Projects: Use Laravel’s Http client or symfony/http-client directly.
  • Minimal Middleware Needs: Overkill for simple requests; prefer Laravel’s built-in middleware.

Migration Path

1. Assessment Phase:
   • Inventory all PluginClient usages and middlewares in the codebase.
   • Map legacy middlewares to php-http equivalents (see plugin migration guide).
   • Benchmark performance of symfony/http-client vs. current setup.
2. Phase 1: Dependency Replacement
   • Remove http-interop/http-client and add:

     composer require php-http/client-common php-http/logger-plugin php-http/cache-plugin
     

   • Or switch to symfony/http-client (recommended for Laravel):

     composer require symfony/http-client
     

3. Phase 2: Core Integration
   • Replace PluginClient with Http\Client\Common\PluginClient:

     use Http\Client\Common\PluginClient;
     use Http\Client\Common\Plugin\LoggerPlugin;
     use Http\Client\Common\Plugin\CachePlugin;
     use Http\Client\Common\Plugin\RetryPlugin;
     use Http\Client\Common\Plugin\HeaderAppendPlugin;
     use Http\Client\Common\Plugin\HeaderNormalizerPlugin;
     use Http\Client\Common\Plugin\BaseUriPlugin;
     use Http\Client\Common\Plugin\ExceptionPlugin;
     use Http\Client\Common\Plugin\TimeoutPlugin;
     use Http\Client\Common\Plugin\HistoryPlugin;
     use Http\Client\Common\Plugin\StatisticsPlugin;
     use Http\Client\Common\Plugin\BaseUrlPlugin;
     use Http\Client\Common\Plugin\ContentLengthPlugin;
     use Http\Client\Common\Plugin\RedirectPlugin;
     use Http\Client\Common\Plugin\StreamPlugin;
     
     $client = new PluginClient(
         new SymfonyClient(), // Laravel's HttpClient instance
         [
             new LoggerPlugin(),
             new CachePlugin(),
             // ... other plugins
         ]
     );
     

   • Alternative (Laravel-Native): Use Laravel’s Http client with symfony/http-client plugins:

     use Symfony\Contracts\HttpClient\HttpClientInterface;
     use Symfony\Component\HttpClient\RetryMiddleware;
     
     $client = \Http\Client\Common\PluginClient::create(
         HttpClientInterface::create(),
         [new RetryMiddleware()]
     );
     

4. Phase 3: Endpoint Migration
   • Replace Http::get() calls with the new client:

     $response = $client->sendRequest(new Request('GET', 'https://api.example.com'));
     

   • For Laravel’s Http facade, use middleware or symfony/http-client directly:

     $response = Http::withOptions(['http_client' => $client])->get('...');
     

5. Phase 4: Deprecation Cleanup
   • Remove http-interop/http-client from composer.json.
   • Update tests to use the new client.
   • Document the migration path for future developers.

Compatibility

• PHP Version: php-http/client-common supports PHP 7.4+ (aligns with Laravel 8+).
• Laravel Version:
  • Laravel 8+: Seamless integration with symfony/http-client.
  • Laravel 7: Possible with composer overrides for symfony/http-client.
• Plugin Compatibility:
  • 1:1 Equivalents: Most PluginClient middlewares have direct php-http counterparts (e.g., LoggerPlugin → php-http/logger-plugin).
  • Missing Plugins: Custom middlewares may need rewriting (e.g., as Laravel middleware or symfony/http-client extensions).
• Middleware Order:
  • Ensure plugin order matches Laravel’s middleware stack (e.g., auth before logging).
  • Use PluginClient::withConfig() to enforce order:

    $client = new PluginClient($baseClient, $plugins, $config);
    

Sequencing

1. Step 1: Dependency Update
   • Replace http-interop/http-client with php-http/client-common + required plugins.
2. Step 2: Container Binding
   • Bind the new client to Laravel’s container (e.g., in AppServiceProvider):

     $this->app->singleton('http.plugin_client', function ($app) {
         return new PluginClient(
             $app->make('http.client'), // Laravel's HttpClient
             [$app->make(LoggerPlugin::class)],
             new MessageFactory()
         );
     });
     

3. Step 3: Middleware Migration
   • Migrate one middleware at a time, testing each in isolation.