Filament Users Roles Permissions Laravel Package

Getting Started

1. Confirm compatibility before installing. v1.0.4 adds Filament 4 support, so check composer.json constraints for filament/filament, laravel/framework, php, and livewire/livewire. If the app is still on Filament 3, pin the package version that matches your panel version.
2. Install the package.

   composer require vendor/package
   

3. Publish package assets and config.

   php artisan vendor:publish --tag=package-config
   php artisan vendor:publish --tag=package-assets
   php artisan migrate
   

   Use the package README to confirm the exact publish tags; many Filament plugins split config, migrations, views, and assets into separate tags.
4. Register the Filament plugin. In your panel provider:

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

5. Look first at: the package service provider, the Filament plugin class, config/package.php, published migrations, and any package-provided Resources, Pages, Widgets, or Livewire components.
6. First use case: register the plugin on a non-production panel, run php artisan filament:assets, clear caches, and open the package’s provided resource/page in the browser. This validates installation, asset publishing, panel registration, and Filament 4 compatibility in one pass.

Implementation Patterns

• Panel-scoped registration. Register the plugin only on panels that need it. For multi-panel apps, create separate panel providers or conditionally register based on panel ID, domain, or tenancy.
• Config-first customization. Prefer published config values over editing vendor files. Common day-to-day adjustments include navigation groups, labels, route slugs, feature flags, and authorization callbacks.
• Extend package classes instead of modifying them. Subclass package Resources, Pages, Widgets, or Actions where the package exposes extension points. This keeps upgrades safe.
• Use package-provided Filament components in your own resources. If the package ships form fields, table columns, filters, actions, or widgets, compose them into existing resources rather than duplicating UI logic.
• Pair with policies and gates. Filament 4 resources usually rely on Laravel authorization. Ensure the package’s models have policies and that panel users can access the relevant resources.
• Asset and build workflow. Run php artisan filament:assets after install and after upgrades. If the package ships custom CSS/JS, include it in the panel theme or rely on the package’s asset registration.
• Testing pattern. Use Filament’s testing helpers and Livewire tests to cover package-provided pages. Test plugin registration in a panel provider, then test resource access and package actions against a test database.
• Upgrade workflow for Filament 4. Treat v1.0.4 as the minimum version for Filament 4 apps. Run composer update, republish assets if needed, clear config/route/view caches, and smoke-test each panel that registers the plugin.
• Integration tip: if the package provides migrations, run them before registering the plugin in production. If it provides settings or seeded defaults, use a dedicated seeder rather than editing published migrations.

Gotchas and Tips

• Filament version mismatch is the most likely failure. v1.0.4 supports Filament 4, but older package versions likely do not. Check composer why-not filament/filament if installation conflicts occur.
• Assets often look broken after upgrades. Run:

  php artisan filament:assets
  php artisan optimize:clear
  

  Then hard-refresh the browser. Filament caches panel assets and manifests aggressively.
• Config cache hides changes. After editing config/package.php, run php artisan config:clear or php artisan optimize:clear. In production, rebuild caches deliberately.
• Plugin registration is easy to miss. A package may install cleanly but render nothing until ->plugin(...) is added to the panel provider. Confirm the plugin appears in php artisan about or the panel’s registered plugins during debugging.
• Multi-panel and tenancy quirks. If a plugin registers routes or navigation items globally, it may appear on panels where it should not. Scope registration and verify tenant-aware routes and policies.
• Migration conflicts. Published migrations can collide with existing tables or previous package versions. Review migration filenames and run php artisan migrate --pretend in staging before production.
• Authorization failures look like missing pages. If a package resource returns 403 or disappears from navigation, check policies, panel access, and the package’s authorization config before assuming a Filament 4 compatibility bug.
• Extension points to prefer: panel plugin configuration, published config, custom Resource/Page subclasses, render hooks, custom themes, and package events. Avoid overriding vendor views directly unless the package documents that path.
• Debugging checklist: confirm package version, Filament version, panel provider registration, published assets, cleared caches, migration status, and policy access. Then inspect storage/logs/laravel.log and the browser console for asset or Livewire errors.