File Laravel Package

Technical Evaluation

Architecture fit. hoa/file is a component of the Hoa project: an object-oriented abstraction over PHP's stream layer (Hoa\File\File, Directory, Link, Read, Write, Append) with its own stream wrapper infrastructure (hoa://), filter chain, locking helpers, and exception model. It is architecturally parallel to, not complementary with, Laravel's I/O story. Laravel standardises on league/flysystem (via the Storage facade) for abstracted disks and symfony/filesystem + symfony/finder for local operations. Adopting hoa/file creates a second, mutually unaware file-access layer with a separate exception hierarchy (Hoa\Exception), a separate event dispatcher (Hoa\Event), and a bespoke autoloading/consistency bootstrap (hoa/consistency) that predates and does not respect PSR-4 conventions the rest of the codebase relies on.

Integration feasibility. There is no Laravel service provider, no facade, no config surface, and no published integration examples for modern Laravel. Wiring it means authoring a thin adapter ourselves. The real cost is the transitive closure: hoa/file pulls hoa/stream, hoa/consistency, hoa/exception, hoa/event, hoa/protocol, and hoa/zformat — all frozen at the same 2017 vintage and all archived. Composer will typically install these on PHP 8.x because the constraints declare a floor (php >= 5.5) with no ceiling, so a green composer require gives false confidence; the failure mode is runtime, not resolution-time.

Technical risk. High, on four axes:

Key questions to resolve before any code is written.

1. What is the actual forcing function — is hoa/file a direct requirement, or a transitive dependency of something else we could replace or isolate?
2. Which specific capability is missing from Storage/symfony/filesystem — stream filters? advisory locking? the hoa:// virtual filesystem? Each has a native or first-party answer.
3. Do we need remote disks (S3, GCS, SFTP)? If yes, hoa/file is disqualified outright; it is a local-stream abstraction with no Flysystem-grade adapter ecosystem.
4. Are we willing to own a vendored fork indefinitely, including security triage? If not, this is a reject.
5. Does any target runtime include PHP 8.2+ or Octane? Both materially raise the breakage probability.

Integration Approach

Stack fit: poor. A capability mapping shows near-total redundancy with first-party Laravel/Symfony primitives:

Migration path (if legacy code already uses it). Do not delete-and-rewrite; introduce a domain-owned interface first, implement it with hoa/file behind the scenes, then swap the implementation to Flysystem/Symfony and delete the adapter. Concretely:

1. Inventory every call site and classify by capability (read, write, directory traversal, filter, lock, temp).
2. Introduce a seam — e.g. App\Contracts\DocumentStore — and adapt hoa/file to it. Nothing outside the adapter may reference Hoa\* types; no Hoa\File\File in a controller signature, no Hoa\Exception escaping into the framework handler.
3. Contract tests written against the interface, run against the hoa/file implementation to capture current behaviour (including edge cases like missing-file semantics and permission errors).
4. Re-implement against Storage/symfony/filesystem, re-run the same contract tests, then remove the adapter and the dependency.

Compatibility. Pin exact versions in composer.json and commit composer.lock; add "replace"/"provide" only if we fork. Audit with composer why hoa/file to confirm whether it is direct or transitive. Run the full suite on the minimum and maximum supported PHP versions in CI before committing to anything.

Sequencing. (a) Spike: one engineer, timeboxed, proving read/write/directory/filter paths under our target PHP and under Octane-style long-lived workers. (b) Decision gate: adopt-with-fork vs. replace-with-native. (c) If replace: seam → contract tests → swap → dependency removal, shipped in that order across separate PRs. (d) If adopt: fork to an internal namespace, add PHP-version compatibility shims, add it to the security-watch list, and document an exit plan at the same time as the adoption decision.

Operational Impact

Maintenance. Archived software means we inherit 100% of the maintenance burden the moment we ship it. There is no upstream to send a patch to, no release cadence to track, and no upgrade path other than our own fork. Every future PHP minor bump becomes an unplanned compatibility investigation. Budget it as an internal, owned library — not as a dependency.

Support. No maintainer, no issue triage, no security advisories, effectively no community. Internal engineers will be the only source of answers, and that knowledge will be concentrated in whoever wrote the adapter. Incident response for a file-handling bug is strictly slower than for Storage, where the answer is a well-documented first-party API.

Scaling. Not a throughput bottleneck in itself — it is a local-I/O wrapper — but it is scale-hostile in two ways. First, it bypasses Flysystem, so we lose the ability to point the same code at S3/GCS/CDN-backed disks as we grow; a horizontal scale-out that assumes shared object storage would require rewriting every call site. Second, it adds its own buffering and object layer over native handles, which means extra open file descriptors held by live objects. In long-running queue workers and Octane processes, unreleased handles accumulate into file-descriptor exhaustion — an outage mode we simply do not have with Storage::get()/put().

Failure modes to instrument for.

• Exception escape. Hoa\Exception\Exception does not extend Symfony's HttpException or Laravel's base exception, so failures bypass Handler::report() and render as raw 500s with no contextual logging. Wrap every entry point in a try/catch that rethrows as a framework-native exception.
• Global stream-wrapper collision. Wrapper registration is process-global; under Octane or in tests that boot multiple applications, registration and teardown can race or leak, producing intermittent invalid stream errors that are hard to reproduce.
• Error-handler interference. hoa/consistency installs its own handlers at bootstrap; stacked against Laravel's handler and PHP 8's signatures this can swallow errors or convert warnings into fatals in unexpected places.
• Silent behavioural drift. Permission and open_basedir semantics differ from Symfony's; code that works locally can fail in containerised production with different UID/GID or mounted-volume behaviour.
• PHP upgrade breakage. The next PHP minor will be an unplanned project, discovered in CI or, worse, in production.

Ramp-up. Every new engineer must learn an API that appears nowhere else in the codebase and is documented only by 2017-era docs and source. The mental model (file()->open()->read()->close() with a Hoa\Stream context) is unlike anything else they will touch at this company. That is a permanent onboarding tax on every hire, in exchange for capabilities we already have. For a package with 0 dependents and a 2017 last release, the recommendation is to reject for new work, treat any existing usage as a tech-debt line item with a scheduled removal, and spend the integration budget on a Storage-based abstraction instead.