Http Message Laravel Package

Product Decisions This Supports

• Standardize the HTTP message layer, not the framework. berlioz/http-message is a framework-free PSR-7/PSR-17 implementation (HttpFactory implements all six PSR-17 factory interfaces). It lets us make a portability decision — "our request/response objects are PSR-compliant regardless of whether we run Laravel, Symfony, Slim, or raw PHP" — rather than a framework-vendor decision.
• Build vs. buy vs. adopt for HTTP plumbing. This package is a candidate to fill the "adopt/assemble" slot in a build-vs-buy evaluation for request/response factories, stream handling, and body parsing. It removes the need to hand-roll PSR-17 glue for SDKs, API clients, and internal libraries.
• Shared-library and SDK roadmap. Because it has zero framework dependencies, it can underpin internal client libraries, service SDKs, and API gateway middleware that must run inside and outside Laravel (via PSR bridges) without pulling in a full framework.
• Test infrastructure as a product. PSR-17 factories give us deterministic request/response fixtures for contract tests, integration tests, and mock HTTP clients — a direct enabler for CI reliability and API contract testing across teams.
• Body parsing and stream strategy. Pluggable body parsers and specialized streams map to concrete feature decisions: multipart uploads, JSON payload handling, large-payload streaming, and content negotiation. Choosing a message layer with pluggable parsers avoids re-platforming later.
• Interop and migration de-risking. If the roadmap includes phasing between frameworks or offering a headless API alongside a web app, committing to PSR-7/PSR-17 at the boundary keeps the migration path open.

When to Consider This Package

Consider it when:

• We need a PSR-7/PSR-17 implementation with no framework coupling, usable in shared libraries, CLI tools, workers, and tests alike.
• We want pluggable body parsers and specialized streams rather than a bare message object — i.e., the package should carry some of the HTTP semantics, not just data structures.
• The stack is PHP >= 8.2 and already PSR-oriented (PSR-4/7/11/12/14/16/17/18 alignment is documented).
• We are wiring an HTTP client (PSR-18) or middleware pipeline and need the message side to stay provider-agnostic.
• We want to abstract our own HTTP interface and keep this as a swappable implementation behind it.

Look elsewhere when:

• Maturity and community support are the deciding criteria. With ~1 GitHub star, 0 dependents, and a single maintainer, this is not a safe critical-path dependency. Mainstream alternatives (nyholm/psr7, guzzlehttp/psr7, laminas/laminas-diactoros) dominate for a reason.
• Minimum footprint matters — if we only need message objects, a lighter, widely-used PSR-7 implementation is the lower-risk choice.
• Laravel-native HTTP is required. For internal Laravel work, Illuminate\Http (requests/responses) is the natural fit; this package adds value only at the interop boundary.
• We need vendor SLAs, long-term support guarantees, or a security response process — there is no commercial backing here.
• We can't afford a bus-factor of one and have no capacity to vendor/fork the code if maintenance lapses.

How to Pitch It (Stakeholders)

To executives: This is a cheap, MIT-licensed interoperability layer, not a platform bet. It lets our services and shared libraries exchange HTTP messages in a standards-compliant way, so we aren't locked into one framework's request/response objects. The strategic value is optionality — cheaper framework migrations, reusable SDKs, and consistent test fixtures. The strategic risk is provenance: it's a very small, single-maintainer project. Recommendation: treat it as an evaluation/pilot candidate behind our own interface, not a critical-path dependency, and keep a mainstream PSR-7 implementation as the fallback. Cost of trying it is low; cost of depending on it blindly is not.

To engineering: Framework-free PSR-7/PSR-17 implementation; one factory class covers all six PSR-17 interfaces via traits, plus pluggable body parsers and specialized streams. It's PHP 8.2+, MIT, and lives in the wider Berlioz monorepo (so upstream releases move in step with the framework). Two asks before adoption: (1) wrap it behind an internal HttpMessageFactory port so we can swap to nyholm/psr7 with a one-line binding change, and (2) run it through our existing controller/middleware and client test suites for parity on streams, multipart bodies, and header edge cases.

Decision framing: Approve a time-boxed pilot in one internal library or SDK. Success criteria: passes parity tests, no stream/body-parser regressions, and the internal abstraction holds. If it fails or maintenance stalls, the fallback is a drop-in mainstream implementation at effectively zero product cost.