Media Library For Laravel Laravel Package

Technical Evaluation

Architecture fit

This package sits directly on Laravel's Eloquent + Filesystem + Database transaction primitives. The 1.1.4 fixes confirm a design assumption that matters for architecture review: correctness depends on a transactional RDBMS with row-level locking (SELECT ... FOR UPDATE) and on application code actually wrapping media operations in transactions. The package is not a standalone service; it is a persistence-layer library whose invariants are shared between the media table, the storage disk, and the caller's transaction boundary.

The 1.3.1 factory fix adds a second architectural signal: the media model is a supported extension point. A host application can swap in its own model class, and the package's factories now resolve and build that configured class rather than a hardcoded base model. That moves "custom media model" from an undocumented trick to a tested configuration, which is relevant if we intend to attach domain behavior (policies, morph maps, custom casts) to the media entity.

Integration feasibility

The 1.3.1 change is confined to test-time code — factory model resolution — with no runtime API, schema, or config change implied. Integration cost is therefore low, with three caveats:

• We have no review of 1.2.0 or 1.3.0. Going from 1.1.4 to 1.3.1 crosses two minor versions whose notes are not in hand, so the factory fix cannot be assumed to be the whole delta. Treat the changelog review as a gating step, not a formality.
• Factory behavior changed observably. Test suites that assert on the concrete class, table, morph alias, or factory states of generated media may now see a different model if the host has overridden the model config. Any existing local workaround (custom factory, newModel() override, Factory::guessModelNamesUsing) may now double up or conflict.
• The runtime behavior changes introduced in the 1.1.4 line still apply to the code we would be running after this upgrade, so the earlier planning items have not gone away:
  • attach() and same-disk copy() can throw ModelNotFoundException when the shared row disappears before the lock is acquired.
  • File deletion for forceDelete() is deferred until transaction commit, changing timing assumptions for code that inspects the disk immediately after the call.

Technical risk

• Lock-coupled correctness. Hot media rows serialize on row locks. High-concurrency workloads (bulk imports, parallel queue workers, API uploads) can see increased lock wait times and new deadlock surfaces where deduplication and deletion target the same file.
• Engine sensitivity. The guarantees only hold on engines that implement locking reads (MySQL InnoDB, PostgreSQL). SQLite and MyISAM-class engines will silently not honor them, so the same code can be correct in staging and incorrect in production if the engines differ.
• Read replicas. The fix relies on locking reads against the primary. Any code path reading media state from a replica will still see the old race.
• Rollback storage cost. In-place replaces keep the previous bytes aside until commit. Large files plus long transactions translate into transient disk consumption and, in the worst case, doubled storage for the duration of the transaction.
• Test-fixture drift (new in 1.3.1). Factories now build the configured model. This is a correctness improvement, but it can silently change which class, observers, global scopes, and table a test is exercising — the kind of change that produces green suites locally and different behavior in CI.
• Unreviewed version range. The delta from 1.1.4 to 1.3.1 spans releases we have not read. Risk here is unknown-unknowns rather than known defects.

Key questions

1. What shipped in 1.2.0 and 1.3.0, and are any of those changes breaking, deprecating, or schema-affecting?
2. Which database engines are officially supported, and are the locking semantics documented as a requirement rather than an implementation detail?
3. What is the expected behavior on lock timeout or deadlock — does the package retry, or does the exception propagate to the caller?
4. Is ModelNotFoundException from attach()/copy() documented as part of the public contract, and do we need a wrapper with app-specific semantics?
5. Is there a recommended orphan-file reconciliation command for the window between commit and deferred deletion?
6. For 1.3.1 specifically: is the configured-model swap supported via published config, container binding, or both? Is it documented as a public extension point, and does the factory change require any action from hosts that already override the model?
7. What Laravel/PHP versions does 1.3.1 support, and are there minimum transaction isolation level requirements?

Integration Approach

Stack fit

Standard Laravel monolith or modular monolith with MySQL/PostgreSQL + a Laravel filesystem disk. Fits naturally if media operations already occur inside DB::transaction() blocks or inside queued jobs with afterCommit semantics. Fit degrades in architectures that share a storage bucket across multiple services writing to the same path space, since the package's locking only protects rows it owns. If we plan to subclass the media model, 1.3.1 makes that path more credible in tests, which is a mild point in favor of adopting it now rather than later.

Migration path

• Target version is 1.3.1. If we are currently on a 1.1.x release, this is a minor-version jump, not a patch bump: read the 1.2.0 and 1.3.0 changelogs and treat anything they mention as part of the change set.
• No data migration appears required from the notes we have; existing rows and files remain valid. Verify on a restored production snapshot before rollout.
• Run the full test suite in staging before rollout. The factory change is exactly the class of fix that shifts test outcomes without shifting production behavior, so a green suite is the primary evidence that we were not depending on the old resolution.
• Remove any application-side factory workaround for custom media models once 1.3.1 is in place, so we do not carry two mechanisms.

Compatibility

• Confirm Laravel and PHP constraints in composer.json against our current runtime before scheduling; the constraint floor may have moved across 1.2/1.3.
• Confirm the production DB engine implements locking reads; if any environment uses SQLite (common in CI or local dev), document that concurrency tests are only meaningful against the production engine.
• Audit app code for attach(), copy(), replace(), forceDelete(), and any custom deduplication configuration — these are where the 1.1.4-line behavior changes surface.
• Audit test code for media factories, model overrides, and class assertions — these are where the 1.3.1 change surfaces.

Sequencing

1. Read the 1.2.0 and 1.3.0 release notes; fold any findings into this plan before committing to the version.
2. Inventory call sites of attach(), copy(), replace(), forceDelete(), plus any custom deduplication configuration.
3. Add explicit handling for ModelNotFoundException at those call sites before upgrading, so the upgrade does not introduce unhandled exceptions.
4. Inventory media factory usage and any existing custom-model workaround in the test suite.
5. Review transaction scope: shorten any transaction that contains media writes so locks and deferred file deletions are held for the minimum time.
6. Upgrade in staging; run concurrency tests covering deduplicated add vs. force-delete, replace vs. concurrent sharing add, and forceDelete-in-rolled-back-transaction. In the same pass, run the full suite to confirm factory behavior.
7. Roll out to production behind normal deploy; restart queue workers so long-lived processes pick up the new code.
8. Keep the prior version pinned for fast rollback during the first week.

Operational Impact

Maintenance

Low ongoing maintenance. This release fixes a defect in test infrastructure rather than adding runtime features, so there is no new configuration to own and no operational surface added. The maintenance burden that does increase sits in the application layer: we own catching ModelNotFoundException, reasoning about transaction boundaries around media writes, and now also owning the media model override if we choose to use one. Document these invariants in the internal runbook so they survive team turnover.

Support

1.3.1 adds no new production failure mode, so the expected ticket shapes are unchanged: (a) unexpected ModelNotFoundException surfacing from attach/copy paths, and (b) reports of files still present after an apparent delete (correct behavior during an open transaction, or an orphan after a crash). Give the support team a diagnostic script that checks whether files exist on disk without a referencing row. The only new support surface is internal: developers confused by factories producing a different model class, which is a documentation fix, not a ticket category.

Scaling

Throughput on the media table becomes lock-bound rather than CPU-bound for concurrent writes to the same underlying file. Batch imports that deduplicate heavily against a small set of files will serialize more than before. Mitigations: spread imports across time or shards, cap worker concurrency per file key, keep transactions short, and avoid holding a transaction open across a network filesystem write. Read paths are unaffected. None of this is changed by 1.3.1.

Failure modes

• Lock contention / deadlock under concurrent dedup + delete. Expect occasional deadlock exceptions; decide now whether to retry at the application layer.
• ModelNotFoundException from attach() / copy() when the shared row is deleted mid-flight. Correct but must be handled; unmapped, it becomes a 500.
• Orphaned files if the process dies between commit and deferred deletion — the row is gone, the file remains. Needs a scheduled reconciliation job.
• Backup-copy disk pressure during in-place replaces inside long transactions; monitor disk headroom and cap transaction duration.
• Silent non-guarantee on unsupported engines (SQLite, MyISAM) — the safety story degrades without any error, which is the most dangerous failure mode because it is invisible.
• Test-only divergence if a host overrides the media model and the application no longer exercises the same class in tests as in production, or vice versa after a partial rollout of the workaround removal.

Ramp-up

Small but real. Engineers need one focused briefing covering: media operations belong inside transactions; transactions containing media writes must be short; ModelNotFoundException is an expected outcome in some races, not a bug; file deletion is commit-time, not call-time; and media factories now build whichever model is configured, so do not hardcode the base class in tests. Plan roughly half a day of team enablement plus an hour of staging validation against the production database engine, and add the changelog review for 1.2.0/1.3.0 as a short pre-work item before the upgrade goes out.