Http Adapter Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require egeloen/http-adapter
   

   (Note: This package is deprecated; prefer php-http/httplug for new projects.)

2. Basic Usage:

   use Ivory\HttpAdapter\Adapter\GuzzleAdapter;
   use GuzzleHttp\Client;
   use Psr\Http\Message\RequestInterface;
   
   $client = new Client();
   $adapter = new GuzzleAdapter($client);
   
   $request = $adapter->createRequest('GET', 'https://api.example.com/data');
   $response = $adapter->sendRequest($request);
   

3. First Use Case: Replace Laravel’s native HTTP client (e.g., Http::get()) with this adapter for cross-adapter compatibility:

   $adapter = new GuzzleAdapter(new Client());
   $response = $adapter->sendRequest($adapter->createRequest('GET', 'https://api.example.com'));
   $body = (string) $response->getBody();
   

Implementation Patterns

Core Workflows

1. Adapter Selection:

   • Choose an adapter based on project needs (e.g., GuzzleAdapter for modern APIs, CurlAdapter for legacy systems).
   • Example:

     $adapter = new CurlAdapter(); // For PHP’s built-in cURL
     

2. PSR-7 Compliance:

   • Leverage PSR-7 interfaces (RequestInterface, ResponseInterface) for consistency:

     $request = $adapter->createRequest('POST', '/endpoint')
         ->withHeader('Content-Type', 'application/json')
         ->withBody(\GuzzleHttp\Psr7\stream_for(json_encode(['key' => 'value'])));
     

3. Event-Driven Extensions:

   • Wrap adapters with EventDispatcherHttpAdapter to hook into lifecycle events:

     use Ivory\HttpAdapter\EventDispatcherHttpAdapter;
     use Symfony\Component\EventDispatcher\EventDispatcher;
     
     $dispatcher = new EventDispatcher();
     $eventAdapter = new EventDispatcherHttpAdapter($adapter, $dispatcher);
     
     // Add subscribers (e.g., logging, caching)
     $dispatcher->addSubscriber(new \Ivory\HttpAdapter\Event\Subscriber\LoggerSubscriber());
     

4. Parallel Requests:

   • Use MultiHttpAdapter for concurrent requests:

     $multiAdapter = new MultiHttpAdapter([$adapter1, $adapter2]);
     $responses = $multiAdapter->sendRequests([$request1, $request2]);
     

Laravel Integration

• Service Provider: Bind adapters to Laravel’s container in AppServiceProvider:

  public function register()
  {
      $this->app->singleton('guzzle.adapter', function () {
          return new GuzzleAdapter(new \GuzzleHttp\Client());
      });
  }
  

• Facade Wrapper: Create a facade for cleaner syntax:

  // app/Facades/HttpAdapter.php
  namespace App\Facades;
  use Ivory\HttpAdapter\Adapter\GuzzleAdapter;
  use Illuminate\Support\Facades\Facade;
  
  class HttpAdapter extends Facade
  {
      protected static function getFacadeAccessor() { return 'guzzle.adapter'; }
  }
  

  Usage:

  $response = HttpAdapter::get()->sendRequest(HttpAdapter::get()->createRequest('GET', '/'));
  

• Middleware: Extend Laravel’s HTTP client middleware to use this adapter:

  // app/Http/Middleware/HttpAdapterMiddleware.php
  public function handle($request, Closure $next)
  {
      $adapter = app('guzzle.adapter');
      $response = $adapter->sendRequest($adapter->createRequest(
          $request->method(),
          $request->fullUrl()
      ));
      return response($response->getBody(), $response->getStatusCode());
  }
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • This package is deprecated. Migrate to php-http/httplug for long-term support.
   • Workaround: Use this only for legacy projects or as a stopgap.

2. Adapter-Specific Quirks:

   • Guzzle: Requires guzzlehttp/guzzle (v3–v6 supported). Ensure version compatibility.
   • cURL: May need curl PHP extension enabled. Test with:

     if (!extension_loaded('curl')) {
         throw new \RuntimeException('cURL extension required for CurlAdapter');
     }
     

   • React: Requires react/http and async handling. Not ideal for synchronous Laravel routes.

3. Event Dispatcher Overhead:

   • Event listeners add latency. Disable unnecessary subscribers in production:

     $dispatcher->removeSubscriber($loggerSubscriber); // Disable logging in prod
     

4. PSR-7 Compliance:

   • Some adapters (e.g., FileGetContentsAdapter) may not fully support PSR-7. Validate responses:

     if (!$response instanceof \Psr\Http\Message\ResponseInterface) {
         throw new \RuntimeException('Adapter returned non-PSR-7 response');
     }
     

Debugging Tips

1. Logging Events:

   • Use the LoggerSubscriber to debug request/response cycles:

     $dispatcher->addSubscriber(new LoggerSubscriber(new \Monolog\Logger('http')));
     

   • Check logs for malformed requests or missing headers.

2. Retry Logic:

   • Configure the RetrySubscriber to handle transient failures:

     $retrySubscriber = new RetrySubscriber();
     $retrySubscriber->setMaxRetries(3);
     $dispatcher->addSubscriber($retrySubscriber);
     

3. Cookie Management:

   • Use CookieSubscriber to persist cookies across requests:

     $cookieJar = new \Ivory\HttpAdapter\Event\Cookie\CookieJar();
     $dispatcher->addSubscriber(new CookieSubscriber($cookieJar));
     

4. Performance:

   • For high-load systems, avoid MultiHttpAdapter with many concurrent requests (risk of resource exhaustion).
   • Benchmark adapters (e.g., GuzzleAdapter vs. CurlAdapter) using:

     $start = microtime(true);
     $adapter->sendRequest($request);
     echo "Time: " . (microtime(true) - $start) . "s";
     

Extension Points

1. Custom Adapters:

   • Implement Ivory\HttpAdapter\Adapter\HttpAdapterInterface for proprietary HTTP clients:

     class CustomAdapter implements HttpAdapterInterface
     {
         public function sendRequest(RequestInterface $request) { ... }
         public function createRequest($method, $uri, array $headers = []) { ... }
     }
     

2. Event Subscribers:

   • Create custom subscribers for domain-specific logic (e.g., API rate limiting):

     class RateLimitSubscriber implements SubscriberInterface
     {
         public static function getSubscribedEvents()
         {
             return [Events::REQUEST_CREATED => 'onRequestCreated'];
         }
     
         public function onRequestCreated(RequestCreatedEvent $event) { ... }
     }
     

3. Middleware Integration:

   • Chain Laravel middleware with adapter events:

     $dispatcher->addSubscriber(new class implements SubscriberInterface {
         public static function getSubscribedEvents() { return [Events::REQUEST_CREATED => 'addAuthHeader']; }
     
         public function addAuthHeader(RequestCreatedEvent $event) {
             $event->getRequest()->withHeader('Authorization', 'Bearer ' . auth()->token());
         }
     });
     

4. Testing:

   • Mock adapters in PHPUnit:

     $mockAdapter = $this->createMock(HttpAdapterInterface::class);
     $mockAdapter->method('sendRequest')->willReturn(new \GuzzleHttp\Psr7\Response(200));
     $eventAdapter = new EventDispatcherHttpAdapter($mockAdapter, new EventDispatcher());