Files Media Filament Laravel Package

Getting Started

This package is a presentation adapter: it wires the Filament admin UI to the underlying liberusoftware/module-files-media domain module. Nothing here stores files by itself — the base module owns models, storage, and conversions; this package gives you Filament resources, form fields, and table columns on top of it. Understand that split before you write a line of code, or you'll waste time debugging the wrong layer.

Minimal steps:

composer require liberusoftware/files-media-filament

1. Read the base module first. Open liberusoftware/module-files-media (its README, migrations, and HasMedia-style trait). This adapter is thin, and every real question — disks, conversions, model relationships — is answered there.
2. Check the composer constraints. Run composer show liberusoftware/files-media-filament and confirm the Filament major version it requires matches your panel (filament/filament:^3.0 vs ^4.0). A mismatch here is the most common install failure.
3. Publish and migrate whatever the base module ships:

php artisan vendor:publish --tag=files-media-config
php artisan vendor:publish --tag=files-media-migrations
php artisan migrate

4. Register the plugin in your panel provider. Depending on the release, this is either a Filament plugin (->plugin(FilesMediaPlugin::make())) or a service provider listed in bootstrap/providers.php. Check the repo's src/ for a *Plugin.php or *ServiceProvider.php to see which pattern this version uses.
5. Look here first: the package's src/Filament/Resources/ (or src/Resources/) directory. That is the entire surface area of the adapter — resources, forms, and tables. If it isn't there, it isn't in this package.

First use case: attach an existing media item to a domain model. Create a resource that uses the base module's media relation, drop the adapter's file/media form component into the form schema, and confirm an upload lands on the expected disk. Do that end-to-end on a throwaway model before touching production resources.

Implementation Patterns

Treat the adapter as UI glue, not a library. The patterns below assume you follow the base module's trait/contract conventions and only use this package for Filament components.

• Form fields. Add the adapter's media upload/picker component to a resource form schema. Configure the disk and directory explicitly rather than relying on defaults — the base module's config is the source of truth, but panel-level overrides are common:

  MediaPicker::make('featured_image')
      ->disk(config('files-media.disk'))
      ->directory('featured');
  

• Table columns. Use the adapter's thumbnail/preview column for list views and avoid loading full-size URLs in tables. Prefer a conversion (thumbnail) column over the original.
• Reuse the base model, don't fork it. If you need a new "collection" or "type" (avatars, documents, galleries), configure it in the base module's config or via its relationship API, not by subclassing the Filament resource. Subclassing the shipped resource is a maintenance trap because your overrides will drift on the next release.
• Multi-panel setups. If you have an admin panel and a staff panel with different access rules, register the plugin per panel and gate visibility with Filament policies. Do not rely on the adapter to enforce authorization — it typically doesn't.
• Policy placement. Media authorization usually belongs on the base module's model policy. Put viewAny/create/delete there and let Filament pick it up. This keeps the adapter panel-agnostic.
• Integration tip — attach after create. For "upload then associate" flows, create the parent record first, then attach media in the afterCreate hook (or use a relation manager). Filament's file upload lifecycle and the base module's attach logic don't always cooperate in a single create() call.
• Relation managers over inline fields for anything with more than one file. A MediaRelationManager on the parent resource is more predictable and gives you delete/reorder for free.
• Testing pattern. Assert on the base module's database rows and storage fake, not on Filament component internals:

  Storage::fake('public');
  // Livewire::test(...)->fillForm(...)->call('create');
  Storage::disk('public')->assertExists(...);
  

Gotchas and Tips

• License is NOASSERTION. That is not a green light. Before shipping to a client, read the LICENSE file in the repo and confirm terms with whoever owns the product. This is the single biggest blocker for production use.
• Maturity: 0 stars, 0 dependents. Treat every release as potentially breaking. Pin an exact version ("liberusoftware/files-media-filament": "1.2.3") and diff the src/ tree between updates rather than trusting semver.
• Last release date is in the future relative to typical assessment windows — verify the tag actually resolves on Packagist with composer show -a. If it doesn't, fall back to a VCS repository entry pointing at a commit.
• Filament version drift is the top failure mode. If you see Class "Filament\..." not found or Method ... does not exist, you almost certainly have a Filament v3/v4 mismatch. Check composer.json in the package against your panel.
• The adapter's defaults are not your defaults. Disks, directories, and max upload sizes commonly fall back to the base module's config, which itself often falls back to Laravel's filesystems.default. Trace the whole chain once:

  php artisan config:show files-media
  

  Then clear caches (php artisan config:clear && php artisan filament:cache-components) after any change — Filament's component cache will happily serve you stale schemas.
• Storage symlink. Thumbnails and previews need php artisan storage:link on the server. Missing symlinks produce broken images with no error, which is easy to misdiagnose as an adapter bug.
• Debugging trick: when a component renders blank or throws on a resource form, comment the adapter's component out and confirm the form works without it. That isolates "adapter problem" from "your form schema problem" in one step.
• Extension points to prefer: the base module's config, its HasMedia trait, model policies, and Filament's own extension mechanisms (relation managers, custom columns, closures on components). Avoid editing files under vendor/liberusoftware/ — composer will overwrite them.
• Document your own integration. With a package this thin and this unmaintained-looking, the real knowledge is in how your app wires it. Leave a short note in your repo (which panel, which disk, which collections) so the next developer doesn't reverse-engineer it from vendor/.
• Have an exit plan. Because the adapter is thin presentation code, replacing it with hand-written Filament components over the base module is genuinely feasible. Keep the base module's trait as the stable contract so a future swap costs days, not weeks.