Filament Locksmith Laravel Package

Getting Started

The 2.0.0 release is a compatibility major: it adds Filament v4 support. Treat it as a new baseline rather than a drop-in patch.

1. Confirm the target stack. 2.0.0 is intended for Filament v4. Check that your application already runs filament/filament:^4.0 with its required PHP/Laravel versions before requiring this package. If you are still on Filament v3, stay on the 1.x line.
2. Install the new major explicitly.

   composer require vendor/package:^2.0
   

3. Register the plugin with your panel. In the relevant PanelProvider, add the package plugin to the panel configuration using the package’s documented plugin/resource registration method. If the package auto-discovers resources or pages, verify they appear only in the panels where you expect them.
4. Publish and build assets if applicable.

   php artisan vendor:publish --tag="package-assets"
   php artisan filament:assets
   npm run build
   

5. First use case: add one package-provided resource, page, widget, or action to a non-production panel, open it in the browser, and confirm navigation, authorization, forms/tables, and actions all render under Filament v4.

Where to look first: the package’s 2.0.0 upgrade notes/README, its composer.json Filament constraint, the panel plugin class, the service provider’s register()/boot() methods, and any published config file.

Implementation Patterns

• Panel-scoped registration. Register the plugin per panel rather than globally where possible. This keeps resources/pages/widgets isolated across admin, tenant, or customer-facing panels.
• Extend package classes sparingly. Prefer configuration and published views over subclassing. Where you do extend package resources or pages, re-check overridden methods against Filament v4 APIs — particularly form/table schema methods, action classes, and navigation methods.
• Publish config for environment-specific behavior. Keep package defaults in the published config and override via .env only for values that genuinely differ per environment.
• Use policies and tenancy deliberately. If the package exposes resources or widgets, verify policy discovery and tenant scoping in each panel. Filament v4’s panel tenancy configuration should be tested explicitly.
• Integrate through Filament extension points. Prefer render hooks, macros, custom actions, custom widgets, and navigation callbacks over forking package views. This reduces upgrade friction for future Filament majors.
• Test with Livewire/Filament testing helpers. Cover the package’s pages and actions with Livewire tests, setting the current panel in test setup and asserting visibility, authorization, and action behavior.
• Maintain a version matrix if supporting both majors. If you maintain downstream packages or multiple apps, use separate branches or Composer constraints (^1.0 for Filament v3, ^2.0 for Filament v4) and run CI against both where feasible.

Gotchas and Tips

• 2.0.0 is a breaking major. It should not be assumed compatible with Filament v3 applications. Check transitive dependencies and other Filament plugins before upgrading; Composer may resolve a mixed v3/v4 plugin set that fails at runtime.
• Filament v4 namespace and API changes surface at runtime. Watch for renamed form/table schema methods, changed action namespaces, and revised component APIs. Errors often appear only when a panel page renders, not during composer update.
• Clear Filament caches after upgrading.

  php artisan optimize:clear
  php artisan filament:clear-cached-components
  php artisan filament:assets
  

  Stale cached components and assets are a common cause of “changes not appearing” after a major upgrade.
• Rebuild frontend assets. If the package ships views or a theme, re-publish views, ensure package view paths are included in your Tailwind content configuration, and rebuild with Vite. A cached CSS bundle can hide v4 markup changes.
• Check config caching. If you use php artisan config:cache, remember that published config and .env changes require a cache clear. This is especially relevant when toggling package features per environment.
• Verify plugin registration order and panel scope. Registering the plugin in the wrong panel provider, or registering it after resources that depend on it, can produce missing navigation items or unresolved components.
• Debug systematically: use php artisan about to confirm versions, php artisan route:list to verify panel routes, and browser/Livewire logs for component render failures. Compare a minimal fresh Filament v4 panel against your application to isolate package-specific issues.
• Use extension points before forking. Render hooks, macros, custom themes, and published views are safer long-term than copying package source, particularly across Filament major upgrades.