Filament Media Library Laravel Package

Getting Started

The package targets PHP 8.3+, Laravel 12/13, and Filament 5 as of 1.3.0 — verify these in composer.json before adding it to a legacy Laravel 10/11 app, since the constraint bump in this release is a hard floor.

Minimal setup:

1. composer require crumbls/filament-media-library
2. Publish and run the migration/config: php artisan vendor:publish --tag="filament-media-library-migrations" then php artisan migrate. Re-publish the config if you already had it published — new keys are silently missing otherwise.
3. Add the package's media trait/interface to any model that should own media (e.g. Post).
4. Register the plugin on the panel you actually want it on, in app/Providers/Filament/*PanelProvider.php — not globally, since 1.3.0 adds explicit coverage for panel authentication and tenant scoping.
5. php artisan storage:link and confirm the disk in the config exists.

First use case: attach an image to a Post from a Filament form, then render it in the resource table. That single flow exercises the upload → media record → conversion/URL path and will surface any disk or queue misconfiguration immediately.

Where to look first: the config file (disk, conversions, accepted mime types), then the resource/table component registration, then the migration to confirm the media table's column names before you write queries against it.

Implementation Patterns

Panel-scoped registration. Register the plugin inside the panel you need, and let the package's auth checks govern access. Because 1.3.0 adds panel-authentication test coverage, the expectation is that media browsing respects the panel's guard — don't hand-roll a second authorization layer on top, but do verify it against your non-default guard if you have one.

Tenant-aware media. With tenancy enabled on the panel, the media table filters to the current tenant. Add a tenant_id (or your scoping key) to the media table and populate it in the owning model's save path, or rely on the package's scoping if it manages the column for you. Test tenant switching explicitly — this is the highest-risk area for cross-tenant leakage.

Model-centric attachment. Treat media as owned by an Eloquent model rather than as standalone uploads. Conversions, responsive URLs, and cleanup then follow the model lifecycle, and cascade deletes are the model's concern rather than something you wire by hand.

Post-upload processing via events. Use the package's events to trigger downscaling, AI tagging, or CDN purging rather than putting that work in the form's afterCreate. Keep listeners queued; uploads are already the slow path.

Validation at the edge. Rely on the package's file validation for mime/size, and layer your own Rule objects for business constraints. Validate in the form and in the model/action layer if media can be attached outside Filament (API, imports) — the Filament validation only covers Filament.

Testing pattern. 1.3.0's harness coverage (media table, auth, events, validation, tenancy) is a good template: use Livewire::test() against the media table and form components, Storage::fake() for the disk, and Event::fake() to assert post-upload events fire. Copy the shapes from the package's own tests rather than inventing them.

Gotchas and Tips

• 1.3.0 is mostly a compatibility and hygiene release. No deprecations or breaking API changes are announced, but the Laravel 13 / PHP 8.3 floor is a breaking constraint for older apps. Pin ^1.2 if you can't move PHP yet.
• Filament 5 upgrade friction is real. The test-harness update implies Filament 5's table and media-table APIs shifted. If you're coming from Filament 4 with this plugin, re-check any custom column/action overrides on the media table — they're the most likely silent breakage.
• Disk vs. URL mismatch. The classic failure: conversions write to a private disk while the table tries to render a public URL. Check the config's disk and visibility settings before debugging the component.
• Conversions need a worker. If processing is queued, an idle queue:work looks identical to "the plugin is broken." Check failed_jobs first.
• Tenant scoping bugs are quiet. A missing tenant column doesn't throw — it just shows everything. Assert row counts per tenant in tests.
• Config drift on upgrade. Always diff the published config against the package's stub after a minor bump; unchanged defaults are merged but deleted keys aren't restored.
• Static analysis is now trustworthy. 1.3.0 repaired the PHPStan config, so if you run PHPStan against your own code, expect new (correct) reports around generic types on model relations — don't suppress them wholesale.
• Extension points: custom media model via the config, custom conversions, and event listeners are the intended seams. Prefer those over forking the table component; the Filament 5 churn in this release shows components are the least stable surface.
• Distribution archive is leaner. If you vendor the package into a private mirror, note the archive no longer ships test files — don't expect the test suite to be present downstream.