Psr7 Plus Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require swow/psr7-plus
   

   Ensure swow/psr7 is also installed (dependency) for runtime performance.

2. First Use Case Replace PSR-7 HTTP message objects with strongly-typed Swow variants in a Laravel request handler:

   use Swow\Psr7Plus\Message\ServerRequest;
   use Swow\Psr7Plus\Message\Response;
   
   // In a middleware or controller:
   $request = new ServerRequest($psr7Request); // Wraps PSR-7 request
   $response = new Response(); // Strongly-typed response
   $response->withHeader('X-Swow', 'Powered');
   return $response;
   

3. Key Entry Points

   • Swow\Psr7Plus\Message: Core interfaces (ServerRequest, Response, Stream).
   • Swow\Psr7Plus\WebSocket: WebSocket-specific interfaces (Frame, Server).
   • Swow\Psr7Plus\Factory: PSR-17 factory implementations (e.g., StreamFactory).

   Check the Swow PSR-7+ Docs for type hints and method signatures.

Implementation Patterns

Workflows

1. Middleware Integration Use the package to enforce type safety in middleware:

   public function handle(ServerRequest $request, RequestHandlerInterface $next): Response {
       $request = $request->withAttribute('swow', true); // Strongly-typed attribute
       return $next($request);
   }
   

2. WebSocket Handling Leverage Swow’s WebSocket interfaces for async operations:

   use Swow\Psr7Plus\WebSocket\Frame;
   use Swow\Psr7Plus\WebSocket\Server;
   
   $server = new Server($socket);
   $server->on('message', fn(Frame $frame) => echo $frame->getData());
   

3. Stream Optimization Use Swow\Psr7Plus\Message\Stream for high-performance I/O:

   $stream = new Stream(fopen('php://memory', 'r+'));
   $stream->write('Swow-powered'); // Non-blocking with Swow’s async runtime
   

Integration Tips

• Laravel HTTP Kernel: Extend Illuminate\Http\Request/Response with Swow’s interfaces via traits or decorators. Example:

  class SwowRequest extends ServerRequest implements HttpRequestContract { ... }
  

• Async Routing: Combine with Swow’s HTTP server for async request handling:

  $server = new Swow\Http\Server();
  $server->route('/swow', fn(ServerRequest $req) => new Response('Async!'));
  

• PSR-17 Factories: Replace Laravel’s default factories with Swow’s PSR-17 implementations for consistency:

  $factory = new Swow\Psr7Plus\Factory\StreamFactory();
  $stream = $factory->createStreamFromFile('/path/to/file');
  

Gotchas and Tips

Pitfalls

1. Runtime Dependency: Swow requires the Swow extension (PHP 8.0+). Ensure it’s installed and enabled:

   pecl install swow
   

   Debug Tip: Check php -m | grep swow for missing extension.

2. Type Mismatches: Swow’s interfaces extend PSR-7 but add strict typing. Avoid mixing with vanilla PSR-7 objects:

   // ❌ Avoid:
   $swowRequest = new ServerRequest(new \GuzzleHttp\Psr7\Request()); // May lose Swow features
   

3. WebSocket State: Swow’s WebSocket Frame objects are stateful. Reuse frames carefully in async contexts.

Debugging

• Stream Errors: Swow streams throw Swow\Exception\StreamException. Wrap operations in try-catch:

  try {
      $stream->write($data);
  } catch (StreamException $e) {
      report($e); // Log via Laravel’s error handler
  }
  

• Header Validation: Swow enforces strict header case sensitivity (RFC 7230). Use withAddedHeader() for case-insensitive additions:

  $response->withAddedHeader('content-type', 'text/plain'); // Preserves case
  

Extension Points

1. Custom Factories: Extend Swow\Psr7Plus\Factory\StreamFactory to add Laravel-specific logic:

   class LaravelStreamFactory extends StreamFactory {
       public function createStreamFromFile(string $filename): Stream {
           $stream = parent::createStreamFromFile($filename);
           $stream->setLaravelCache(); // Hypothetical method
           return $stream;
       }
   }
   

2. Middleware Decorators: Decorate Laravel’s Request/Response with Swow’s interfaces:

   class SwowRequestDecorator implements HttpRequestContract {
       protected ServerRequest $swowRequest;
   
       public function __construct(ServerRequest $request) {
           $this->swowRequest = $request;
       }
   
       public function header($key, $default = null) {
           return $this->swowRequest->getHeaderLine($key) ?? $default;
       }
       // Delegate other methods...
   }
   

3. Async Event Handling: Use Swow’s coroutines to integrate with Laravel’s events:

   use Swow\Coroutine;
   
   Coroutine::create(function() {
       event(new SwowEvent());
       // Non-blocking event dispatch
   });