Profiles Filament Laravel Package

Getting Started

The package is a presentation adapter: it contains no domain logic of its own. Everything it renders comes from the Profiles domain module it wraps. Install and read them together — the adapter alone will not work.

composer require liberusoftware/profiles-filament

Because the package is unscored/zero-dependent, pin it explicitly and confirm what it pulls in:

composer show liberusoftware/profiles-filament --all   # available versions
composer show liberusoftware/module-profiles           # the domain module it needs

Where to look first, in this order:

1. vendor/liberusoftware/profiles-filament/composer.json — the real require block tells you which Filament major and which Profiles module version you are actually being bound to. This is the single most important file given the package's maturity.
2. vendor/liberusoftware/profiles-filament/src/ — look for a *Plugin class or a Providers/ directory. In the Liberu module family the adapter normally ships a Filament plugin plus a service provider that registers resources.
3. The config/ directory — if a config file exists, publish it before writing any code:

php artisan vendor:publish --tag=profiles-filament-config

Register the plugin in your panel provider (namespace is almost certainly Liberu\ProfilesFilament\... — confirm against composer.json's autoload.psr-4):

use Liberu\ProfilesFilament\ProfilesFilamentPlugin;

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

First use case: boot the admin panel, log in as a user with the relevant policy/permission, and navigate to the Profiles resource. Create one profile end-to-end — list, create, edit, view — before touching anything else. If the resource appears but the form is empty, the domain module's migrations are not run; if the menu entry is missing entirely, the plugin is not registered (or the panel is cached).

Sanity checks:

php artisan migrate
php artisan optimize:clear
php artisan filament:assets
php artisan about --only=environment

Implementation Patterns

Treat it as a thin skin, not a source of truth. Any behaviour you need (validation rules beyond form-level, state transitions, side effects) belongs in the Profiles domain module's actions/services. Call those from Filament actions rather than writing Model::update() inline — otherwise you fork behaviour between the UI and the API/console paths.

Extending a resource rather than editing vendor code. Subclass the vendor resource, override the schema/table methods, and re-register it:

namespace App\Filament\Resources;

use Liberu\ProfilesFilament\Resources\ProfileResource as BaseProfileResource;

class ProfileResource extends BaseProfileResource
{
    public static function form(Schema $schema): Schema
    {
        return parent::form($schema)->schema([
            ...parent::form($schema)->getComponents(),
            TextInput::make('nickname')->maxLength(64),
        ]);
    }
}

Then disable the vendor registration (plugin config flag if present, otherwise ->resources([]) on the panel and register your own). Verify you don't end up with two menu entries — that is the classic symptom of a half-done override.

Multi-panel setups. If you have admin and app panels, register the plugin on the admin panel only, and expose the end-user profile page as a custom Filament page on the app panel. Sharing resources across panels invites policy and tenancy confusion.

Relation managers are usually where the value is. A Profiles resource typically pulls in addresses, contacts, phone numbers, or KYC documents via relation managers owned by the domain module. Use ->relationManagers([...]) on the resource to select which ones appear, rather than deleting them from the vendor resource.

Authorization. Wire resources to policies from the domain module, and if you use Filament Shield or a permission package, re-run the permission generation after any resource you add. A resource that renders but 403s on save is almost always a missing policy method, not a Filament problem.

Tenancy. If profiles are user- or team-scoped, set ->tenant(Team::class) on the panel and confirm the vendor resource's getEloquentQuery() respects it. Adapters in small ecosystems often assume a single-tenant admin and won't scope for you.

Table actions as domain entry points. Put lifecycle operations (verify, suspend, merge) behind Action::make()->action(fn ($record) => app(VerifyProfile::class)->handle($record)) so the same code paths serve the UI, queued jobs, and tests.

Testing. Hit the resource through Livewire rather than calling the domain directly, so you catch form/schema breakage on Filament upgrades:

Livewire::test(\App\Filament\Resources\ProfileResource\Pages\CreateProfile::class)
    ->fillForm(['name' => 'Ada'])
    ->call('create')
    ->assertHasNoFormErrors();

Gotchas and Tips

• License is NOASSERTION. That is not "MIT with a typo" — it means the repository's license file could not be classified. Get legal sign-off before it reaches production. This is the single biggest blocker on the package, ahead of any technical concern.
• The stated last release, 2026-10-26, is in the future. Either a mis-tagged date, a timezone/CI artefact, or a placeholder tag. Check composer show --all for what versions actually resolve, and pin a concrete constraint ("1.2.*", not "^1.0") — do not rely on dev-main in anything you intend to maintain.
• Zero stars / zero dependents means you are the QA team. Budget for reading the source before every minor bump. Vendor-patch anything you fix rather than waiting on upstream.
• Filament v3 vs v4 API drift. form(Form $form) became form(Schema $schema), and ->schema() replaced ->form() in many places. Check the Filament constraint in the adapter's composer.json against your installed major before debugging a blank form — the adapter may simply be built for the other version.
• Migrations live in the domain module, not here. If php artisan migrate produces nothing from this package, that is correct. Run the Profiles module's migrations (and check whether it publishes them or loads them from database/migrations).
• Panel/provider load order. The adapter's service provider must boot after Filament's. If resources vanish intermittently, check bootstrap/providers.php / config/app.php ordering and run composer dump-autoload.
• Caching bites hard. After any resource or plugin change: php artisan filament:cache-components (to rebuild) or php artisan optimize:clear (to bust). A "my new resource doesn't show up" report is a cache issue nine times out of ten.
• Duplicate menu items / duplicate routes = vendor resource still registered alongside your subclass. Fix by disabling one registration path, not by hiding the item with ->navigation(). Hiding it leaves the route live and the bug discoverable later.
• Debug what's actually registered:

$panel = Filament::getPanel('admin');
dump($panel->getResources());   // is your override or the vendor class listed?
dd($panel->getPlugins());

• Extension points to prefer: published config, published views (--tag=profiles-filament-views), and container bindings for resource classes — in that order. Subclassing is fine; editing vendor/ is not, because with no upstream maintainers your edits are the only copy and a composer update deletes them.
• Watch the query count on the list page. Small adapters frequently omit modifyQueryUsing eager loading. If the table N+1s on a relation column, add ->modifyQueryUsing(fn ($q) => $q->with([...])) in your subclass and consider upstreaming it.