Filament Trumbowyg Laravel Package

Getting Started

Version 3.0.0 adds Filament 3 support, which makes this release the entry point for anyone running a Filament 3 panel. Treat it as a framework-major upgrade release, not a feature drop — the package surface is largely the same, but the Filament/Livewire floor underneath it moved.

Minimum steps:

1. Confirm your app is already on Filament 3 (composer show filament/filament → 3.x). Filament 3 requires PHP 8.1+, Laravel 10+, Livewire 3, Alpine 3. If you're still on Filament 2, stay on the previous major of this package — 3.0.0 will not resolve alongside it.
2. composer require vendor/package:"^3.0" and, if the package ships assets/views/config, re-publish them (see Gotchas — stale published views are the #1 upgrade failure).
3. Register the plugin in your panel provider rather than a global service provider:

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

4. Run php artisan filament:upgrade and php artisan filament:assets, then clear caches.

Look first at: the README's Filament 3 / upgrade section, CHANGELOG.md for the 2.x → 3.x diff, the package's *Plugin.php class (this is where panel-scoped config and registration live in Filament 3), and the published config file for feature toggles.

First use case: install into an existing panel, register the plugin, and verify the package's pages/resources appear in the navigation for one panel only. That single check exercises registration, authorization, and asset loading — the three things that break in a Filament major bump.

Implementation Patterns

• Panel-scoped registration. Filament 3 encourages plugins over global providers. Register the plugin per panel; in multi-panel apps (AdminPanelProvider, AppPanelProvider) a plugin registered on one panel should not leak into the other. This is a feature — use it to expose admin-only tooling.
• Config-first customization. Publish the config and drive behaviour from it (config('package.features.x')) rather than subclassing. Config survives minor upgrades; subclasses don't.
• Extend, don't fork. For UI changes, extend the package's Resource/Page classes and override form()/table(), or override Blade views via Filament's view namespace resolution instead of editing vendor/.
• Theme integration. Filament 3 expects a Vite-built custom theme (->viteTheme('resources/css/filament/admin/theme.css')). If the package injects CSS/JS, confirm its assets are registered through Filament's asset pipeline so they survive filament:assets.
• Testing. Use Filament's testing helpers with Livewire 3 style tests (livewire(Page::class)->assertSee(...)) and cover at least: plugin registration, navigation visibility per role, and one form submission. Filament 3's Livewire 3 dependency changes component testing semantics — retest anything that previously relied on Livewire 2 lifecycle hooks.
• CI matrix. Test against Filament 3.x and Livewire 3.x explicitly; if the package still supports Filament 2 on a 2.x branch, keep a second matrix entry so you can patch both.
• Upgrade workflow for downstream apps: bump the constraint → re-publish assets/views → filament:upgrade → optimize:clear → smoke-test each panel. Script it; this sequence is repeated for every Filament plugin in the app.

Gotchas and Tips

• This is a breaking major. Assume 3.0.0 drops Filament 2 support. Don't upgrade mid-sprint on a production panel without a rollback path; the constraint change alone can cascade into other Filament plugins that haven't shipped F3 support yet.
• Transitive conflict diagnosis. If composer require fails, composer why-not vendor/package 3.0 tells you which plugin is holding the app on Filament 2. Upgrade the ecosystem together, not one package at a time.
• Stale published views/assets are the classic post-upgrade bug: the vendor code is 3.x but your resources/views/vendor/... copy is 2.x. Re-publish with --force (after diffing your customizations) and rebuild assets.
• Filament 3 namespace moves. Filament 3 relocated many classes (Filament\Resources\Form → Filament\Forms\Form, table columns moved, Heroicon strings became an enum, ->colors() became ->colors([...])). Any code in your app extending package classes may need the same edits — grep your app for the old namespaces after upgrading.
• Alpine 3 syntax. Alpine 2 idioms (x-init with $nextTick chaining, dispatchEvent patterns) can silently break UI inside Filament 3 components. Check any custom views the package renders.
• Cache clearing is not optional. Config, route, view, and Filament component caches all mask upgrades. php artisan optimize:clear then php artisan filament:upgrade fixes a large share of "it's broken after upgrade" reports.
• Authorization defaults. Navigation and page access are gated by policies in Filament 3; if pages vanish after upgrade, check canAccess()/policy wiring before assuming a package bug.
• Extension points worth knowing: the plugin class (registration + config), the published config file (feature flags), the view namespace (UI overrides), and any registered macros/actions (behaviour). Prefer these over vendor/ edits — everything else is overwritten on the next composer update.
• Watch the repo for a 3.0.x follow-up. First majors that only bump framework support often ship quick patches for missed Filament 3 API changes; pin ^3.0 rather than 3.0.0 exactly.