Filament Oops Laravel Package

Getting Started

This release adds Filament v5 support, so the package now targets the current major of the Filament admin stack rather than the previous one. Treat the install as two decisions: which Filament major you are on, and which package major matches it.

1. Confirm your stack first. Check composer.json for filament/filament (or filament/support for lighter plugins). If you are on Filament v4, stay on the package's 2.0.x line; the 2.1.x line is for v5 panels.
2. Require the matching constraint rather than an open one:

   composer require vendor/package:"^2.1" -W
   

   The -W matters — without it Composer will happily hold back filament/* and you'll get an unsatisfiable set or a silent downgrade.
3. Register the plugin on the panel, not globally. This is the first place to look in the README, and the only line most apps need:

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

4. Publish and migrate, if the package ships config, migrations, or assets:

   php artisan vendor:publish --tag="package-config"
   php artisan vendor:publish --tag="package-migrations"
   php artisan migrate
   php artisan filament:upgrade
   

5. First use case: open the panel and hit the feature the package advertises (a resource, page, widget, or field). If it renders, registration is correct. If the panel 500s on boot, the plugin is almost always being registered against a Filament major it wasn't built for.

Implementation Patterns

Panel-scoped registration. Filament plugins register per-panel, which is the package's main integration seam. In multi-panel apps (e.g. AdminPanel + StaffPanel), register the plugin only where it belongs — this is also how you keep the upgrade blast radius small.

Config-first customization. Publish the config file and drive behavior from config/package.php rather than editing vendor views. This survives upgrades; edited vendor files do not. Re-publish after upgrading if the package ships new config keys, and diff against your copy.

Version gate in CI. Since the package now spans two Filament majors, add a matrix job or at minimum pin the Filament version in composer.lock and assert it in CI. A single composer update on a branch without a lockfile is the most common way this breaks.

Extending via published classes. Where the package exposes base classes (resources, pages, widgets), extend them in app/Filament/... and reference your subclass in the panel. This is the package's intended extension point and keeps you off vendor/ edits.

Testing. Filament panels are Livewire components, so use Livewire::test() against the page/resource class, and actingAs() a user with the panel's policies satisfied. Boot the panel explicitly in the test ($this->actingAs($user) plus the panel provider) — plugin-registration bugs surface here long before they hit staging.

Upgrade pattern from 2.0 to 2.1. Do it as a dedicated branch: bump the package and filament/* together, run php artisan filament:upgrade to republish assets, clear caches, then walk the panel manually. Filament majors routinely rename schema/table APIs, so expect view-level or form-definition edits in your own code even when the package itself is clean.

Gotchas and Tips

• Constraint drift is the number one failure. An open "filament/filament": "*" or "^4|^5" in the app can resolve to whichever major Composer prefers, and the plugin will register against a panel API it doesn't match. Pin, and let the lockfile arbitrate.
• filament:upgrade after every update. Filament publishes versioned CSS/JS assets; stale published assets are the classic "it works locally, broken in prod" symptom. Run it in your deploy script, not by hand.
• Clear config and panel caches in production. php artisan optimize:clear (or config:clear + filament:optimize-clear) after deploy. Filament caches component discovery, so a newly registered plugin can appear inert until the cache is dropped.
• Registration order can matter. If two plugins both touch the same navigation group or resource, ordering in ->plugins([...]) decides the outcome. When something vanishes from the sidebar, test by reordering before debugging deeper.
• Multi-panel leakage. A plugin registered on the default panel is not automatically on others. Users report "missing feature" far more often than a genuine bug — check AdminPanelProvider first.
• Watch for deprecations, not just breakage. Filament majors deprecate liberally. Run with deprecation warnings visible in a dev environment; the package's 2.1 line will likely carry forward shims that disappear in 2.2.
• Debugging entry point: when the panel fails to boot, temporarily comment out the ->plugin() call. If the panel returns, the issue is version mismatch or missing config — not your app.
• Lockstep releases. Because 2.1.0 is purely a compatibility release, treat bug reports against it as "is this a package bug or a Filament v5 behavior change?" Check Filament's own upgrade guide before filing upstream; most surprises at this boundary belong to the framework, not the plugin.