Hoa Protocol Laravel Package

Technical Evaluation

What it is. A fork of hoa/protocol — the Hoa Project's path/URI registry abstraction (roots + components, hoa:// style resource resolution) — with resolve() removed and a "Laravel-compatible" claim attached. Archiving status: yes. Stars: 0. Dependents: 0. License: BSD-3-Clause (permissive, commercially safe).

Architecture fit — poor. Laravel already owns path and resource resolution through base_path()/resource_path()/storage_path(), the Storage/Flysystem abstraction, and config-driven paths. Introducing a parallel registry means two sources of truth for where files live, which is a classic source of environment-specific bugs (local vs. Octane vs. container). Worse, removing resolve() strips the part of Hoa\Protocol that actually did something — walking and validating the path. What remains is a thin, string-keyed lookup that a nested config() array reproduces in ~30 lines with zero dependency risk.

Integration feasibility — technically trivial, strategically dubious. It is Composer-installable and PSR-4, but there is no service provider, no facade, no publishable config, and no published Laravel integration test. "Laravel-compatible" is a maintainer assertion, not a verified artifact. The only realistic adoption path is as a transitive substitution: something in your tree (e.g., hoa/stream, hoa/file) requires hoa/protocol and the upstream package is broken on your PHP version. That is a narrow, defensive use case, not a greenfield one.

Technical risk — high relative to value.

• Abandonment. Upstream Hoa has been unmaintained for years; this fork is itself archived. No security response, no PHP-version roadmap.
• Bus factor of one, with zero external validation (0 stars, 0 dependents means no observable production usage to learn from).
• Substitution mechanics are unverified. The critical unknown is whether it declares composer replace: hoa/protocol. Without that, Composer will happily install both and you get duplicate class definitions or a silent autoload race.
• Behavioral regression. Any transitive Hoa code that calls Protocol::resolve() will fatal. Removing a public method is a breaking change to the upstream contract, so "drop-in replacement" cannot be assumed.

Key questions to answer before any code is written.

1. Does the package declare replace/provide for hoa/protocol, and at what version constraint?
2. Which PHP versions and which Laravel majors are actually exercised in CI? Is there a test suite at all?
3. What in our dependency tree requires hoa/protocol today — and can that dependency be removed entirely instead?
4. Why was resolve() removed: a PHP 8 incompatibility, a security concern, or a Laravel path-root conflict? The answer determines whether the fix is upstreamable or permanent.
5. Why is the repository archived, and is the maintainer responsive to a security report?

Integration Approach

Stack fit. Marginal at best. Adopt only under one condition: a transitive Hoa dependency blocks a PHP or Laravel upgrade and no maintained alternative exists. Do not adopt it as a new abstraction layer for application paths — that is strictly negative value against config() + Storage.

Migration path (if the blocking condition is real).

1. Reproduce the failure in a throwaway branch with the exact PHP/Laravel matrix you run in production.
2. Prefer the least invasive fix in this order: (a) remove the Hoa dependency chain entirely, (b) patch upstream hoa/protocol via a Composer patch plugin, (c) substitute this fork.
3. If substituting, vendor the source into our own namespace rather than depending on an archived remote. It is a small library; internal ownership costs less than an unpatchable external dep flagged forever by SCA tooling.
4. Declare the replace in the root composer.json explicitly, and pin the exact commit — there will be no future releases to track.
5. Wrap the call sites behind a single internal adapter (one interface, one implementation) so the eventual swap to config() or Storage is a one-file change.

Compatibility. Verify against PHP 8.2/8.3/8.4 and the Laravel majors in support. Confirm no code path expects the hoa:// stream wrapper to be registered — with resolve() gone, that registration may or may not survive, and a missing wrapper fails at runtime, not at boot.

Sequencing. Week 1: dependency-tree audit and PoC. Week 2: internal fork + adapter + tests if the PoC is green; otherwise close the ticket as "not needed." Do not let this sit in a backlog as a half-adopted dependency.

Operational Impact

Maintenance. Archived means you inherit the maintenance burden on day one — there is no upstream to defer to. The code volume is small, so the recurring cost is mostly attention: PHP upgrade testing, security triage, and answering "why do we have this?" every time someone reads composer.json. Budget a few hours per PHP minor release, indefinitely.

Support. Effectively none. Zero stars and zero dependents means no community, no issue history to search, no Stack Overflow corpus. The escalation path for any defect terminates at your own team. For a package touching filesystem resolution — a common attack surface — the absence of a security response process is the material risk, not the code quality.

Scaling. Runtime performance is a non-issue: it is pure PHP string manipulation with negligible overhead, and it does not participate in request-path hot loops unless you invite it to. The scaling concern is organizational — every additional abandoned dependency raises the cost of the next framework or language upgrade, and this one buys almost nothing in return.

Failure modes to watch.

• Silent path mismatches between the registry and Laravel's real roots, surfacing as "file not found" only in staging or under Octane's long-lived workers.
• Composer class collisions if replace is absent and both packages land.
• Transitive callers invoking the removed resolve() → fatal error at runtime.
• PHP deprecation warnings promoted to exceptions on the next major upgrade.
• Continuous SCA noise: automated scanners will flag an archived, zero-adoption dependency on every run, training the team to ignore alerts.

Ramp-up. Low technical ramp-up — a mid-level engineer reads the whole library in an afternoon — but high contextual ramp-up: with no docs and no external references, the only way to know the behavior is to read the source and write the tests yourself. Assume half a day for a confident engineer to own it, plus the test suite you will have to author.

Verdict. The composite score of 0.045 is the correct read. This is a single-maintainer, archived, zero-adoption fork whose one differentiating change is the removal of upstream functionality. Recommend reject for new use; permit only as a temporary, vendored, adapter-wrapped workaround for a specific blocked upgrade — with a written exit criterion and an owner. The opportunity: 39 signal reflects unmet need in the Hoa ecosystem, not an opportunity for us to take on that maintenance.