Identity Core Filament Laravel Package

Getting Started

This package is a thin Filament adapter: it does not own the identity data, it renders whatever model the Liberu identity core is configured to use. Treat it as UI over a contract, not as a standalone package.

Install and wire up

1. Install the identity core first (the model/contracts package this adapter depends on), then the adapter:

   composer require liberusoftware/identity-core-filament
   

2. Read composer.json before anything else — it tells you the Filament major version (filament/filament: ^3.x vs ^4.x) and which Liberu identity packages are hard requirements. Version drift here is the most common reason the panel blows up on boot.
3. Publish whatever the service provider exposes:

   php artisan vendor:publish --provider="Liberu\IdentityCoreFilament\IdentityCoreFilamentServiceProvider"
   

   Expect a config file (model class, navigation group, feature toggles) and possibly views/assets.
4. Register the plugin in your panel provider:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->id('admin')
           ->path('admin')
           ->plugin(\Liberu\IdentityCoreFilament\IdentityCoreFilamentPlugin::make());
   }
   

   The exact plugin class name is the one thing to verify in src/ — look for a class implementing Filament\Contracts\Plugin.

Where to look first

• src/*Plugin.php — the registration entry point; shows what resources/pages get added to the panel.
• src/Resources/ — user, role, permission resources and their forms/tables. This is where 90% of your customization happens.
• The service provider's register()/boot() — config merging, model binding, policy registration.
• config/ — the model swap point. If your app has a custom User model, this is where you point the package at it.

First use case

Boot the panel, log in as a user with an admin-ish role, and confirm the identity resources appear under the configured navigation group. Then edit a user's roles and verify the change lands on the configured model (not a hardcoded one). If the resource renders but saving fails, you have a model-contract mismatch, not a Filament problem — see Gotchas.

Implementation Patterns

Config-driven model swap. The package's whole value proposition is "the configured identity model." Define your model once in config (or via the identity core's own config) and let both the core and this adapter read from it. Never hard-subclass resources just to change the model class — change the config. This keeps upgrades cheap.

Extending resources instead of editing them. For custom fields, subclass the shipped resource and register yours on the panel, or use Filament's global configuration in a service provider:

UserResource::configureUsing(function (UserResource $resource) {
    // tweak labels, navigation group, table columns
});

This survives composer update. Forking the resource file does not.

Multi-panel / multi-tenant setups. Register the plugin only on the panels that should expose identity administration. For tenant-scoped panels, scope the resource's query (e.g. getEloquentQuery() filtered by tenant) rather than duplicating resources. Identity administration on a public-facing panel is a security smell — gate it with canAccess().

Authorization belongs to policies, not the resource. Filament resolves viewAny, create, update, delete against the model's policy. If role/permission management should be restricted, write those policies against the identity model; the adapter will respect them. Don't hide buttons with visible() as your only control — direct URLs and Livewire actions still hit the policy.

Sensitive-field discipline. The user resource typically handles passwords and possibly 2FA/API tokens. Confirm password fields are dehydrated(fn ($state) => filled($state)) and hashed in the model's mutator, not the form. Check that edit forms don't leak hashed columns or remember-tokens in the table.

Relation managers over embedded repeaters. Roles and permissions are many-to-many. Prefer the package's relation managers (or add your own) so sync handling and pivot data stay in one place, rather than a Select::multiple() on the main form.

Eager loading. Tables listing users with roles/permissions columns will N+1 unless the resource's getEloquentQuery() eager-loads them. If the shipped resource doesn't, override it — this is the single biggest admin-panel performance win.

Cross-module integration. Other Liberu modules should consume the identity core's contracts/services, not this Filament package. This package is a leaf: nothing should use its classes except your panel provider and any resource subclasses.

Gotchas and Tips

• Contract mismatch is the #1 failure. The adapter expects a specific interface (something like an identity/user contract). A stock App\Models\User that doesn't implement it will render empty forms or throw on save. Verify the model in config implements every interface the core publishes.
• Zero stars, future-dated release. 2026-10-27 as a last-release date is a red flag — either a metadata error or a package under active churn. Pin an exact version in composer.json, read src/ before trusting it, and expect breaking changes between minors. Budget time to vendor-fork if it goes stale.
• Filament v3 vs v4 API drift. Namespace moves (Filament\Resources\Resource internals, form/table schema changes) break silently or with opaque errors. Match the adapter's constraint to your Filament version exactly; don't let Composer resolve across majors.
• Config cache. After changing the configured model or navigation settings: php artisan config:cache (or config:clear in dev). A stale cached model class produces "resource shows wrong data" bugs that look like code problems.
• Component cache. Filament caches panel components; after adding/renaming resources run php artisan filament:optimize-clear (or optimize:clear). Missing resources after a deploy are almost always this.
• Navigation not appearing. Three usual causes, in order: the plugin isn't registered on this panel, the policy returns false for viewAny, or the component cache is stale. Check policy first — it fails silently as "hidden."
• Policy discovery for a swapped model. If you point the package at App\Models\User, Laravel looks for App\Policies\UserPolicy. Miss it and everything is 403 in production while working locally under a permissive dev policy.
• Publishing collisions. If both the identity core and this adapter publish config under similar names, publishes can overwrite each other. Publish with explicit --tag= options and diff what lands.
• Debugging isolation. To separate adapter bugs from your app: register the plugin on a bare panel in a scratch app with the default identity model. If it works there, the problem is your model/config, not the package.
• Extension points to prefer. Global configureUsing(), resource subclasses, policy classes, and the config file. Avoid editing vendor/ — with a 0-star package you will need to update, and patches will be lost.
• Don't expose it broadly. Identity administration is the highest-privilege surface in the app. Restrict the panel by middleware/IP allowlist, require 2FA for admins if the core supports it, and log changes (activity log) — the adapter gives you CRUD, not audit.