Hoa Protocol Laravel Package

Product Decisions This Supports

• Extensibility roadmap (plugins / themes). The package supplies the primitive behind override chains: a named tree of path roots (app://, package://, tenant://) where each node holds an ordered list of candidate locations, tried first-to-last. That is exactly the data model for "ship a default theme, let the customer override it, let a plugin override that."
• Multi-tenant and white-label asset resolution. Tenants can be modeled as extra "reals" pushed onto a shared root, so path priority becomes configuration rather than branching code in controllers and Blade directives.
• Build vs. buy — and the honest answer is "vendor." The value is not the library, it's the API shape. It is small, BSD-3, and dependency-free, which makes copying it into the codebase (with attribution) cheaper than owning a Composer dependency on an archived fork.
• Decoupling path discovery from path resolution. This is the whole reason the fork exists. Upstream resolve() bakes in is_file()-style local-disk checks; stripping it lets your code take the candidate list and check existence through Laravel's Storage/Flysystem instead — which is what makes S3-, GCS-, or CDN-backed assets a config change rather than a second abstraction.
• Avoids global stream-wrapper registration. Frameworks dislike packages that register process-wide wrappers; a resolve-free build is plausibly wrapper-free, which is likely the "Laravel-compatible" claim. Verify this before relying on it.
• What it does not support: no user-facing capability ships because of this package. It unblocks no roadmap item on its own; it is a plumbing choice inside one.

When to Consider This Package

Reasonable fit when:

• You are porting or maintaining code already written against Hoa\Protocol's root API and need it to run under Laravel without Hoa's filesystem-bound resolver or wrapper side effects.
• You need an ordered, mutable registry of named roots with fallback semantics, and you want to own the existence check (database, cache, remote disk).
• You accept vendoring it: BSD-3 permits copying with attribution, which neutralizes the maintenance risk.

Look elsewhere when:

• The requirement is simply "find this file across these directories" — a short helper plus Illuminate\Support\Facades\File, or symfony/finder, does it with no new concept.
• You need real mounts or a virtual filesystem — that is league/flysystem, not this.
• You expect maintenance, security triage, or community answers. Package health is the headline: archived, 0 stars, 0 dependents, single-maintainer fork of an effectively dormant upstream. You would be the only consumer in existence.
• It touches a critical path or a regulated supply chain. An archived dependency with no upstream CVE process is an automatic finding in most audits, and "no one else uses it" means no one else will notice a break.

How to Pitch It (Stakeholders)

Executives: There is no license cost and no lock-in, so the decision is about risk, not money. The package is a maintenance orphan — archived, zero adopters, one maintainer — so we should not take it as a live dependency. Recommendation: copy the small amount of code we need into our own repository, keep the BSD attribution, and own it. Cost is hours, not weeks, and it removes a future audit and upgrade problem.

Engineering: It is the registry half of Hoa\Protocol without the half that assumes a local disk. You define roots, push ordered candidate paths onto them, and read the candidate list back; we implement resolution, so it works with any Flysystem disk and stays testable. The surface area is small, the semantics are the ones we already want for theme and plugin overrides, and vendoring means we can refactor it freely.

Risks and mitigations: Archived upstream, single maintainer, no dependents — so no CVE pipeline and no upgrade path. Mitigate by vendoring rather than requiring it, pinning it behind our own thin interface, and writing tests that lock the behaviour we depend on so a future replacement is a one-file change. If the team would rather not own even that, the fallback is a short in-house root registry — the concept is simple enough that this is a legitimate build-over-buy call.