Laminas Diactoros Laravel Package

Getting Started

Start by installing the package via Composer:

composer require laminas/laminas-diactoros

Begin with ServerRequestFactory::fromGlobals() to convert PHP superglobals into a PSR-7 ServerRequestInterface. This is the most common first step for middleware-based applications (e.g., in frameworks like Expressive/Laminas API Tools or customSlim/Expressive-style stacks). Immediately after, create a Response to build your output:

use Laminas\Diactoros\ServerRequestFactory;
use Laminas\Diactoros\Response;

$request  = ServerRequestFactory::fromGlobals();
$response = new Response();
$response->getBody()->write('Hello world');

Use the README’s code samples for quick reference—especially the Server-Side Applications section.

Implementation Patterns

• Marshaling incoming requests: Use ServerRequestFactory::fromGlobals() to standardize $_SERVER, $_GET, $_POST, $_COOKIE, $_FILES → ServerRequestInterface. The factory intelligently parses cookies from headers when no explicit $cookies array is provided.
• Immutable message chaining: PSR-7 objects are immutable. Always assign results of with*() methods:

  $request = $request->withAddedHeader('X-Request-ID', uniqid());
  $response = $response->withStatus(201);
  

• Stream handling: Use $response->getBody() for writing content. Supports resource streams (fopen()), php://memory, and custom StreamInterface implementations.
• Request/Response serialization: Leverage Request\Serializer and Response\Serializer for debugging or logging (e.g., in middleware or CLI jobs):

  $logData = [
      'request'  => Request\Serializer::toString($request),
      'response' => Response\Serializer::toString($response),
  ];
  

• Array-based serialization: Use ArraySerializer::toArray() for structured logging—especially useful in structured JSON logs or telemetry tools (e.g., Sentry, Datadog).
• Middleware compatibility: Works natively with PSR-15 (and de-facto PSR-15-style middleware). Combine with laminas/laminas-httphandlerrunner for production-ready request handling (replacing the now-deprecated Server class).

Gotchas and Tips

• Deprecated Server class: Do not use Laminas\Diactoros\Server for new work—it was deprecated in v1.8. Prefer laminas/laminas-httphandlerrunner (RequestHandlerRunner).
• Immutable confusion: A common mistake is forgetting to capture the result of with*() methods. Always assign:

  // ❌ Wrong: $request unchanged  
  $request->withHeader(...);  
  // ✅ Correct  
  $request = $request->withHeader(...);
  

• Cookie normalization: PHP mangles cookie names (e.g., foo.bar → foo_bar). Use fromGlobals() without $cookies to pull cookies from the raw Cookie header instead.
• Body stream reuse: The StreamInterface is a resource handle—don’t try to write to it after it’s been consumed (e.g., after calling getContents() once). Clone if needed:

  $clonedBody = $request->getBody()->detach() ? $request->getBody()->__clone() : $request->getBody();
  

• Testing tip: In unit tests, avoid fromGlobals(); instead, manually construct ServerRequest or Request instances with new + with*() methods for full control over test context.
• Middleware stack safety: When passing ServerRequest/Response between middleware layers, remember immutability means each handler receives the original object unless you return a modified response.