Mediasort Laravel Package

Technical Evaluation

What we are actually evaluating. The description and the 2.0.9 release notes describe two different products. description.md is unambiguously a rule-based media file organizer — it takes an uploaded file, applies a rule (extension, MIME type, custom callback) and moves or copies it to a configured destination directory on a Laravel filesystem disk. The package name (mediasort = sort media), the "Attachment manager for Laravel" tagline, and the 2.0.9 note about "checking if a file was uploaded before it's processed" all support that reading. The internal engineering assessment, by contrast, spends its length on a sortable/Eloquent position-column trait (drag-and-drop reordering, position columns, scoped collections, reorder endpoints). That is a different capability and, most likely, a different Torann package. The two internal artefacts cannot both be right, and we should not book roadmap capacity against either until someone spends half a day in vendor/torann/mediasort/src. This is the single most important finding on the page.

Architecture fit (assuming the media-organizer reading is correct). Reasonable fit for a Laravel-native application that already routes uploads through Laravel's filesystem abstraction (local disk or S3). It sits between the upload controller and the disk: you hand it a file, it decides the destination and performs the move/copy. That is a narrow, testable seam. It does not fit cleanly if we already run a media lifecycle owner — Spatie Media Library, a DAM, or Cloudinary/imgix — because we would then have two components deciding where a file lives, and storage layout drift is expensive to unwind. It is also a poor fit for anything that needs transformations, variants, or CDN URL generation; this is placement, not media management.

Integration feasibility. Mechanically trivial: composer require, publish the service provider config, register the facade if not auto-discovered, define rules. Cost is measured in hours for a pilot surface, assuming the source matches the description. The risk is not effort, it is certainty — 20 stars, 0 dependents, one maintainer, BSD-2, no published security policy. There is no community evidence that this behaves as documented under Laravel 12, and the changelog/description mismatch is itself evidence that documentation is not maintained to a standard we can plan against.

Security surface. Media handling is a security-adjacent domain, not a convenience domain. Any component that decides a file's on-disk path must have a defensible answer on: MIME sniffing vs. client-supplied content type, filename sanitisation and path traversal, executable-file placement relative to the web root, and public/private disk visibility. None of that is evidenced in the material provided. A TPM should treat "we will read the source for these four behaviours" as a release gate, not a code-review nicety.

Technical risk summary. Low blast radius (small, forkable, BSD-2), low certainty (undocumented, low adoption, doc drift). The mitigations are cheap: a wrapper, a pilot, a pinned version. The risk is tolerable only because the code is small enough that forking is a realistic exit — that is what makes the bus factor survivable.

Key questions to answer before any commitment:

1. Does the package attach media records to Eloquent models, or only move files on disk? (Determines whether it replaces or complements our upload code.)
2. Does it own the disk configuration, or read ours? Will it fight an existing config/filesystems.php?
3. What happens on move across disks (local → S3)? Copy-then-delete, non-atomic, and what cleans up the orphan on failure?
4. Are rules evaluated deterministically, and what is the fallback when no rule matches — throw, or pass through?
5. Does it validate MIME type itself, or trust the client?
6. Is there a transaction/queue boundary, or is placement synchronous inside the request?
7. What does the published config actually contain, and how much of it is per-model vs. global?
8. Which Laravel/PHP versions are proven, not merely "supported" in a changelog line?
9. If a record is deleted, does the file get deleted — or do we own that cleanup?
10. Is 2.0.9's Laravel 12 claim tested in CI, and can we see the matrix?

Integration Approach

Stack fit. Laravel 12 (per 2.0.9) is the target and removes a version constraint; confirm PHP 8.2+ from composer.json rather than trusting the release note. The natural home is an app that already has upload endpoints, a filesystems config, and (ideally) a queue worker for post-upload processing. It is a backend plumbing dependency, so there is no user-facing surface to design, no frontend coordination, and therefore no cross-team scheduling cost — which is why it can be piloted inside a single squad's cycle.

Migration path. Do not migrate existing media. Existing files stay where they are; new uploads on one surface go through the package. That gives us a controlled comparison — old path and new path co-existing behind a config flag — without a storage backfill, which is the genuinely expensive part of any media change and would dwarf the package's value. If the pilot succeeds, the second surface is a small, known increment; if it fails, we delete a wrapper class and one config block.

Compatibility checks up front (half a day, timeboxed):

• Facade alias and config-publish name collisions with existing providers.
• S3/Storage::disk() behaviour: temporary URLs, visibility, and whether move on S3 is copy+delete.
• Interaction with any image-processing dependency (Intervention, Glide) and whether it expects a local path.
• Laravel 12 + PHP version in CI, verified by actually running the test suite or a scratch app.

Sequencing.

1. Source read and API confirmation (½–1 day). Read src/, run the key questions above, and correct our internal record — the ordering-vs-placement confusion must be resolved before anyone estimates anything.
2. Internal adapter (½ day). One small interface (MediaPlacement::store(UploadedFile $file, string $context): string) so no controller, job, or Blade template calls the package directly. This is the whole insurance policy and it costs almost nothing.
3. Pilot on a low-stakes surface (2–3 days). An internal admin upload, an avatar, a document upload — not customer-visible, not revenue-adjacent.
4. Feature-flagged rollout to a second surface, with the old code path retained for one release as a rollback.
5. Decide: adopt / fork / replace. Forking is a legitimate terminal state here; budget it as an option, not a failure.

What we should not do: adopt this as the storage authority for a customer-facing upload flow while the documentation is unresolved, or adopt it as a replacement for an existing media library. Both convert a weekend-sized decision into a quarter-sized migration.

Operational Impact

Maintenance. Pin the exact minor version (~2.0.9), record it in the dependency register with a named owner and an explicit note that a vendored fork is acceptable, and review it once per quarter or on each Laravel major — whichever comes first. Do not let a framework upgrade be gated on this package's release cadence; the fork clause exists precisely so it isn't. Total ongoing maintenance is genuinely low: small surface, BSD-2, nothing to configure beyond rules.

Support. There is no vendor, no SLA, no published security policy, and one maintainer. Internal support is therefore "whoever owns the adapter." Define that before adoption, not after the first incident. If the pilot succeeds, the runbook is short: where rules live, where the config lives, how to add a rule, how to trace a misplaced file.

Scaling. Placement is file I/O, so the cost profile is storage bandwidth and latency, not CPU. Two things follow: for anything user-facing, placement should happen off the request path (queue job), and cross-disk moves (S3) will be slower and non-atomic. At high upload volume the package itself will not be the bottleneck — the disk will — but a synchronous placement step inside a request will show up in p95 latency, so plan the queue boundary on day one rather than retrofitting it.

Failure modes to design for now:

Ramp-up. For a Laravel developer: one to two days to be productive, most of which is the mandatory source read and the first rule set. There is no meaningful documentation ramp because there is no meaningful documentation — the source is the documentation, and the team should treat that as an accepted, budgeted cost rather than a surprise. The adapter pays off here too: new engineers learn one internal interface instead of one obscure package.

Recommendation. Proceed to a timeboxed, single-surface pilot behind an internal adapter, contingent on resolving the description/changelog contradiction and confirming the four security behaviours. Do not put it on the critical path for a customer-facing upload flow, and do not let it displace an existing media library. The opportunity is real and small; the honest framing to stakeholders is "cheap, reversible, low-adoption convenience dependency," not "platform capability."