Stream Laravel Package

Product Decisions This Supports

• Build vs. buy for a stream abstraction layer. Hoa\Stream is a ready-made object-oriented façade over PHP's native stream layer: a base Stream class plus capability interfaces (In, Out, Path, Bufferable, Lockable, Pointable, Statable, Selectable), a custom-stream-wrapper registration mechanism, and filter/context/listener helpers. That interface surface is a useful spec for scoping an internal abstraction — even if we build our own, this tells us what capabilities a stream wrapper must advertise.
• Feature scoping for protocol/wrapper work. If a roadmap item needs a custom scheme (s3://, encrypted://, memory://, log://) or a composable filter chain (compression, encoding, hashing on read/write), this package defines the shape of that work and the edge cases (seekability, locking, stat, select) we'd otherwise discover late.
• Testability decisions. The IStream capability split makes it straightforward to substitute in-memory or fixture-backed streams in unit tests instead of touching the real filesystem or network — a legitimate argument for introducing an abstraction here, not necessarily this one.
• Dependency-risk and SBOM triage. Archived since 2017-era releases with no maintained upstream is a standing risk item. Decision: identify and quarantine any transitive usage, and add a policy line ("no new dependencies on archived packages") to the engineering standards.
• Architecture Decision Record content. This is a strong "considered and rejected" citation — evidence that the abstraction was evaluated, why native wrappers plus modern alternatives win, and what capability gaps (if any) remain.
• Not a roadmap investment. No feature bet should be gated on this package. If it is already in the tree, the funded work is removal, not extension.

When to Consider This Package

Consider it when:

• You are maintaining an existing Hoa-based system and need to keep a pinned, vendored copy working — treat it as frozen infrastructure, not a platform.
• You need reference material for designing your own stream abstraction: read the interface decomposition and wrapper registration pattern, then write ~200 lines of your own typed, PHP 8-tested equivalent.
• You are on a legacy PHP 5.x/7.0-era runtime where native stream wrapper ergonomics are genuinely painful and the code is already isolated behind an internal adapter.
• You need a capability matrix (seekable? lockable? statable?) to reason about heterogeneous storage backends before choosing a library.

Look elsewhere when:

• Greenfield work, or anything on PHP 8+ — no maintained releases, no compatibility guarantees, no security response path.
• You need HTTP message factories → PSR-17/PSR-7 implementations (e.g. nyholm/psr7) with a client such as Guzzle.
• You need filesystem/storage abstraction across local, S3, FTP → league/flysystem.
• You need async or non-blocking I/O → ReactPHP or Amp stream components.
• You need sockets, TLS, or connection management → native sockets, or a maintained socket/HTTP-client package.
• Your team has no appetite to fork and own unmaintained code. Forking is the only honest way to adopt this; if that's off the table, so is the package.

Adoption criteria (all must hold): existing usage in a system we own · code isolated behind an internal adapter interface · PHP version pinned and tested · no unforked CVE exposure · a named owner · a dated plan to replace or explicitly accept the risk.

How to Pitch It (Stakeholders)

For executives (one paragraph): Hoa\Stream is a small, well-designed PHP library that wraps the language's file, socket, and stream handling in a clean object-oriented API. It is also archived, with no release since 2017, modest community traction (~300 stars), and no active maintainer. My recommendation is no new adoption: the strategic value is a design reference, not a dependency. There is no commercial upside to standardizing on unmaintained code, and the downside is a permanent, unbudgeted maintenance obligation and a security-response gap. If any current system depends on it, I'd like a small, time-boxed remediation item to isolate or replace it — measured in days, not a project.

For engineering leads: Treat it as a frozen reference implementation, not a dependency. What's worth stealing is the design: the split of stream behaviour into narrow capability interfaces, the wrapper registration pattern, and the filter/context separation. What's not worth taking is the code — it predates modern PHP typing, has no CI against current runtimes, and gives us no upstream to escalate to. The replacement path is short: native stream_wrapper_register behind our own interface for custom schemes, league/flysystem where the need is really storage abstraction, and PSR-17 factories where the need is HTTP. Where the need is only test doubles for I/O, a small in-house adapter gets us the same benefit with full ownership and a test suite we control.

Ask: (1) approve "no new dependencies on archived packages" as a standing rule; (2) authorize a scoped inventory of existing usage; (3) if usage exists, fund a replace-or-isolate ticket with a hard deadline rather than an open-ended support commitment.