Psr 18 Guzzle Adapter Laravel Package

Technical Evaluation

Architecture Fit

• PSR-18 Standardization: Perfectly aligns with Laravel’s growing adoption of PSR standards (e.g., PSR-7 for HTTP messages, PSR-15 for middleware). Enables seamless integration with Laravel’s built-in HTTP client (v8+) or third-party PSR-18 consumers like spatie/laravel-http-client.
• Decoupling Strategy: Ideal for Laravel applications transitioning from Guzzle to a more modular HTTP layer, especially in microservices or API-heavy architectures. Reduces vendor lock-in by abstracting Guzzle behind a standardized interface.
• Testability: Significantly improves unit/integration testing by allowing mocking of ClientInterface (e.g., with Mockery or PHPUnit), isolating HTTP dependencies from business logic.
• Laravel Synergy: Works harmoniously with Laravel’s service container, facades, and DI system. Can be layered alongside Laravel’s native Http client for mixed-stack applications.

Integration Feasibility

• Laravel Compatibility:
  • Service Container: Trivial to bind the adapter as a singleton or context-bound instance in Laravel’s container.
  • Facades: Can extend Laravel’s Http facade or create a dedicated PSR-18 facade (e.g., Psr18::get()) for consistency.
  • Legacy Code: Minimal refactoring required for existing Guzzle usage, as the adapter wraps Guzzle’s API.
• Dependency Risks:
  • Guzzle Versioning: Tested with Guzzle v7+; compatibility with Guzzle v8+ (used in Laravel v10+) should be verified. Potential for deprecation warnings if Guzzle evolves beyond PSR-18’s scope.
  • PSR-18 Gaps: Missing PSR-17 (MessageFactoryInterface) support may require manual handling of request/response creation in some edge cases.
• Performance: Negligible overhead (~0–1% latency increase per request), as the adapter is a thin wrapper around Guzzle.

Technical Risk

• Low to Medium Risk:
  • Adapter Limitations: Not all Guzzle features (e.g., event system, TransferStats) are exposed via PSR-18. Teams relying on these may need custom wrappers or middleware.
  • Middleware Translation: Guzzle middleware (e.g., retry, logging) must be reimplemented as PSR-15 handlers, adding complexity.
  • Laravel-Specific Quirks: Potential conflicts if mixing this adapter with Laravel’s native Http client (e.g., duplicate bindings). Requires clear naming conventions (e.g., psr18.client vs. http.client).
• Mitigation Strategies:
  • Feature Gap Analysis: Audit Guzzle-specific features before adoption to identify custom middleware needs.
  • Gradual Rollout: Start with non-critical HTTP services to validate the adapter’s behavior.
  • Fallback Mechanism: Provide a getGuzzleClient() method in the adapter for unsupported use cases.

Key Questions

1. Strategic Alignment:
   • Does the team have a long-term goal to adopt PSR-18 across the stack, or is this a short-term Guzzle compatibility layer?
   • Will this enable migration to other PSR-18 clients (e.g., php-http/guzzle7-adapter) in the future?
2. Feature Parity:
   • Are there Guzzle-specific features (e.g., async requests, event listeners) that cannot be replaced with PSR-18 alternatives?
   • How will middleware (e.g., retry, auth) be handled if not natively supported by PSR-18?
3. Laravel Integration:
   • Should the adapter replace Laravel’s built-in Http client entirely, or coexist with it (e.g., for legacy code)?
   • Will this require custom facades or helper methods to maintain developer ergonomics?
4. Testing Impact:
   • How will existing Guzzle-based tests (e.g., mocking GuzzleHttp\Client) be updated to use ClientInterface?
   • Are there integration tests for HTTP-dependent workflows (e.g., webhooks) that need adaptation?
5. Performance Sensitivity:
   • Are there high-throughput endpoints where Guzzle’s performance characteristics (e.g., connection pooling) are critical?
   • Has the adapter been benchmarked in Laravel’s specific context (e.g., with Http client middleware)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Service Container: Leverage Laravel’s DI system to bind the adapter as a singleton or context-specific instance. Example:

    $this->app->bind(\Psr\Http\Client\ClientInterface::class, function ($app) {
        return new GuzzleAdapter(
            new \GuzzleHttp\Client($app['config']['http.client'])
        );
    });
    

  • Config Integration: Extend Laravel’s config/http.php to include PSR-18-specific settings (e.g., default options, middleware).
  • Facades: Create a custom facade (e.g., Psr18) to mirror Laravel’s Http facade:

    facade_root('Psr18', 'App\Facades\Psr18Facade');
    

    // App\Facades\Psr18Facade.php
    public static function get($uri, array $options = [])
    {
        return app(\Psr\Http\Client\ClientInterface::class)
            ->sendRequest(new \GuzzleHttp\Psr7\Request('GET', $uri, [], $options));
    }
    

• Non-Laravel PHP:
  • Use with standalone DI containers (e.g., PHP-DI, Symfony DI) or manually instantiate the adapter.

Migration Path

1. Assessment Phase:
   • Audit all Guzzle usage in the codebase (e.g., via grep or static analysis tools like PHPStan).
   • Identify critical features (e.g., middleware, async requests) that may require custom handling.
2. Incremental Adoption:
   • Step 1: Dependency Injection Bind the adapter in AppServiceProvider and update constructors/services to accept ClientInterface.

     // Before
     public function __construct(GuzzleHttp\Client $client) { ... }
     
     // After
     public function __construct(\Psr\Http\Client\ClientInterface $client) { ... }
     

   • Step 2: API Layer Refactor Replace Guzzle method calls (e.g., $client->request()) with PSR-18 equivalents (e.g., $client->sendRequest()). Use IDE refactoring tools (e.g., PHPStorm’s "Rename" or "Change Signature") to automate this.
   • Step 3: Middleware Migration Convert Guzzle middleware to PSR-15 handlers. Example:

     // Guzzle Middleware (Before)
     $stack->push(Middleware::retry($retryConfig));
     
     // PSR-15 Middleware (After)
     $handler = new \League\Pipeline\Pipeline([
         new RetryMiddleware($retryConfig),
     ]);
     

   • Step 4: Testing Updates Replace Guzzle-specific test doubles with ClientInterface mocks:

     // Before
     $mock = $this->createMock(GuzzleHttp\Client::class);
     
     // After
     $mock = $this->createMock(\Psr\Http\Client\ClientInterface::class);
     

3. Backward Compatibility:
   • Use adapter methods to expose Guzzle-specific functionality when needed:

     public function getGuzzleClient(): GuzzleHttp\Client
     {
         return $this->adapter->getClient();
     }
     

   • Gradually deprecate direct Guzzle usage via Laravel’s deprecated() helper.

Compatibility

• Guzzle Versions:
  • Tested: Guzzle v7+ (as of 2026). Verify compatibility with Guzzle v8+ (used in Laravel v10+) by checking for breaking changes in:
    • Request/response handling (PSR-7 compliance).
    • Middleware API (e.g., onPrepare vs. PSR-15).
  • Mitigation: Pin Guzzle to a specific minor version (e.g., ^8.0) to avoid surprises.
• PSR-18 Compliance:
  • Adheres to ClientInterface, RequestInterface, and ResponseInterface.
  • Gaps: Missing PSR-17 (MessageFactoryInterface) support. Workaround:

    use GuzzleHttp\Psr7\Factory\Psr17Factory;
    $request = (new Psr17Factory())->createRequest('GET', 'https://example.com');
    

• Laravel-Specific:
  • No Conflicts: The adapter and Laravel’s Http client can coexist if bound to different container keys (e.g., psr18.client vs. http.client).
  • Middleware Stack: Ensure PSR-15 middleware integrates with Laravel’s middleware pipeline (e.g., via Illuminate\Pipeline\Pipeline).

Sequencing

1. **