Files Laravel Package

Product Decisions This Supports

• Build vs. buy for the file-upload subsystem. The package bundles the commodity 80% of upload work: Flysystem storage abstraction, metadata persistence, Doctrine lifecycle hooks (postPersist uploads, preRemove deletes), a Symfony form type + validation constraints, and a DownloadUtility for controller responses. This is the classic "don't spend sprint capacity reinventing attachment handling" decision.
• Storage-cost / dedupe strategy. MD5-checksum deduplication means identical uploads are stored once and the DB row is reused. That's a direct lever on storage spend and a defensible product answer to "why are we paying for 4 copies of the same PDF?"
• Storage portability and vendor lock-in. Flysystem adapters mean S3/GCS/local/Azure is a config swap rather than a rewrite. This de-risks the "go multi-region" or "move off S3" roadmap item and keeps cloud negotiation leverage.
• Data ownership boundary. Metadata (mime, size, hash, path, timestamps) lives in your relational DB, not in the object store. That makes files queryable, joinable, auditable, and reportable — materially different from a "just put a URL column in the table" approach.
• Delivery architecture. The README's PathResolver + serializer normalizer examples support the "serve direct from CDN" pattern, while DownloadableFile and the controller path support authenticated/forced-download flows. That's the decision fork between public media and gated documents.
• Use-case fit. Best suited to CMS content, admin-panel attachments, document/records modules, avatars, and internal tooling — anywhere a file is an entity with lifecycle semantics.
• Roadmap scoping. Treat naming strategies (SplitHash, Date, UuidV5, decorators) and the embeddable-vs-entity file model as configuration choices to standardize early, which prevents a per-feature "each team invents its own upload path" sprawl.

When to Consider This Package

• Correct the framing first: this is not a Laravel package. arxy/files is a Symfony bundle built on Doctrine ORM. The README states plainly: "Currently, only Doctrine ORM is supported as persistence layer." There is no Eloquent driver, no Laravel service provider, no Laravel validation integration. If the target stack is Laravel, this is not adoptable as-is — it is at best a reference architecture to port.
• Adopt when you are on Symfony + Doctrine, uploads are a supporting capability rather than the product, you want DB-backed file metadata with dedupe, and you're comfortable owning the integration glue (the README gives YAML and plain-PHP wiring; you write the controllers, normalizers, and CDN config).
• Look elsewhere when:
  • Stack mismatch — Laravel/Eloquent, non-Doctrine ORMs, or non-Symfony frameworks.
  • Vendor-risk sensitivity. 18 stars, 0 dependents, a single-maintainer footprint, and no downstream adoption signal is a real bus-factor and longevity concern. Note also the release metadata shows a future-dated release, which suggests thin or stale release hygiene — verify against the repo directly before committing.
  • Media is the product. No image transformation pipeline of its own; the LiipImagine integration is example code, not a supported feature. If you need on-the-fly resizing, AVIF/WebP negotiation, or a DAM, buy a managed service (Cloudinary/imgix) instead.
  • Async / direct-to-storage uploads. The model uploads on Doctrine postPersist, i.e., synchronously in the request. Large files, presigned S3 PUTs, and queued processing are outside its design.
  • Compliance-heavy requirements. No virus scanning, no PII redaction, no retention policy, no signed-URL expiry primitives beyond a cache-expiry argument — all of that is on you.
• Fallback posture: vendor/fork it and pin the version, or mine the design (dedupe-by-hash + Flysystem + entity lifecycle) and reimplement against your own persistence layer. Budget roughly the metadata model, hooks, and two naming strategies — a few days, not weeks.

How to Pitch It (Stakeholders)

To executives: "We need file uploads in N features this quarter. This library gives us the boring, risky parts for free under MIT — storage abstraction, de-duplication, database tracking, and automatic cleanup when records are deleted. The catch is it's a small, low-adoption open-source project built for Symfony, not our Laravel stack, and it has essentially zero downstream users. Recommendation: do not take a dependency on it for anything customer-critical. Either use it as a proven design blueprint and build the ~3-day equivalent ourselves, or adopt it only in a low-blast-radius internal tool with the version pinned and the code vendored so a maintainer walking away can't break us."

To engineering: "It's a Symfony bundle over Doctrine ORM + Flysystem — worth reading for the patterns, not for composer require. Steal these three ideas: (1) store file metadata in our own table so files are queryable and joinable; (2) hash-based dedupe so identical uploads don't multiply storage cost; (3) hook upload on persist and delete on remove so orphaned blobs never accumulate. Skip its synchronous-on-flush upload model — we want presigned direct-to-S3 plus a queued post-process step. The naming-strategy abstraction is genuinely good; the LiipImagine and serializer snippets are illustrative, not supported."

Ask: timebox a spike to confirm the dedupe + metadata schema against our actual storage target before we commit either way.