Entity File Bundle Laravel Package

Product Decisions This Supports

• Attachment feature scoping. One YAML "configuration" maps one entity to one filesystem. If the roadmap item is "let sellers upload a logo" or "let products have pictures," this defines the whole feature surface (save, list, read, move, delete) in a few config blocks — a scoping artifact you can put in front of design and engineering in an afternoon.
• Build vs. buy. The core scope is narrow and well-bounded: attach a file to a Doctrine entity, store via FlySystem, serve it over two protected routes. Buying this is a days-not-weeks trade against hand-rolling upload handling, path management, and entity/file lifecycle glue. It is not a media platform, so budget the "buy" decision as "skip the plumbing," not "skip the feature."
• Storage strategy (reversible). FlySystem adapters mean local disk today, S3/FTP/Drive later, without touching entity code. That supports a decision to ship MVP on local storage and defer cloud procurement — a genuinely useful option value for a PM.
• Access-control and delivery policy. Per-configuration role (including PUBLIC_ACCESS) and disposition (inline vs attachment) are product-visible dials: gated customer documents vs. public images, view-in-browser vs. forced download. These map directly to policy questions stakeholders will ask.
• Data model and future reporting. Files are Doctrine entities (default, or your own class implementing EntityFileInterface plus the shipped trait), so metadata is queryable — "which entities have attachments," "who uploaded what" become SQL, not log archaeology.
• Internal admin/ops roadmap. The Crudit EntityFileBrick gives a dropzone UI (view, add, remove, download) for back-office panels — this can decide whether ops tooling ships this quarter or next.
• Explicit non-goals to record. No thumbnailing, transcoding, variant generation, validation rules, virus scanning, quotas, versioning, or signed-URL/direct-to-cloud upload. Every one of these is a build item for you, and should be written into the brief so no stakeholder assumes it.
• Dependency risk acceptance. 3 stars, 0 dependents, single-vendor maintainership, MIT license, no tests documented in what's provided. This is a decision to accept a small bus factor in exchange for saved effort — ideally recorded with a mitigation (thin internal wrapper, pinned version, fork option) rather than left implicit.

When to Consider This Package

Adopt if:

• Your stack is Symfony + Doctrine, configured with YAML, and files conceptually belong to entities (logos, product photos, generated reports, scanned documents).
• You need basic lifecycle only: save from string / File / UploadedFile / resource, retrieve, read or stream contents, move/rename, delete (entity + physical file together).
• You want storage-agnostic behavior via FlySystem now, with the option to swap adapters later.
• You are building internal or authenticated experiences where a role-gated route is sufficient protection.
• You can own the code if abandoned — MIT, small surface area, readable.
• You want the Crudit dropzone for an existing 2LE-based admin.

Look elsewhere if:

• You are on Laravel/Eloquent. Despite being tagged as a Laravel/PHP package, this is a Symfony bundle: it depends on Symfony DI, YAML bundle configuration, Doctrine entities, and (optionally) Symfony Flex route registration. Eloquent models, config/filesystems.php, and Laravel's Storage facade are not what it talks to. Bridging is real work, not configuration.
• You need media processing — resizing, thumbnails, transcoding, AI tagging; pair with a dedicated library or service instead.
• You need direct-to-cloud uploads, pre-signed URLs, CDN delivery, or high-volume public traffic. Uploads appear to flow through PHP; there is no caching or signing story in the docs.
• You need compliance-grade behavior: MIME/extension validation, size limits, malware scanning, retention policies, audit trails, encryption requirements, tenant isolation.
• You need variants or versioning of the same asset.
• You require vendor support, SLAs, or a large community — 0 dependents and 3 stars means you are effectively the maintainer of last resort.
• You cannot verify release cadence or test coverage. The supplied release notes stop at "added SQL indexes" and "SF7/SF8 compatibility"; before committing, ask for the test suite and confirm the 2026-dated release is real and not a metadata artifact.

How to Pitch It (Stakeholders)

For executives: "This is a small, MIT-licensed Symfony component that attaches files to records in our database — a seller's logo, a product's images, a generated report. Instead of engineering building upload, storage, path, and download-serving logic, we configure one mapping per entity. It also gives us a ready-made upload panel for internal admin screens. Two things to be clear about: it's plumbing, not a media platform — thumbnails, scanning, and public-scale delivery are separate line items — and it's maintained by a single small vendor, so we'd wrap it thinly and stay able to replace it. Expected payoff is a few engineer-weeks avoided per attachment feature, with storage choice left open so we're not locked into local disk."

For engineering: "Doctrine-oriented Symfony bundle. You define a configuration per entity+filesystem in lle_entity_file.yaml (class, storage_adapter, optional entity_file_class, role, disposition), then get a manager: $entityFileLoader->get('seller_logos'). save($entity, $data, $path) accepts a string, File/UploadedFile, or stream resource and returns an EntityFile you must persist and flush yourself — that's the main footgun. move() likewise requires a flush. Read with read()/readStream(), remove with delete() (removes row and blob). Paths are caller-supplied, so dynamic layouts like Y-m/{id}.xml are trivial. Storage is FlySystem: define any adapter in flysystem.yaml and reference it; the default drops files under data/{configName}. Delivery is two routes — by id or by path — gated by the config role; register them manually if you're not on Flex. Extend metadata by implementing EntityFileInterface and using the provided trait.

Known gaps to plan around: no file validation, no image processing, no queueing, no signed URLs, no Laravel/Eloquent path, and the docs show no test suite or CI. Mitigation I'd recommend: put a one-method internal interface in front of the manager so a future swap to raw FlySystem is a contained change, pin the version, and add our own validation and authorization layer rather than relying on the bundle's role check alone. Budget a spike to confirm Symfony/Doctrine version fit and route-security behavior before we commit to a date."