Filament Draftable Laravel Package

Getting Started

The v1.1.0 release widens Filament compatibility to v4 and v5, so the first job is pinning which of the two your application actually runs before touching anything else.

1. Check your Filament version first.

   composer show filament/filament | grep versions
   

   If you are still on v3, this package will not install — the v1.1.0 constraint targets v4/v5 only.

2. Install against the right major.

   composer require <vendor>/<package>:"^1.1" -W
   

   The -W (--with-all-dependencies) flag matters here: because the package now allows two Filament majors, Composer may otherwise resolve a combination your other Filament plugins do not support.

3. Register the plugin on the panel, not globally. Filament v4/v5 both expect plugin registration in the panel provider:

   use <Vendor>\<Package>\<Package>Plugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(<Package>Plugin::make());
   }
   

4. Publish anything the package ships (config, migrations, assets) and rebuild Filament's asset cache:

   php artisan vendor:publish --tag="<package>-config"
   php artisan filament:assets
   

   If the package registers its own CSS/JS through FilamentAsset::register(), skipping filament:assets is the single most common cause of "the UI renders but nothing is styled".

Where to look first: the package's own Plugin class (it tells you exactly what gets registered: resources, pages, widgets, render hooks), then its composer.json require block — that is the authoritative statement of which Filament majors and which Livewire/Tailwind versions are actually supported.

First use case: register the plugin on one non-production panel, load a single page or resource that uses it, and confirm the assets resolve. Getting one page rendering end-to-end on your Filament major is the fastest way to validate the whole install.

Implementation Patterns

Version-gated code paths. With two supported Filament majors, any application code that extends or overrides package behaviour needs to branch. Prefer checking the installed major once, in a service provider or helper, rather than scattering version_compare calls through views:

// e.g. a small support class
public static function filamentMajor(): int
{
    return (int) Str::before(Composer\InstalledVersions::getPrettyVersion('filament/filament'), '.');
}

Then gate only the spots where the v4 and v5 APIs diverge — form/table schema method names, action classes, and asset registration being the usual suspects.

Panel-scoped registration. Register the plugin only on the panels that need it. In multi-panel apps (e.g. AdminPanel + AppPanel), a plain ->plugin(...) call in a shared provider leaks the package's navigation entries and widgets into every panel. Register per-panel, or wrap in a config flag:

$panel->plugin(<Package>Plugin::make())
      ->when(config('features.<package>'), fn ($panel) => $panel);

Configure, don't fork. If the package exposes a fluent plugin API (->navigationGroup(), ->shouldRegisterNavigation(false), etc.), use it in the panel provider rather than subclassing the package's pages. Subclassing couples you to internal method signatures that are the most likely thing to shift between Filament majors.

Test against both majors in CI. This is the pattern that pays for itself immediately. A GitHub Actions matrix with filament/filament:^4.0 and ^5.0 will catch the majority of compatibility breakage before your users do:

matrix:
  filament: ['^4.0', '^5.0']

Pair it with orchestra/testbench and Filament's own testing helpers (livewire(Page::class)->assertOk()).

Integration points that hold across versions. Register the plugin, publish config, extend via the package's documented extension points (custom resource pages, custom widgets, render hooks), and keep any Filament-version-specific glue in one thin adapter layer. Everything else — your own business logic — should be version-agnostic.

Gotchas and Tips

• Composer "works on my machine" resolutions. Allowing two Filament majors means composer update can silently move a consumer from v4 to v5 if nothing else pins it. Commit composer.lock, and consider pinning the major explicitly in applications (filament/filament:^4.0) while letting the package stay permissive.

• Stale published assets after upgrading. Filament publishes versioned asset files. After any Filament or package upgrade, re-run php artisan filament:assets and hard-refresh the browser. A surprising number of "v5 broke the styling" reports are just cached v4 assets.

• Cache invalidation in production. Filament caches components and Blade icons. After deploying the upgrade, run the full sequence: php artisan filament:clear-cached-components, php artisan view:clear, php artisan config:clear, then re-cache. Skipping this yields "page not found" errors for pages that plainly exist in the codebase.

• Plugin registration order matters. Plugins that add render hooks or navigation are applied in registration order. If the package's nav entries appear in an unexpected place after upgrading, check where it sits relative to other plugins in the panel provider.

• Navigation and tenancy interactions. If you use Filament tenancy, verify the package's resources respect the tenant scope on both majors — tenancy handling is one of the areas where v4 and v5 behaviour differs most.

• Debugging a blank or 500 page. In order: check storage/logs/laravel.log, confirm the plugin is registered on this panel, confirm the user passes the package's authorization checks/policies, then confirm assets are published. The package's own resources are usually gated, and a silent 403 looks identical to a broken install.

• Extension points to prefer. Config file, plugin fluent API, and published views (with a view namespace you can override) are the stable surfaces. Avoid overriding the package's Livewire components by class name unless the package documents that as supported — those are the classes most likely to be renamed between Filament majors.

• When in doubt, read the package's upgrade/CHANGELOG for the exact Filament version each release targets. Since v1.1.0 is the first release spanning two majors, it is worth confirming whether the maintainers intend v4 and v5 to be equally supported or whether one is already in maintenance mode.