Integrations Filament Laravel Package

Getting Started

This package is a presentation adapter, not an integration engine. It ships Filament resources, pages, and widgets that render UI on top of a separate domain package (almost certainly a sibling "integrations" module in the Liberu ecosystem). If you install this alone, you get screens with nothing behind them.

Install order matters:

composer require liberusoftware/integrations-filament

Before you run that, open the package's composer.json on GitHub and confirm:

1. The required version of the core integrations package — install and configure that first, including its migrations and any provider credentials config.
2. The filament/filament constraint. This is the single most important line in the file. The package was last released 2026-10-26, so it targets a specific Filament major version, and resource/page APIs differ substantially between v2, v3, and v4.
3. Whether it expects nwidart/laravel-modules style registration (Modules\... namespaces) rather than standard PSR-4. The repo name (module-integrations-filament) hints at a modular monolith layout.

Where to look first, in this order:

• src/*ServiceProvider.php — read the whole file. It tells you what gets registered: Filament panel plugin, Livewire components, views, config, migrations, routes. Note any publishes() tags here since they are often undocumented elsewhere.
• src/Filament/ — the actual Resources, Pages, and Widgets. This is the surface you will extend.
• config/ — look for keys that let you toggle resources, change navigation groups, or swap classes.
• composer.json autoload block — confirms the namespace root you'll use in your own subclasses.

Sanity check before writing any code:

php artisan about
php artisan vendor:publish --provider="Liberu\IntegrationsFilament\...ServiceProvider"
php artisan optimize:clear

Then log into the panel and confirm the resources actually appear in navigation. If they don't, the problem is panel registration, not the package (see Gotchas).

First realistic use case: an admin screen where an operator picks a provider, enters API credentials or clicks "Connect" for OAuth, sees connection status, and triggers a manual sync. Build that end-to-end before touching anything else — it exercises the form schema, the actions, the auth flow, and the job dispatch path all at once, which is where this kind of adapter usually has rough edges.

Implementation Patterns

Respect the two-layer split. The core module owns credentials storage, HTTP clients, sync jobs, and token refresh. This package owns forms, tables, actions, and notifications. Every time you are tempted to put a Http:: call or a token-refresh branch inside a Filament action closure, stop — put it in the core module and call it. Adapters like this rot precisely because business logic leaks into the presentation layer and then can't be tested or reused by the API/CLI surfaces.

Resource + relation manager composition. The typical shape is a top-level IntegrationResource listing configured connections, with relation managers or a nested table for sync runs/logs. When extending, prefer adding a relation manager over adding a tab to the main form — it keeps your additions isolated from upstream changes to the resource's schema.

Build credential forms dynamically from provider metadata. The core module almost certainly exposes something like a provider definition with field names, types, and required flags. Map that to Filament components rather than hardcoding one form per provider:

// illustrative — adapt to whatever the core exposes
foreach ($provider->credentialFields() as $field) {
    $component = match ($field->type) {
        'secret' => Forms\Components\TextInput::make($field->key)->password()->revealable(),
        'boolean' => Forms\Components\Toggle::make($field->key),
        default  => Forms\Components\TextInput::make($field->key),
    };

    $schema->components([
        $component->required($field->required)->helperText($field->help),
    ]);
}

This is the highest-leverage thing you can add if the package doesn't already do it — new providers then need zero UI work.

OAuth belongs on a custom Page, not a modal action. Redirect-and-callback flows break inside modal actions because the Livewire component state is lost across the redirect. Use a Filament\Pages\Page (or a plain controller route) for the callback, store the state parameter, then redirect back to the resource with a notification. Check whether the package already registers a callback route in its service provider before you add a competing one.

Long-running work goes through the queue. Action closures execute inside the Livewire request. A sync that takes 40 seconds will hit max_execution_time or the user's patience:

Tables\Actions\Action::make('sync')
    ->requiresConfirmation()
    ->action(function (Integration $record) {
        SyncIntegrationJob::dispatch($record);
        Notification::make()->title('Sync queued')->success()->send();
    })
    ->visible(fn (Integration $record) => $record->isConnected());

Gate destructive actions properly. ->requiresConfirmation() is not authorization. Add ->visible(fn ($record) => auth()->user()->can('update', $record)) and make sure a policy exists — see Gotchas.

Tenancy. If your app is multi-tenant, verify how the resource scopes queries. Filament's getEloquentQuery() is the hook; override it in a subclass if the package doesn't scope by team_id/tenant_id. This is a security issue, not a cosmetic one, so check it on day one.

Testing. Resource pages are Livewire components and test cleanly:

livewire(ListIntegrations::class)
    ->assertCanSeeTableRecords($integrations)
    ->callTableAction('sync', $integrations->first())
    ->assertNotified();

Queue::fake() the job dispatch. Write these tests early — with zero stars and zero dependents, you are the only regression suite this package will ever have.

Gotchas and Tips

Zero stars, zero dependents, NOASSERTION license. Treat this as first-party vendor code you happen to not own: pin an exact version in composer.json, read the source before upgrading, and consider vendoring or forking if you ship to production. The "last release 2026-10-26" date with no adoption signals means nobody else has found the bugs yet. You will.

Filament major-version drift is the #1 failure mode. Forms\Form → Schemas\Schema, ->form() → ->schema(), ->actions() moving from the table to the row, getPages() signature changes — all of these break adapter packages silently or with confusing type errors. Confirm the constraint matches your app before debugging anything else. If they mismatch, you'll chase phantom bugs in your own code for an hour.

Resources not appearing in navigation. In order of likelihood: (a) the panel doesn't auto-discover the package's namespace — add ->discoverResources(in: base_path('vendor/.../src/Filament/Resources'), for: 'Liberu\\IntegrationsFilament\\Filament\\Resources') or register explicitly; (b) the service provider isn't in bootstrap/providers.php; (c) Filament's component cache is stale — run php artisan filament:cache-components after clearing; (d) canViewAny() returns false because no policy exists.

Missing policies. Packages like this frequently ship resources without policies, which means either everything is visible to every panel user or nothing is. Grep for Policy in src/. If absent, generate them yourself and register in AuthServiceProvider — do not rely on the package.

Publish tags are undocumented. Don't guess --tag=integrations-filament-config. Read publishes() in the service provider and use the exact tag or the --provider= form.

OAuth callback URLs. These usually hardcode or config-derive a route. Verify the redirect URI against what you registered with the provider, and be aware that panel routes are prefixed (e.g. /admin/integrations/callback) while the provider may expect a root-level path. APP_URL mismatch here produces opaque invalid_request errors from the provider side, not from Laravel.

Cache and config after every change. php artisan optimize:clear && php artisan filament:cache-components should be muscle memory. Silent stale-component behavior costs more debugging time than any actual bug in this package.

Extension points, in order of safety: (1) config keys that swap class names, if they exist; (2) subclassing the resource/page and re-registering your subclass in the panel while removing the original; (3) Filament's action/component extension hooks (->extraAttributes(), custom Action objects on the table); (4) forking. Editing files under vendor/ is not an option — you'll lose it on the next composer update.

Watch the query count. Adapter resources commonly forget ->with() on relations and N+1 their way through a table of 50 integrations with sync logs. If the list page is slow, look at modifyQueryUsing() before blaming the database.