Filament Redirects Laravel Package

Getting Started

The v3.0.0 release is a compatibility major: it adds Filament 5 / Laravel 13 support. There are no new features or deprecations listed, which means the entire upgrade story is dependency constraints plus whatever accumulated drift exists between v2 and v3.

Start here, in order:

1. composer.json require block — confirm the exact constraints. Expect filament/filament: ^5.0 and laravel/framework / illuminate/*: ^13.0, with php: ^8.4 (Laravel 13's floor). This tells you immediately whether you can install it.
2. The plugin class (src/*Plugin.php or the service provider registered in extra.laravel.providers) — this is the entry point Filament panels consume.
3. config/ and resources/ — what's publishable, and under which tags.
4. CHANGELOG.md / diff v2.x..v3.0.0 — since the release note is one line, the diff is your only migration guide.

Minimal install on a Filament 5 / Laravel 13 app:

composer require vendor/package:^3.0
php artisan vendor:publish --tag=<package>-config   # tag from the service provider
php artisan filament:upgrade

First use case: register the plugin on one panel and confirm the UI renders before touching config.

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugins([
            \Vendor\Package\PackagePlugin::make(),
        ]);
}

If you are not on Filament 5 / Laravel 13 yet, pin ^2.0. v3 is not a drop-in for Filament 4 / Laravel 12 apps unless the maintainer explicitly widened both constraints.

Implementation Patterns

Pin the major, not the minor. In an app, "vendor/package": "^3.0" is correct. In a downstream package that depends on this one, you likely need to widen: "vendor/package": "^2.0 || ^3.0" and mirror the Filament constraint split in your own composer.json, otherwise your consumers on Filament 4 are locked out.

Branch your CI matrix on the Filament major. This is the pattern that catches v3 regressions before users do:

matrix:
  include:
    - php: 8.3
      laravel: ^12.0
      filament: ^4.0
      package: ^2.0
    - php: 8.4
      laravel: ^13.0
      filament: ^5.0
      package: ^3.0

Config-first, plugin-second. Publish and commit the config file rather than relying on package defaults. Majors are exactly when defaults shift, and a committed config makes the v2→v3 diff a visible code change instead of a silent behaviour change.

Multi-panel registration. Filament plugins are registered per-panel, so the common production pattern is: enable on admin, leave app/customer panels untouched until verified. Do the rollout panel by panel.

Testing. Use Filament's Livewire test helpers against the package's pages/resources/widgets rather than unit-testing internals:

it('renders the panel page', function () {
    $this->actingAs(User::factory()->create());
    Livewire::test(SomePackagePage::class)->assertSuccessful();
});

assertSuccessful() on the whole page is a cheap, high-signal smoke test after a major bump — it catches broken views, missing assets, and unresolved container bindings in one assertion.

Upgrade workflow for v2 → v3. Upgrade Filament/Laravel first, get your app green, then bump this package. Doing both at once makes bisecting failures impossible.

Gotchas and Tips

• A one-line release note is a yellow flag, not a green one. "Filament 5/Laravel 13 support" tells you nothing about internal API changes, renamed publish tags, or removed config keys. Read the v2.x..v3.0.0 diff before shipping.
• Publish tags often change between majors. vendor:publish --tag=<package>-assets may now be -views or split in two. Re-publish all tags after upgrading and diff the output; stale published views are the #1 cause of "it works in a fresh install but not after upgrade."
• Stale lock files. composer update vendor/package -W — the -W (with-all-dependencies) matters, because Filament 5 pulls newer Livewire and Support packages that can otherwise keep you on a conflicting resolution.
• Asset and component caches. After upgrading, run php artisan filament:upgrade and clear caches: php artisan optimize:clear. In production, config:cache will freeze the old package config if you deploy without clearing.
• PHP version floor. Laravel 13 requires PHP 8.4. Confirm your Docker image, CI runners, and any platform.php setting in composer.json before assuming a constraint conflict is the package's fault.
• Check extra.laravel.providers vs. Filament's plugin discovery. If the provider is auto-discovered and you register the plugin, you can end up with double registration — usually visible as duplicated navigation items or doubled assets.
• Extension points to verify post-upgrade: published views (override copies will not auto-update), custom ->colors() / theme CSS referencing Filament internals, and any macro or container binding registered against a class that was renamed in Filament 5.
• If the package still declares ^4.0 alongside ^5.0, treat Filament 5 as untested-by-default and add your own smoke tests. Dual support is claimed far more often than it is exercised in CI.
• Pin exact minors in production for the first few weeks after a compatibility major ("3.0.*"), then relax to ^3.0 once 3.0.x has settled.