Laminas Diactoros Laravel Package

Product Decisions This Supports

• Build vs. buy for HTTP plumbing. Diactoros gives us battle-tested PSR-7 message objects (Request, Response, ServerRequest, UploadedFile, Stream) and PSR-17 factories. The decision this informs is "do we write our own HTTP value objects?" — answer: no. We buy the primitives and spend engineering time on product logic.
• Whether to ship a framework-agnostic SDK/integration. If any roadmap item is a public PHP SDK, webhook receiver, or connector that must run outside Laravel (Symfony, Slim, Mezzio, custom PSR-15 stacks), standard interfaces are the differentiator. Diactoros lets us say "works anywhere PSR-7 works" instead of "Laravel only."
• Vendor/implementation selection among PSR-7 providers. Realistic shortlist is Diactoros, nyholm/psr7, and guzzlehttp/psr7. This assessment supports choosing Diactoros when we want the most feature-complete implementation (server-request-from-globals, uploaded-file handling, JSON responses) with heavy static-analysis QA; choosing Nyholm when we optimize strictly for footprint and speed.
• Unblocking third-party dependency adoption. Many packages we evaluate for OAuth2 servers, OpenAPI request validation, PSR-15 middleware, or HTTP signing require a PSR-7/PSR-17 implementation to be installed. This package is the enabler that turns "blocked on missing PSR implementation" into a one-line composer change.
• PHP version support matrix. Releases through 3.9.0 track PHP 8.1→8.5 and add HTTP/3 protocol version support. That directly feeds our "minimum supported PHP / upgrade timeline" roadmap decision.
• Test infrastructure decisions. Deterministic request/response fixtures and mockable uploaded files reduce flakiness in integration tests for file upload, header, and streaming features — a quality-cost lever, not just a library choice.
• Framework-boundary architecture. Whether we keep an internal seam (PSR-7 at the edges, Laravel Request/Response inside) rather than letting Illuminate\Http types leak into domain code. Diactoros makes that seam cheap to implement via symfony/psr-http-message-bridge.

When to Consider This Package

Adopt when:

• We need a PSR-7/PSR-17 implementation and we are already in, or comfortable with, the Laminas ecosystem (Mezzio, Laminas MVC, Laminas components elsewhere in the stack).
• We need the fuller feature surface: ServerRequestFactory::fromGlobals(), SAPI header discovery, UploadedFile semantics, JsonResponse, and stream handling — not just bare request/response objects.
• Our codebase is type-strict and static-analysis heavy; the project ships Psalm types, type coverage badges, and a Roave BC-check gate, which lowers the odds of silent breaking changes in minor releases.
• License hygiene matters and BSD-3-Clause is acceptable (it is, for essentially all commercial use).
• We are building something that must be portable across frameworks, or a library we publish.

Look elsewhere when:

• The product is a Laravel-only application with no SDK, no PSR-15 middleware, and no PSR-7-consuming dependencies. Illuminate\Http\Request/Response already covers it; adding Diactoros is indirection with no payoff.
• We only need a minimal PSR-7 implementation behind a PSR-18 client or psr/http-message bridge — nyholm/psr7 is smaller, faster to boot, and the more common pairing in Symfony/Laravel-adjacent stacks.
• Guzzle is already a dependency — guzzlehttp/psr7 avoids a second implementation and a second streaming model.
• We need an HTTP server, emitter, or PSR-15 dispatcher. Diactoros is messages only; we would still be buying laminas/laminas-httphandlerrunner or a dispatcher.
• Vendor concentration is a concern and we are deliberately standardizing on Symfony components; introducing a second ecosystem's conventions has a real cognitive and upgrade cost.
• Diligence flags: our dataset shows limited public dependent signal, so validate real adoption via Packagist install counts and transitive usage before treating it as the default.

How to Pitch It (Stakeholders)

To executives: This is a small, permissively licensed (BSD-3) library that gives us standard-shaped HTTP requests and responses — the same shape nearly every PHP framework and third-party API library already understands. Adopting it costs essentially nothing in licensing and lets us sell integrations and SDKs to customers who are not on Laravel, which widens our addressable market. Maintenance risk is low: active releases, current PHP support (8.1 through 8.5), published security policy, and automated backwards-compatibility checks.

To engineering: It is the boring, correct choice for PSR-7/PSR-17 primitives — strictly typed, Psalm-annotated, conformance-tested, with server-request-from-globals and uploaded-file handling built in, so we are not reimplementing header parsing and stream semantics. It buys us compatibility with PSR-15 middleware, OAuth2 servers, OpenAPI validators, and any PSR-18 client work, and it gives us a clean seam between HTTP and domain code via the Symfony PSR bridge. Trade-off is footprint and a second ecosystem's conventions; if we are Laravel-only, or Guzzle or Nyholm is already in the tree, we should not add it. Recommendation: adopt behind an internal HTTP boundary, not scattered through controllers.