Psr7 Laravel Package

Getting Started

Install the package via Composer:

composer require ringcentral/psr7

Begin by leveraging its immutable PSR-7 implementations—especially ServerRequest, Request, Response, Stream, and Uri. Start with constructing a simple request or response:

use RingCentral\Psr7\Request;
use RingCentral\Psr7\Response;

$request = new Request('GET', 'https://api.example.com/users');
$response = new Response(200, ['Content-Type' => 'application/json'], '{"status":"ok"}');

For common use cases (e.g., handling incoming HTTP requests in a standalone script or middleware stack), parse a raw request or use ServerRequestFactory::fromGlobals() if combined with a compatible factory (note: this package does not include factories—see “Gotchas” below).

Implementation Patterns

• Middleware Integration: Use with PSR-15/PSR-15-compatible routers or frameworks (e.g., Slim, Expressive, custom middleware stacks). Pass ServerRequestInterface objects through middleware pipelines, modifying via fluent setters:

  $request = $request->withQueryParams(['page' => 2])
                     ->withHeader('X-Custom', 'value');
  

• Stream Handling: Efficiently manage bodies—especially for large payloads—using Stream objects:

  $stream = new Stream('php://temp', 'r+');
  $stream->write(json_encode($data));
  $response = new Response(200, [], $stream);
  

• URI Manipulation: Build or modify URIs immutably:

  $uri = (new Uri('https://api.example.com'))
          ->withPath('/users')
          ->withQuery('limit=10');
  $request = $request->withUri($uri);
  

• Factory Pattern: Since ringcentral/psr7 only implements interfaces, pair it with a factory like nyholm/psr7-factory or laminas/laminas-diactoros for ServerRequest creation from globals:

  $factory = new Nyholm\Psr7\Factory\Psr17Factory();
  $request = $factory->createServerRequest('GET', '/api');
  

Gotchas and Tips

• No Built-in Factories: This package only provides classes—not factories. You’ll need an external factory (e.g., nyholm/psr7-factory, slim/php-http-psr7 for Slim) to create ServerRequestInterface instances from $_SERVER, $_GET, etc.
• Immutable Operations Are Crucial: Always assign results of with*() methods (e.g., $req = $req->withHeader(...)); forgetting to reassign is a common source of silent bugs.
• Stream Reusability: Streams created from resources (e.g., fopen(...)) may not be rewound automatically. Call $stream->rewind() after writes or before reads if needed.
• Date/Time Headers: PSR-7 requires Date headers to be in RFC 7231 format. Use \DateTime::RFC7231 when setting them manually.
• Performance Consideration: For high-throughput apps, benchmark ringcentral/psr7 against alternatives (e.g., nyholm/psr7 or slim/psr7); while lightweight, some implementations are faster for large payloads or high-frequency operations.
• PHP Version Compatibility: Requires PHP ≥7.0, but verify against your runtime environment—deprecated features (e.g., PEAR::HTTP_Request2) may conflict if mixed with older code.