Photonic Filament Laravel Package

Getting Started

digitonic/photonic-filament is the Filament bridge for Digitonic's Photonic image package — it gives you Filament form fields and table columns for uploading and rendering Photonic-managed images instead of hand-rolling a FileUpload plus your own conversion logic.

Before you install, check the version gate. 3.0.0 is described in the release notes only as "Laravel 13 upgrade". In practice a major bump driven by a framework upgrade almost always means the package's composer.json now requires laravel/framework ^13.0 and a matching Filament major (filament/filament ^4.0). Confirm both before you start:

composer show digitonic/photonic-filament --all | grep -A2 requires

If you are still on Laravel 11/12 or Filament 3, stay on the 2.x line and plan the framework upgrade first — this is a hard constraint bump, not a deprecation path.

Order of operations:

1. composer require digitonic/photonic-filament:^3.0 (let it pull digitonic/photonic as a dependency).
2. Publish and review config — php artisan vendor:publish --tag=photonic-config (tag name may differ; check vendor/digitonic/photonic-filament/src/*ServiceProvider.php for the actual publish tags).
3. Run migrations for Photonic's storage tables if you have not already; this package provides UI, not the schema.
4. php artisan storage:link and set the disk/visibility Photonic expects in config/photonic.php.
5. Register the plugin/provider in your panel if it ships a Filament plugin object — look in the package's src/ for a class implementing Filament\Contracts\Plugin and add it to your PanelProvider::panel()->plugins([...]).

Where to look first:

• vendor/digitonic/photonic-filament/src/ — the field and column classes are the entire public surface; there will be very few of them.
• The README's usage snippet — for a package this small the README is the documentation.
• vendor/digitonic/photonic/ — most of your debugging will land here, not in the Filament wrapper.

First use case: replace a plain FileUpload::make('image') in one Resource form with the Photonic field, render the thumbnail in the table, and confirm the file lands where Photonic's config says it should. Do this on one resource before rolling it across the admin panel.

Implementation Patterns

Treat the package as a thin adapter. Your leverage is in Photonic itself (image sets, transformations, storage abstraction); the Filament package just wires those into the form/table lifecycle. Keep conversion and sizing rules in config/photonic.php so multiple Resources share them, rather than passing per-field overrides that drift.

Form field pattern. Typical shape, adjusting names to what's actually in src/:

use Digitonic\PhotonicFilament\Forms\Components\PhotonicImage;

PhotonicImage::make('hero_image')
    ->imageSet('hero')          // a named set defined in config/photonic.php
    ->disk('public')
    ->required();

Define hero, thumbnail, og etc. once as named image sets and reference them everywhere. That is the single biggest day-to-day win over raw FileUpload: the transformation contract lives in config, not in twenty Resource classes.

Table column pattern. Pair the form field with the package's column so list views render the correct derived size rather than the original upload:

PhotonicColumn::make('hero_image')->imageSet('thumbnail');

If the package only ships a form field, add a ImageColumn with a closure resolving the URL from the Photonic model — but check first, because reimplementing this is exactly what you're paying the dependency for.

Consistent placement across a panel. If you have more than a handful of Resources, add a small base Resource or a trait (HasPhotonicMedia) that declares the field/column pair for common attributes (cover image, avatar, gallery). New Resources then get compliant uploads by default instead of each developer inventing their own.

Queue it. Photonic transformations are the expensive part. Ensure a worker is running in every environment including local and staging — if conversions are queued and the queue is dead, uploads appear to succeed and images silently render at original size. This is the most common "the package is broken" report and it is almost never the package.

Testing. Use Storage::fake('public') and Filament's livewire() / fillForm() test helpers to assert the file is stored and the record references it. Because the field wraps Photonic, assert against Photonic's model/attachment rather than a raw path — that keeps tests stable if the internal storage layout changes between majors.

Upgrade workflow for 3.0.0 specifically. Since the changelog is a single line, do not trust it as a complete description. Diff the tags before merging:

composer require digitonic/photonic-filament:^3.0 -W
git diff 2.1.0 3.0.0 -- vendor/digitonic/photonic-filament

Read composer.json (constraints), any UPGRADE.md, and the field class signatures. Then exercise one upload, one edit-with-existing-image, and one delete in a staging panel — those three flows cover most of what a wrapper like this can break.

Gotchas and Tips

The release notes are the main risk. "Laravel 13 upgrade" with no migration notes means the burden of discovering behavioural change is on you. Two realistic scenarios: (a) it is a pure constraint bump and 3.0.0 is a drop-in once you're on Laravel 13 — most likely given the single PR; (b) the Filament major moved underneath and the field's API shifted with it. The version number alone cannot distinguish these, so verify with the diff rather than the changelog.

Major version = read the constraint, not the feature list. The breaking change here is almost certainly "drops Laravel ≤12 / Filament ≤3", not a redesign. That matters for monorepos and packages: if any sibling package pins the old framework, you cannot partially upgrade. Resolve the whole dependency graph with -W and expect conflicts.

Config cache will bite you. After changing anything in config/photonic.php — disks, image sets, quality — run php artisan config:clear (and config:cache in deploy). Stale cached config producing "wrong size" or "wrong disk" bugs looks like a package defect and is not.

Disk visibility and URLs. A private disk plus a public URL expectation yields broken images with a 200-ish page and no obvious error. Set explicit visibility on the disk and confirm the generated URL matches what storage:link actually serves. Check both config/filesystems.php and Photonic's own disk setting — they can disagree.

Orphaned files on delete. Filament deleting the record does not necessarily delete the underlying Photonic image or its derivatives. Wire cleanup in a model observer / deleting hook, and decide deliberately whether an image is shared (don't delete) or owned (do delete). Do this before production, not after the bucket fills up.

Livewire temp uploads. Large images can hit Livewire's temporary upload rules (TemporaryUploadConfiguration, max upload size, PHP upload_max_filesize/post_max_size) before Photonic ever sees them. If uploads fail only for big files, the failure is upstream of this package — check livewire.php and PHP ini first.

Extension points are thin, so prefer composition. Rather than subclassing the field (fragile across majors), wrap it in your own factory method or trait. That way a 4.0.0 bump touches one file in your codebase instead of every Resource.

Debugging order when an image doesn't appear: (1) is the file on disk at the expected path, (2) is the queue worker alive and did the conversion job run, (3) does the URL resolve with the right disk visibility, (4) only then suspect the Filament field. Log the resolved disk/path from Photonic's model before you start reading vendor source.

Pin sensibly. Given how terse the changelog is, use ^3.0 in composer.json (patch/minor safe) and read the diff on each bump rather than floating *. For a package whose entire surface is a couple of UI components, a five-minute diff review is cheap insurance.