File System Bundle Laravel Package

Technical Evaluation

Architecture fit — this is a category mismatch and should be the first line of the assessment. Despite being presented as a Laravel/PHP package, kitpages/file-system-bundle is a Symfony 2-era bundle: it wires itself through services.xml, Symfony's DI container, and optionally the EventDispatcher. There is no ServiceProvider, no facade, no publishable config, no config/*.php. Composer will autoload the classes into a Laravel app, but nothing will be bound into the container. Every adapter would require a hand-written bridge. The genuinely portable asset is the design pattern — a thin adapter contract (set/get/delete/exists over a path namespace) where the content argument is a file path or stream handle rather than a string, so a 2 GB transfer never materializes in a PHP variable. That idea is worth adopting. The code is not.

Integration feasibility. Direct installation is low-feasibility. Expect pinned symfony/* ~2.x constraints that will conflict with the Symfony 6/7 components Laravel 10/11 ship, PSR-0 or early-PSR-4 autoloading, PHP 5.3–5.6 idioms, and an S3 adapter built against AWS SDK v1/v2 with its own CVE history. Concept extraction is moderate-feasibility and is the recommended route. A notable tell: the developer-facing adoption guide in our source set documents Symfony bundle registration in AppKernel.php, not a Laravel install — the documented path is itself evidence of stack mismatch.

Technical risk.

• Abandonment. 12 stars, 0 dependents, no releases in roughly a decade. No PHP 8 compatibility, no security triage, no Flysystem interop.
• Dependency contagion. Pulling a stale AWS SDK transitively into a modern Laravel app is a larger risk than the bundle itself.
• Silent behavioral drift. The abstraction's entire value is memory-flat streaming. If a future adapter refactor reads into a string, the failure mode is a fatal OOM under production load — not a test failure.
• Throughput, not memory, is the real ceiling. Streaming solves the 128 MB limit and does nothing for worker occupancy. That distinction matters for capacity planning and is easy to lose in the framing.
• License is clean (MIT), so forking and vendoring is legally unencumbered — the constraint is cost, not law.

Key questions.

1. What is the actual pain point — upload memory, download memory, or both? Laravel Storage::readStream/writeStream already covers both, so the answer determines whether this pattern is still needed at all.
2. What are p50/p99 file sizes and peak concurrent transfers per worker pool?
3. Target backends: local disk, S3-compatible, or both? Multipart, presigned URLs, and range requests change the design materially.
4. Do we require atomic writes, checksum verification, and idempotent retries? The bundle appears to offer none.
5. Are we prepared to own a fork indefinitely, or is the goal to decommission within N months?

Integration Approach

Stack fit. Laravel's Storage facade is a Flysystem wrapper and is the idiomatic home for this problem. Local-to-local moves use stream_copy_to_stream between handles to keep memory flat. For S3, Storage::writeStream() plus a multipart uploader — or better, a presigned PUT/GET URL that bypasses the PHP process entirely. The bundle's differentiator is achievable natively on a maintained dependency. Do not introduce a second storage abstraction alongside Storage; the onboarding tax is permanent and the marginal capability is zero.

Migration path.

1. Spike, timeboxed to one sprint. Install the bundle in a throwaway app, read the adapter contract, and benchmark memory behavior against a 1–2 GB file to confirm the README claim. Do not merge this spike.
2. Define our own contract. A FileStoreInterface with putStream(string $path, resource $stream), getStream(string $path): resource, delete, exists, url — typed for PHP 8.
3. Implement two adapters. LocalFileStore (temp file + rename() for atomicity) and S3FileStore (multipart, StreamInterface over fopen).
4. Bind in a service provider, mapping config into a dedicated disk or a file_store config block.
5. Migrate call sites, then ensure no vendor copy of the bundle ever lands in composer.json.

Compatibility. Target PHP 8.1+, Laravel 10/11, Flysystem 3.x, AWS SDK v3. Do not attempt to co-install the original Symfony 2 constraints — the resolver will fight you and the win is negligible.

Sequencing. Contract → adapters → provider/config → call-site migration → decommission. Front-load the spike and the contract; the rest is mechanical. Exit criteria up front: if the spike shows Storage::writeStream already meets the measured memory target at p99 file size, skip steps 2–3 and close the evaluation as "solved by existing dependency." Write that down before the spike starts, because the temptation to build the abstraction anyway is strong.

Operational Impact

Maintenance. Upstream maintenance is effectively zero. Assume no patches, no PHP 8 fixes, no security response. Adoption implies a permanent fork owned by our team, with all dependency-upgrade cost (AWS SDK, Symfony contracts) landing on us. A 12-star, zero-dependent package has no invisible maintainer community to absorb that. Budget it as a line item, not a footnote.

Support. Documentation is a README, likely French-language. No tests, no CI badge, no issue triage. Internal ramp-up on the abstraction itself is small — the surface is a handful of methods. The real cost is archaeological: reading Symfony 2 bundle conventions to reconstruct intent, and the ongoing "why aren't we using Storage?" question from every new engineer.

Scaling. A PHP-FPM worker is occupied for the full duration of a transfer; a 2 GB upload at 10 MB/s pins a worker for roughly 200 seconds. Under load, worker exhaustion hits well before memory exhaustion. Mitigations: presigned direct-to-store uploads, chunked/resumable transfers, queue workers for server-side moves, and a deliberate review of max_execution_time and request_terminate_timeout.

Failure modes to instrument.

• Partial writes with no atomicity → corrupt objects served downstream. Temp-file + rename() locally, multipart completion semantics on S3.
• Temp-file leakage on exception paths → disk exhaustion on app servers, surfacing as unrelated cascading failures.
• Silent truncation — no checksum in the original design; add SHA-256 verification on upload.
• Non-idempotent retries duplicating or overwriting objects.
• OOM regression if a future refactor reads content into a string; guard with a memory-limit assertion in the adapter test suite.

Ramp-up. One to two engineer-weeks for the spike, contract, and both adapters for a mid-level engineer comfortable with streams, plus a half-day of team education on stream semantics and handle lifecycle (finally blocks, explicit closes). The conceptual surface is small; the risk sits entirely in the dependency's age, not its complexity.

Recommendation. Do not adopt the package. Treat it as a design reference and a benchmark oracle. Adopt the pattern — never hold full file content in a $content variable — only if the spike proves Laravel's native Storage::writeStream and presigned-URL paths are insufficient at our measured file sizes and concurrency.