Laravel Model Media Laravel Package

Product Decisions This Supports

• Build vs. buy on file attachments. The package collapses "attach a file to a record" into a trait plus a path column. That removes a media-table migration, a polymorphic relation, and the join/query complexity that comes with it — roughly a sprint of work we don't have to schedule.
• Schema and roadmap simplicity. No additional tables means no cross-service joins, no backfill migrations, and no new entity in our data model. File attachments ship as an attribute on models we already have, so the feature rides along with existing work rather than becoming its own epic.
• Use cases that fit cleanly: avatars, cover images, single PDF attachments (contracts, invoices, receipts), KYC/verification documents, imported CSV artifacts — anywhere the product rule is "one file per field."
• Deliberate deferral of a DAM. This is the cheap primitive that lets us postpone investment in conversions, renditions, CDN delivery, and asset search until usage data justifies it. We stay out of the "media platform" business while the product question is still open.
• Low lock-in as a roadmap hedge. MIT-licensed, small surface area, path stored as a plain attribute. If we outgrow it, our data is already portable — files live where we put them, and the column stays meaningful.
• Explicit non-scope to plan around: no conversions/thumbnails, no multi-file collections or ordering, no media metadata table. If the roadmap needs any of those, this package is a stepping stone, not the destination.

When to Consider This Package

Adopt when:

• The domain genuinely is one file per attribute; a nullable *_path column is the honest model.
• The team is Laravel-native, small, and would rather own a 200-line trait than a dependency tree.
• You need the feature in weeks, not a media subsystem in quarters.
• You're comfortable being an early production adopter and will read the source before shipping it.

Look elsewhere when:

• You need galleries, multiple collections per model, ordering, or per-file metadata — reach for spatie/laravel-medialibrary or a hosted DAM instead.
• You need image conversions, responsive variants, signed-URL/CDN abstractions, or an admin media browser. This package deliberately does none of it.
• You need media-level queryability (list all assets, orphan detection, retention/erasure workflows). Path-as-attribute makes those a manual exercise; if GDPR deletion or audit obligations are in scope, budget for it.
• Maturity signals matter to your org. 11 stars, 0 dependents, single maintainer: we would be the first serious production user. Treat that as a code-review and fork-maintenance cost, not a disqualifier — but if your procurement requires ecosystem validation or a vendor SLA, this fails that bar.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed library that lets us ship file attachments on existing records without adding a table or a service. It's a weeks-not-quarters decision, it costs nothing to license, and because files are stored as ordinary model attributes, we can walk away from it later without a data migration. The tradeoff is that it's a young project with one maintainer — so we treat it as an internal utility, not a platform bet.

To engineering: One trait, one column, no service provider gymnastics, no extra queries. We isolate it behind a thin internal interface (attachFile / url / delete) so that swapping to a full media library later is a single adapter change rather than a refactor. Pin the version, add contract tests around upload/delete/orphan cleanup, and review the trait's source before it touches a production model — at 0 dependents we are effectively the QA. Recommend a fork-and-vendor fallback if maintenance stalls.