Http Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sabre/http:~5.0.0
   

   Add to composer.json under require.

2. First Use Case:

   use Sabre\HTTP\Sapi;
   
   // Initialize request (run once per request lifecycle)
   $request = Sapi::getRequest();
   
   // Initialize response
   $response = new Sabre\HTTP\Response();
   $response->setStatus(200);
   $response->setBody('Hello, World!');
   
   // Send response (run once per request lifecycle)
   Sapi::sendResponse($response);
   

3. Key Files to Review:

   • vendor/sabre/http/src/ (Core classes)
   • examples/ (Practical use cases like async clients, reverse proxies)

Implementation Patterns

Core Workflow

1. Request Handling:

   // Dependency-injected handler
   public function handle(Sabre\HTTP\RequestInterface $request) {
       $method = $request->getMethod();
       $path = $request->getPath();
       $data = $request->getPostData();
   
       // Process...
   }
   

2. Response Construction:

   $response = new Sabre\HTTP\Response();
   $response->setStatus(201);
   $response->setHeader('Content-Type', 'application/json');
   $response->setBody(json_encode(['success' => true]));
   

3. Middleware Pattern (Decorator-based):

   // Auth decorator
   class AuthRequestDecorator extends Sabre\HTTP\RequestDecorator {
       public function isAuthenticated() {
           return $this->getHeader('Authorization') !== null;
       }
   }
   
   // Usage
   $request = new AuthRequestDecorator(Sapi::getRequest());
   

Integration Tips

• Laravel Service Provider:

  public function register() {
      $this->app->singleton(Sabre\HTTP\RequestInterface::class, function() {
          return Sapi::getRequest();
      });
  }
  

• API Client Wrapper:

  class ApiClient {
      private $client;
  
      public function __construct() {
          $this->client = new Sabre\HTTP\Client();
      }
  
      public function get(string $url) {
          $request = new Sabre\HTTP\Request('GET', $url);
          return $this->client->send($request);
      }
  }
  

• Async Requests:

  $client = new Sabre\HTTP\Client();
  for ($i = 0; $i < 10; $i++) {
      $client->sendAsync(
          new Sabre\HTTP\Request('GET', 'https://api.example.com/data'),
          function($response) { /* Success */ },
          function($error) { /* Error */ }
      );
  }
  $client->wait();
  

Gotchas and Tips

Pitfalls

1. Stream Handling:

   • getBodyAsString() may only work once (streams are consumed).
   • Use getBodyAsStream() for repeated access.

2. Header Case Sensitivity:

   • Headers are case-insensitive in retrieval (getHeader()), but case is preserved in storage (setHeader()).

3. POST Data:

   • setPostData() must be called before getPostData() if you need to modify POST data.

4. Async Client:

   • Always call wait() to ensure all async requests complete.
   • Error callbacks receive the raw cURL error, not a Response object.

5. Decorator Order:

   • Decorators wrap behavior from innermost to outermost. Ensure decorators are applied in the correct order.

Debugging Tips

• Inspect Headers:

  print_r($request->getHeaders());
  

• Log Request/Response:

  $client->on('afterRequest', function($request, $response) {
      file_put_contents(
          'debug.log',
          "Request: {$request->getMethod()} {$request->getUrl()}\n".
          "Response: {$response->getStatus()}\n"
      );
  });
  

• Mocking for Tests:

  $mockRequest = $this->createMock(Sabre\HTTP\RequestInterface::class);
  $mockRequest->method('getPath')->willReturn('/test');
  

Extension Points

1. Custom Request/Response:

   class CustomRequest extends Sabre\HTTP\Request {
       public function getCustomHeader() {
           return $this->getHeader('X-Custom');
       }
   }
   

2. Event Listeners:

   • Extend Sabre\HTTP\Client with custom events (e.g., beforeRequest for logging).

3. Reverse Proxy:

   • Use setBaseUrl() to handle path rewriting:

     $request->setBaseUrl('/api/v1');
     $subRequest->setUrl('https://backend.example.com' . $request->getPath());
     

4. HTTP Version:

   • Explicitly set setHttpVersion('1.1') if working with HTTP/1.1-specific features.

Config Quirks

• PHP Version Compatibility:
  • Use ~5.0.0 for PHP 7.4+ or ~4.2.0 for PHP 5.4+.
• Sapi::getRequest():
  • Only call this once per request lifecycle (caches superglobals).
• Body Handling:
  • For large bodies, prefer streams (setBody(fopen('file.txt', 'r'))).