Gallery Json Media Laravel Package

Technical Evaluation

Architecture fit

• Stores an entire gallery as a JSON array on the owning model (images, documents columns cast to array) via the InteractWithMedia trait and HasMedia contract. There is no media table, no polymorphic relation, and no asset registry — this is a deliberate trade: minimal schema, fast reads for page-render use cases, no ability to query, dedupe, or reuse an asset across records.
• Strong fit for CMS-lite panels: content pages, blog posts, product galleries, small document sets where media belongs to exactly one record and is rendered, not managed centrally.
• Poor fit where media is a first-class entity: cross-model reporting ("all PDFs over 10MB"), shared/brand libraries, per-asset permissions, CDN conversion pipelines, or anything needing signed, expiring URLs.
• The package's real value is the vertical slice it owns: Filament field → JSON persistence → Blade fluent API (getMedias(), getDocuments(), withImageProperties(), withView()). The front-end API is decoupled enough to survive a later swap; the admin-side field is tightly coupled to Filament's form internals and will move with every Filament major.
• Verdict: adoptable as a scoped UI convenience for a bounded set of content models; not adoptable as the application's media backbone.

Integration feasibility

• composer require, publish config, optionally translations and views. First working field is roughly 1–2 hours for a developer already fluent in Filament.
• Hard prerequisites: PHP ^8.2, spatie/image, a Filament custom theme with the CSS @import added, and storage:link. The theme build is the only step that reliably surprises teams — it means a compiled asset pipeline change, not just a composer line.
• Version-to-branch matrix must be pinned explicitly in composer.json: Filament v3 → 3.x, Filament v4 → 4.x, Filament v5 → 5.x. This is a branch-per-Filament-major project, so the constraint is a forward-compatibility commitment, not a version range.

Technical risk

• Bus factor 1, 19 stars, 0 dependents, single maintainer (webplusm). Treat as a vendored dependency: pin exact versions, mirror the repo, and budget for self-patching.
• Public disk only — explicitly "NO S3". For most production stacks this is a hard blocker or a mandatory code change, not a config toggle. It also means no private documents; JsonDocumentsEntry downloads are effectively public URLs.
• Implicit JSON schema. The payload (path, custom properties, width/height) has no documented version field. v5.5.0 had to ship a gallery-json-media:regenerate command and a maintenance.models registry specifically to backfill dimensions on already-stored records — evidence that schema evolution arrives as data migrations you must plan for.
• Crop URL generation has already changed shape (v4.1.0 "crop URLs without tokens"). Any stored or cached URLs from earlier versions are upgrade-sensitive.
• Changelogs are low-information ("wip", "fix", "chore"); release notes occasionally describe behavior changes only after the fact. A GH Actions test suite exists, which is the main quality signal available.
• SVG is accepted (explicitly handled for dimensions) — validate whether that is served inline, which is a stored-XSS surface.

Key questions for the maintainer/team

1. Is the JSON media payload versioned, and is there a documented upgrade contract for Filament v6 / Laravel 14?
2. Is non-public / S3 disk support on the roadmap, or is "public only" permanent?
3. Are crop URLs authorizable, or are they capability-by-obscurity?
4. Are uploads MIME-validated and re-encoded, or stored as received (SVG)?
5. What is the intended gallery size ceiling before JSON decode and per-request thumbnail work become the bottleneck?
6. What is the fallback if the package is abandoned mid-cycle — how many call sites would we own?

Integration Approach

Stack fit

• Laravel 11/12/13 + Filament v3/v4/v5, PHP 8.2+, spatie/image with the GD or Imagick driver, local public disk. Confirm the app is not already multi-node without a shared volume before committing.
• If the platform standard is S3/private storage, stop here and evaluate spatie/laravel-medialibrary with a Filament plugin instead — the visibility constraint will not be worked around cheaply.

Migration path

• Greenfield: add nullable json columns to the target models, add the trait and casts, register getFieldsToDeleteMedia(). No backfill required.
• From a single image string column: wrap into a one-element array per row in a one-off migration — cheap and reversible.
• From spatie/laravel-medialibrary: write a bespoke command that maps collections to the JSON descriptor shape, leaving files in place, and run both systems in parallel (medialibrary tables read-only) until the Blade templates are cut over. This is a real project, not a migration script.
• Register every target model in maintenance.models and run gallery-json-media:regenerate --dimensions-only (or full) in staging before production, so responsive srcset and crop ratios are correct at launch rather than after a defect report.

Compatibility

• Verify Filament theme build in CI, not just locally — a missing CSS import silently degrades the field to unstyled markup and is easy to miss on a green test suite.
• Pin the branch to the Filament major in lockstep with the panel upgrade; never bump Filament majors without a corresponding package branch change and a staging pass over upload/crop/reorder.

Sequencing

1. Spike on one low-value content model in staging; validate upload, crop, reorder, custom properties slide-over.
2. Validate the theme CSS import and storage:link in a built asset.
3. Wire the Blade front end on one page using the fluent API and a custom view — prove the rendering contract before widening.
4. Run gallery-json-media:regenerate against real data; confirm dimensions and thumbnail regeneration.
5. Roll out model by model, front-end and back-end together.
6. Stand up an orphan-file sweep before the second model lands, not after.

Operational Impact

Maintenance

• Ongoing cost is not the package's code, it's the upgrade tax: every Filament major implies a package branch move, a theme rebuild, and a data/URL compatibility review. Budget one focused engineer-day per Filament major with a staging validation pass, plus contingency for a self-patch if releases lag the next Filament beta.
• Treat the repository as a fork candidate. Pin exact tags, vendor the source, and keep a short internal patch log. Thin, occasionally post-hoc release notes make "read the diff" the only reliable upgrade procedure.

Support

• Community Discord thread and GitHub issues only; no commercial support or SLA. Internal ownership must be named before adoption, and the runbook should cover: regenerate command usage, maintenance.models registration, theme CSS rebuild, and disk-move recovery.

Scaling

• Public-disk-only is the scaling ceiling: horizontal app scaling requires a shared network volume, and a move to object storage is an integration project, not a config change.
• JSON decode happens per model hydration. Safe for galleries in the tens; on index tables rendering many rows with JsonMediaColumn, expect payload bloat and heavier responses. Cap maxFiles at the field level as a guardrail.
• Thumbnail creation appears synchronous on upload/crop, so image CPU lands on web nodes. Keep maxSize conservative, prefer GD where Imagick memory is a concern, and consider offloading heavy cropping to a queue if galleries grow.

Failure modes (ranked by likelihood × damage)

1. Orphaned files after force-deletes, bulk query-builder deletes, or cascade deletes that bypass model events — the trait's getFieldsToDeleteMedia() only fires on proper Eloquent lifecycle. Silent disk growth; needs a scheduled sweep.
2. Broken or unresized images after a filesystem move or package upgrade — thumbnails and stored dimensions are not self-healing; the regenerate command is the only remedy and requires the model registry to be complete.
3. Concurrent edits to the same gallery — last-write-wins on the whole JSON column; two admins editing custom properties simultaneously lose one set of changes. Mitigate with editableCustomProperties() gating and editorial process, not code.
4. Missing casts — forgetting 'array' on the column produces string state and confusing form behavior; enforce in code review.
5. Unstyled gallery in production after a theme rebuild drops the CSS import.
6. SVG upload as an XSS vector if documents/images are served inline from the public disk.
7. Visibility misconfiguration exposing documents intended to be private — the package does not offer a private mode, so this must be designed around, not configured.

Ramp-up

• Roughly half a day for a Laravel developer comfortable with Filament: one field, one column, two infolist entries, one trait, one Blade loop. The observable API surface is small and the README examples are directly usable.
• Documentation is README-only with no API reference beyond examples; expect source reading for Media methods (getCropUrl, getCustomProperty, withImageProperties) and for the config surface. New hires will need a short internal note documenting the JSON shape and the regenerate workflow, since the package does not.