Filament Mermaid Field Laravel Package

Getting Started

This release (3.0) is a compatibility release: the package now targets Filament 5. There are no stated feature additions, so treat 3.0 as "same package, new Filament major" and plan accordingly.

First steps:

1. Check your Filament version before anything else. The package major version no longer implies the Filament major you are on:

   composer show filament/filament | grep versions
   

   • On Filament 5 → require this package ^3.0.
   • On Filament 3 or 4 → stay on the previous package major (^2.x); 3.0 will not install alongside an older Filament because of the composer constraint.

2. Install and register the plugin in the panel provider that should expose it:

   composer require <vendor>/<package>:^3.0
   php artisan vendor:publish --tag="<package>-config"
   php artisan vendor:publish --tag="<package>-migrations"   # if applicable
   

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

3. Look first at the package's src/*Plugin.php (or service provider) — that is where panel registration, assets, and navigation entries are wired, and it is the file most likely to have changed to accommodate Filament 5's APIs.

4. First real use case: register the plugin on a non-default panel, load the page/resource it provides, and confirm assets render. If you only ever test the default panel, you will miss half the integration surface.

Implementation Patterns

Upgrade path from 2.x. Do the Filament upgrade and the package upgrade in the same branch, not sequentially — an intermediate commit where Filament is 5 but the package is 2.x (or vice versa) will fail to boot and gives you noisy errors. Order: bump filament/filament to ^5.0, bump the package to ^3.0, composer update --with-all-dependencies, then re-publish assets.

Multi-panel registration. Register the plugin only on the panels that need it. If you previously relied on the package auto-registering globally, verify the new version still does — Filament's plugin contract has shifted across majors, and explicit ->plugin() registration is the safe pattern.

Re-publish, don't assume. Filament major bumps typically change the asset pipeline (theme CSS, Vite entry points, published JS). Re-run the publish commands and diff the output rather than keeping your old published copies:

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

Feature tests. Filament's testing helpers are the fastest way to catch a bad upgrade. Wrap the panel in a test case and assert the plugin's page loads:

public function test_package_page_loads(): void
{
    $this->actingAs($user)
        ->get(\Vendor\Package\Pages\Example::getUrl(panel: 'admin'))
        ->assertOk();
}

This single test would have caught most breakage from a Filament major bump.

CI matrix. If you maintain multiple apps or a package that consumes this one, pin Filament and this package together in a matrix row (filament ^5.0 + package ^3.0, filament ^4.0 + package ^2.x). Mixing rows silently produces unresolvable dependency sets.

Deployment. Add php artisan filament:assets (or the package's asset command) to your deploy script if you publish assets — Filament major upgrades have historically moved where compiled CSS/JS lives, and stale published files manifest as unstyled UI in production only.

Gotchas and Tips

• Package major ≠ Filament major. 3.0 pairs with Filament 5. Do not infer the pairing from the package's own version history; read the composer.json constraint or the release notes each time.
• The release notes are the whole changelog here. "Updated to work with Filament 5" tells you nothing about which APIs changed. Before merging, diff the package's composer.json and its plugin/provider file between 2.x and 3.0 — that is where the actual migration surface is (asset registration, navigation group enums, schema/form namespaces, Livewire constraint).
• Config merge vs. publish. Package config is usually merged, so a published config/<package>.php from 2.x will shadow new 3.0 defaults. If new options appear in 3.0, your old published file silently omits them. Re-publish or diff the config.
• Caches mask the upgrade. After switching versions, run php artisan optimize:clear before debugging anything. Filament caches component/asset manifests aggressively, and "class not found" or blank panels after an upgrade are frequently stale cache, not real breakage.
• --force on publish is destructive. If you have customised published views or assets, back them up before re-publishing; there is no three-way merge.
• Namespace churn is the usual culprit. Filament 3→4 moved a lot into Filament\Schemas\*; a 5.0 bump can move more. Any of your own code that uses Filament classes alongside this package (custom pages extending package base classes, your own resources reusing its traits) is the most likely place to break, not the package itself.
• Extension points to check first if you need to patch: the plugin class (->plugin()), the service provider's register/boot for bindings and navigation, and any published config for toggles. Prefer config overrides and subclassing over editing vendor/.
• Stuck on an older Filament? Pin this package at ^2.x explicitly in composer.json rather than relying on the resolver, so a later composer update doesn't drag the panel onto 5.x unexpectedly.