Sortable Gallery Laravel Package

Technical Evaluation

Architecture fit. tjmpromos/sortable-gallery is a narrow, opinionated feature package: a persisted, orderable set of images attached to an Eloquent model, surfaced through a Filament admin UI. It fits cleanly into the "admin panel owns content" pattern common in Laravel/Filament applications, where the public site reads from the same tables. It is not a general media library, a DAM, or a CDN pipeline — it solves one bounded problem (upload, order, delete, crop/convert maybe) inside one admin surface. That narrowness is the package's main architectural virtue: the blast radius is a migration, a trait on one or two models, and one Filament form/relation component.

The low star count and the personal namespace (tjmpromos) tell us this is a battle-tested-in-one-context extraction rather than a community-maintained standard. Treat it as high-quality sample code you are prepared to own, not as an upstream dependency you can lean on. For a TPM the relevant question is not "is it good?" but "is the code small enough that forking it costs less than rebuilding it?" At a glance, probably yes — a gallery component plus a pivot/order column is a few hundred lines.

Integration feasibility. Typical integration is mechanical: composer require, publish config/migrations, add a trait or interface to the owning model, attach the component in a Filament resource, register a plugin in the panel provider. The unknowns that determine real effort:

• Filament version coupling. Filament v3 → v4 introduced breaking changes in form/table APIs and asset registration. If the package pins ^3.0 only, you inherit a migration deadline on Filament's release cadence rather than your own.
• Storage semantics. Does it assume a public disk, a configurable disk, or spatie/laravel-medialibrary under the hood? Disk/CDN assumptions are the most common source of "works locally, breaks in prod."
• Ordering strategy. A dedicated order column with a reorder endpoint is simple and portable; a spatie/eloquent-sortable dependency is fine but adds a transitive upgrade surface. Either way, concurrent drag-and-drop needs a tie-breaker policy.
• Upload surface. Livewire temporary uploads inherit php.ini/upload_max_filesize, Livewire temp-disk, and Filament's image editor settings. These are configuration hazards, not code hazards, but they cause incidents.

Feasibility verdict: feasible for a single pilot panel in 1–3 days, contingent on one of the key questions below resolving favorably.

Technical risk.

Security exposure is modest but non-zero: the component handles file uploads, so MIME validation, SVG handling, and path traversal are the areas to review before exposing it to non-admin users. It is admin-only by design, which is the correct containment boundary — do not reuse it for end-user uploads without a review.

Key questions to resolve before committing:

1. Which Filament major versions are declared in composer.json, and is v4 supported or planned?
2. What are the direct and transitive dependencies, and are any abandoned or unmaintained?
3. Does it use spatie/laravel-medialibrary, custom columns, or a JSON blob for image metadata?
4. Is the order column unique per-owner-model, and how are collisions on concurrent reorder handled?
5. Disk/CDN configuration: configurable, or hard-coded to public?
6. Does it support multiple galleries per model, or one gallery per record?
7. Are there tests? Even a thin feature suite materially reduces our fork burden.
8. Does it honor Filament policies/authorization, or bypass them?
9. What happens to files and DB rows on delete — cascade, soft delete, orphan?
10. Is the maintainer responsive, and would they accept a PR for Filament v4 support (cheaper than owning a fork)?

Integration Approach

Stack fit. The package only makes sense if Filament is already the admin layer. If the team is on Nova, Backpack, or a bespoke Blade admin, this package is irrelevant and the correct decision is "do not adopt" — you would be importing a UI paradigm you cannot host. For a Filament shop, it is a strong fit: it uses the same conventions (panel plugins, form components, resource pages) the team already knows, so onboarding cost is near zero for anyone who has written a Filament resource.

Migration path. Because the package owns its own table(s), migration is additive and reversible:

1. Publish and inspect migrations; rename the table prefix to your project convention if it collides.
2. Add the trait/interface to a single low-traffic model (e.g., a Banner or CaseStudy), not the flagship content type.
3. Run staging with the production-like disk and CDN config, not local storage.
4. Backfill existing images through a one-off artisan command, preserving any existing sort order.
5. Only after a full release cycle, extend to additional models.

If you are replacing an existing hand-rolled gallery, keep the old read path alive behind a feature flag until the new component has served a full week of production traffic. The write path (ordering) is the risky part; the read path is cheap to dual-run.

Compatibility. Pin explicitly: PHP minor, Laravel major, Filament major. Do not allow ^ ranges to float across Filament majors — a composer update in CI should never be able to change the admin UI's component API. Verify DB support (MySQL 8 and Postgres both handle the ordering column; SQLite is fine for tests but masks concurrency issues). Confirm the package does not require a specific queue driver or filesystem adapter beyond what you already operate.

Sequencing. Recommend a four-step gate:

• Spike (0.5 day): install in a throwaway branch, render a gallery, upload, reorder, delete. Answer questions 1–5 from the code.
• Internalize (1–2 days): if the spike passes, vendor the source into packages/internal/gallery under your namespace, add a single feature test covering upload → reorder → delete → file cleanup. This converts an unmaintained dependency into an owned, tested module at low cost.
• Pilot (3–5 days): one model, one admin panel, staging soak, then production.
• Generalize (optional): only if a second use case materializes; premature rollout multiplies the fork's maintenance surface.

The decision gate is simple: if the spike fails on Filament version or disk assumptions and the maintainer is unresponsive, build the 200-line internal version instead. At this scale, forking and rebuilding cost roughly the same, and rebuilding removes the bus-factor risk entirely.

Operational Impact

Maintenance. Expect to own this. Last release April 2025 with 12 stars implies low ongoing investment; a single Filament major release can strand the package. Budget a recurring, low-but-nonzero allowance — roughly 0.5–1 engineer-day per quarter for dependency bumps, plus ~1 day per Filament major. After vendoring, the practical burden is "keep it compiling," which is manageable for a component this small. Establish a named owner (a specific engineer, not "the platform team") and a calendar reminder to review the upstream repo quarterly; if upstream ships a v4-compatible release, consider re-adopting to shed the fork.

Support. No commercial support, MIT license, community-only. That is acceptable only because the code is small enough to read in an afternoon. Do not adopt it for anything with a regulatory or revenue-critical surface where you'd need an SLA. Internal documentation matters more than usual here: record the pinned Filament version, the disk configuration, and the ordering semantics in your runbook so a future on-call engineer isn't reverse-engineering a package nobody remembers choosing.

Scaling. The admin surface is inherently low-QPS — a handful of editors, not user traffic — so the package is not a scaling concern on the write side. The scaling profile that matters is image delivery, which the package only partly addresses:

• Uploads are synchronous within the Livewire request; large files hit PHP upload limits and can time out the admin request. If originals are large, offload conversion to a queued job and make the component tolerate a "processing" state.
• Rendering the public gallery is your code, not the package's. Watch for N+1 queries when iterating gallery items and for un-resized originals being served to browsers. Conversions plus a CDN are the difference between a 200ms and a 3s page.
• Storage growth is unbounded unless deletions are handled. A monthly reconciliation job comparing DB rows against disk objects is cheap insurance.

Failure modes. The realistic incidents, in rough order of probability:

1. Uploads break after an infra change — disk credentials, bucket policy, or php.ini limits changed; the component surfaces this as a generic admin error. Mitigate with a synthetic upload check in staging.
2. Orphaned files on record deletion, silently accruing storage cost. Mitigate with observer-based cleanup plus a prune job.
3. Duplicate or non-deterministic ordering after concurrent edits, producing a gallery that "shuffles" on refresh. Mitigate with a unique constraint and deterministic secondary sort.
4. Filament/PHP upgrade breaks the component during an unrelated maintenance window, blocking editors. Mitigate by pinning and by keeping the fork on your own upgrade schedule.
5. Migration drift if the published migration is edited after deployment. Treat published migrations as immutable and layer changes in new ones.

Ramp-up. Low for anyone with Filament experience — roughly half a day to be productive, a day to be confident enough to modify. The real ramp-up cost is the reverse-engineering phase for a new owner six months later, which is why vendoring plus a one-page internal README (what it owns, what it assumes, how to upgrade) is worth the modest upfront effort. Editors need separate, minimal training: drag to reorder, delete, save — and explicit guidance on image dimensions and file size, since the component will happily accept whatever the upload limits permit.

Bottom line for the product decision. The package's narrow scope and MIT license make it a low-consequence bet: cheap to pilot, cheap to fork, cheap to abandon. Its risks are structural rather than technical — single maintainer, Filament-version coupling, unclear upstream longevity. Adopt only if (a) Filament is already the admin layer, (b) the dependency audit is clean, and (c) the team accepts ownership via a vendored fork. Score it as an accelerator of an already-planned gallery feature, not as a reason to build one.