cheesegrits/filament-phone-numbers
The v2.1.0 release is a compatibility release, not a feature release: the only documented change is added support for Filament v5. Nothing else in the public API is advertised as changed, so the practical question is not "how do I learn this package?" but "which Filament major am I on, and does my constraint resolve?"
Minimal steps:
composer show filament/filament | grep versions (or check composer.lock). Filament v5 pulls a newer Laravel/Livewire/Tailwind baseline than v4, so your app's versions decide which side of the matrix you land on. Do not upgrade this package in isolation from Filament itself.composer.json constraints after updating. v2.1.0 almost certainly widens the Filament constraint (e.g. ^4.0|^5.0) rather than pinning to v5. That widened constraint is the whole release — verify it, because it tells you whether in-place upgrades are supported or whether you must move Filament first.->plugin(PackageName::make())) or a register() call in PanelProvider. That one line is where 90% of the day-to-day surface area of a Filament integration lives.composer update succeeding does.If you are on Filament v4 today, v2.1.0 is a no-op for you — upgrade on your normal cadence. The release only matters if you are actively planning a Filament v5 move.
Treat this as a two-step upgrade, Filament first. The reliable order is: bump Filament to v5 → resolve its own breakages → bump this package to ^2.1 → re-run your smoke tests. Doing it in one composer update conflates two sets of failures, and Filament v5's asset/theme changes will masquerade as package bugs.
Pin per-environment during the transition. If you have multiple apps or a monorepo, constrain explicitly while you migrate:
"require": {
"filament/filament": "^5.0",
"vendor/package": "^2.1"
}
Do not rely on ^2.0 resolving to 2.1.0 by accident in a long-lived branch — the widened constraint means resolution depends on your Filament version, which is exactly the kind of implicit coupling that breaks CI on an unrelated PR.
Register the plugin per panel, not globally. Filament's multi-panel support means a plugin registered on admin is invisible on app. If your app has more than one panel, replicate the registration in each PanelProvider that needs it, and use panel-scoped configuration (navigation group, slug, access callback) rather than global config where the package exposes it.
Use the package's Filament layer as the integration seam, not its models. When a package ships both a domain layer and Filament resources, extend the Filament classes (custom Resource, custom Widget, custom Action) for UI-level customisation and leave the domain layer alone. Overriding domain models to change a form label is the classic way to make a future Filament upgrade painful.
Test the panel, not just the package. Filament components are Livewire components, so cover the write path with Livewire tests rather than HTTP feature tests:
Livewire::test(CreateRecord::class)
->fillForm(['name' => 'Example'])
->call('create')
->assertHasNoFormErrors();
This pattern survives Filament major upgrades far better than asserting on rendered HTML, and it is the single highest-value test to add before attempting the v5 move.
Rebuild front-end assets explicitly. Filament v5 and Tailwind 4 changed how stylesheets are discovered. If the package ships CSS or expects your theme to @source its views, add the @source line to your theme CSS and run a production build. Cached/compiled assets are the most common cause of "the package looks broken after upgrade" reports.
composer.json. If 2.1.0 replaced v4 support rather than widening it, this becomes a breaking change for anyone still on Filament v4 and you should not upgrade blindly on a shared branch.2.0 → 2.1) signals semver-compatible, but Filament's own majors are not semver-aligned with this package's. Keep a note in your upgrade log of the exact (package, filament) pair you validated — "works on 2.1.0" means nothing without the Filament version next to it.composer show vendor/package filament/filament and read the actual installed versions before assuming the upgrade landed.php artisan filament:optimize / optimize:clear and config:cache routinely serve stale plugin registration after an upgrade. If the plugin "disappeared", clear caches before debugging code.--force into a scratch checkout and diff against your published copies. Unmerged published views are a frequent source of v5 breakage that looks like a package bug.PanelsRenderHook, TablesRenderHook) and action/field class resolution are the fastest way to locate where package markup is injected when something renders in the wrong place. Search the package's service provider for RenderHook:: and ->plugin( to map its entry points in a few minutes — this is usually more current than the README.register() are not — expect those to break on every Filament major.How can I help you explore Laravel packages today?