Media Library For Laravel Laravel Package

Product Decisions This Supports

• Storage cost / deduplication strategy: This release hardens the deduplicated-add and replace() paths so that identical files are shared safely across rows. The decision to store one original and point many records at it (rather than duplicating bytes per record) is now defensible under concurrent writes, not just in single-threaded tests.
• Data-integrity posture for media: Three of the four fixes close silent data-loss windows — a shared original being force-deleted out from under a committing row, forceDelete() inside a rolled-back transaction permanently losing files while the row returns, and replace() overwriting bytes a soon-to-be-committed row was about to share. For a PM, this converts "media is best-effort" into "media is transactionally consistent with the database," which is a claim you can put in front of customers.
• Transactional workflow support on the roadmap: Teams can now wrap media operations in DB::transaction() alongside domain writes and expect rollback semantics to hold for both row and bytes. This unblocks features like order-attachment flows, draft-to-published content, and import jobs that must be all-or-nothing.
• Extensibility without breaking test fidelity (new in 1.3.1): Factories now build the model configured on the host rather than a hardcoded one. That removes a common tax on extending the package — teams that subclass the media model for tenancy, custom tables, or extra behavior can keep using the shipped factories in their own suites. It is a small change, but it is the difference between "you can swap the model" and "you can swap the model and still have working test scaffolding," which is what actually gets exercised in CI.
• Rollout risk and upgrade decision: The release line remains patch-safe with no breaking API changes. The decision it directly supports is "ship the current line (1.3.1) before onboarding any tenant or workload that does concurrent uploads, dedup, or force-deletes" — particularly before any backfill or bulk-import migration that runs in parallel with live traffic. Because the recommended target has moved from 1.1.4 to 1.3.1, treat it as a minor-version upgrade: review the intermediate changelogs once, then ship.
• Build vs buy: Each of these fixes is a class of concurrency bug most teams would not find, let alone fix, in a homegrown media layer. The factory fix is a smaller signal, but it points the same way: the package is investing in being embeddable in someone else's application conventions, not just correct in isolation.
• Test and QA investment: The remaining behavioral contracts (row locks before sharing, deferred file deletion until commit, ModelNotFoundException on racing attach/copy/replace) are now explicit and testable. Worth encoding as acceptance criteria in your own integration suite rather than trusting upstream alone — and now worth doing against our model class, not a stand-in.

When to Consider This Package

Consider it when you are on Laravel, need media/original/variant handling with checksum-based deduplication, and your writes happen concurrently or inside database transactions — queues, multi-worker consumers, bulk imports, or multi-tenant uploads. It is a particularly strong fit if you have force-delete/cleanup requirements (GDPR erasure, retention policies) that must not strand or over-delete bytes, or if you intend to subclass the media model for per-tenant behavior and want the package's test tooling to keep working when you do.

Look elsewhere, or scope down, when:

• You need cross-engine guarantees the locking approach depends on — verify your database supports the row-locking semantics used here, and be cautious with engines or configurations where SELECT ... FOR UPDATE is a no-op or unsupported.
• Your media needs are simple single-upload, no-dedup, no-transactional-coupling cases; the concurrency machinery is overhead you will not exercise.
• You need transformation/CDN-level features (on-the-fly resizing, edge delivery, signed URLs) as first-class concerns — this is storage-lifecycle tooling, not a media delivery platform.
• You require media version history with retrievable prior bytes. Note the release confirms an in-place replace() keeps the same URL and discards old bytes on commit; if you need old versions, that is your own responsibility and a different tool.
• You need cross-service or S3-only consistency without a relational row store to lock on.

Adoption criteria before promoting to production: confirm the underlying DB locking works as intended, run a concurrency test that exercises dedup + force-delete and replace + rollback, ensure any code catching media exceptions handles ModelNotFoundException from racing attach()/copy()/replace() — that is new, surfaced behavior your error paths must tolerate — and, if you swap the model, re-run your factory-based fixtures to confirm they now resolve to your class.

How to Pitch It (Stakeholders)

To executives: A patch release that closes silent data-loss bugs in the media layer — no API changes, no migration work, no user-visible behavior change except correct outcomes. The commercial value is in what it prevents: files disappearing while records still reference them, orphaned bytes surviving a rolled-back delete (a compliance and storage-cost issue), and files being overwritten by concurrent writes. A follow-on fix also makes the package's test scaffolding respect our own model configuration, which lowers the cost of tailoring media storage to our tenancy model. If we handle customer uploads at any concurrency, run any bulk import alongside live traffic, or plan to customize the media model, we should take this before those workloads start, not after.

To engineering: Four fixes, all in the concurrency/transaction boundary, plus one factory fix. Sharing rows now save under a row lock on the row they share with, so a concurrent force-delete waits and then sees them; if the shared row is gone, dedup add/replace falls back to storing its own copy and attach()/copy() throw ModelNotFoundException. Force-deleted files are now removed on commit, immediately outside a transaction, and retained on rollback. replace() locks its own row and does a locking read for other referrers, writing to a new path when the file is shared, and restores old bytes on rollback for in-place replaces. Separately, factories now instantiate the model configured on the host, so subclassed or swapped models are built correctly in tests. Action items for us: upgrade to 1.3.1 (reviewing the 1.2.x/1.3.x changelogs once, since we are coming from 1.1.4), add ModelNotFoundException handling to media error paths, and add integration coverage for dedup-plus-force-delete and replace-plus-rollback against our actual database engine using our own model class.