Search Filament Laravel Package

Getting Started

1. Confirm the dependency chain first. This package is a presentation adapter: it assumes the underlying search module (liberusoftware/module-search or equivalent) is installed and configured. Install order matters:

composer require liberusoftware/module-search
composer require liberusoftware/search-filament

If the core module is missing, the Filament classes will resolve but fail at runtime when they call into the search service contract.

2. Read these files before writing any code, in this order:

• composer.json — pin down the supported Filament major (^3.0 vs ^4.0) and the required PHP version. This single line determines whether the rest of your integration works.
• src/*ServiceProvider.php — check whether the plugin is auto-discovered, whether resources/pages are registered conditionally, and whether config/assets are publishable.
• config/search-filament.php (if present) — the navigation group, resource visibility, and driver bindings usually live here.
• src/Filament/Resources/ — the resource classes are the real API surface you will extend.
• src/Filament/Widgets/ — search stats/health widgets, if bundled.

3. Register the plugin with your panel. The typical entry point is a Filament plugin object in your AdminPanelProvider:

use LiberuSoftware\SearchFilament\SearchFilamentPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            SearchFilamentPlugin::make()
                ->navigationGroup('Search'),
        ]);
}

If no plugin class exists, register the service provider manually in bootstrap/providers.php and confirm the resources appear under the expected navigation group.

4. Publish and migrate.

php artisan vendor:publish --tag=search-filament-config
php artisan vendor:publish --tag=search-filament-assets
php artisan filament:optimize-clear

5. First use case to validate the install: open the search index/records resource in the panel, confirm the table renders, and run the reindex action on a single record. That exercises the whole chain — Filament resource → adapter → core search service → driver — in one click. If that works, everything else is configuration.

Implementation Patterns

Extend, don't edit. Treat the shipped resources as base classes. Subclass and re-register rather than publishing/mutating vendor files, so upgrades stay cheap:

class SearchIndexResource extends \LiberuSoftware\SearchFilament\Resources\SearchIndexResource
{
    public static function table(Table $table): Table
    {
        return parent::table($table)
            ->columns([...parent::getTableColumns(), ...]);
    }
}

Then point the panel at your subclass (via plugin config, a ->resource() call, or by disabling the vendor resource in config).

Reindex as a queued action, never inline. Index rebuilds are the most common source of request timeouts in search admin UIs. Wrap the vendor action or add your own:

Tables\Actions\Action::make('reindex')
    ->requiresConfirmation()
    ->action(fn (SearchIndex $record) => ReindexDocument::dispatch($record))
    ->successNotificationTitle('Reindex queued');

Requires a running queue worker — document this for anyone deploying the panel.

Scope by tenant/panel. If you run multiple panels, register the plugin selectively and pass tenant context through the plugin's configuration rather than relying on global state. Filter the resource query by the current tenant in a modifyQueryUsing clause so the adapter's search calls stay consistent with what the table shows.

Wire the search contract through the container. For tests, bind a fake implementation of the underlying search service in a service provider rather than hitting a real driver. Filament's Livewire test helpers plus a stubbed contract give you fast coverage of the adapter layer:

$this->mock(SearchService::class)
    ->shouldReceive('index')->once();

Use widgets for operational visibility. Register the package's widgets in the panel (->widgets([...])) and pair them with a dashboard page. Index health (document counts, failed jobs, last rebuild) is the day-to-day reason a team opens this screen.

Keep the adapter thin in your own code. Anything that transforms a domain model into a search document belongs in the core module or an event listener, not in a Filament resource. The adapter should only orchestrate: show, filter, trigger, notify.

Gotchas and Tips

Filament major-version drift. Resource, Form, and Table APIs changed significantly between v3 and v4 (schema namespaces, action classes). Check the constraint in composer.json before assuming any example you find online applies. If the package lags your Filament version, expect namespace errors at boot rather than at call time.

The license is NOASSERTION. That means GitHub could not detect a recognized license — not that it is unlicensed, but that you cannot assume permissive terms. Get this reviewed before it enters a commercial codebase; for internal tooling it is usually tolerable, for distributed software it is a blocker until clarified.

Zero stars, zero dependents, future-dated release. The 2026-10-26 release timestamp is a strong signal of an unusual or automated release process. Treat the package as a snapshot: pin an exact version in composer.json, commit composer.lock, and be prepared to fork. Vendor it into a packages/ path with a path repository if you need to patch it.

Namespace collisions with the core module. Both packages live under the same vendor prefix and may share event names, config keys, or model names. If you see duplicate navigation entries or doubled table rows, check for double registration: once via auto-discovery, once via an explicit ->resource() or ->providers() call.

Config and component caching. After changing navigation groups, resource registration, or plugin options, run php artisan filament:optimize-clear and php artisan config:clear. Filament caches component discovery aggressively; a "my plugin changes do nothing" report is almost always stale cache.

Authorization is not free. The adapter renders resources; it does not necessarily define policies. Add policies for any model it exposes, or every authenticated panel user can trigger reindex and view index internals. Check Gate::allows names used in the vendor resource before assuming a policy exists.

Debugging checklist when the UI breaks:

• php artisan route:list | grep search — did the resource pages register at all?
• php artisan about — is the service provider listed?
• Boot the panel and check storage/logs/laravel.log for container binding errors on the search contract.
• If the table renders but is empty, the adapter is fine and the driver is misconfigured — look at the core module's config, not this package.

Extension points worth preferring over monkey-patching: the plugin object's fluent configuration, published config keys for navigation/labels/visibility, subclassed resources, and the underlying search service's events. If none of those cover your need, open an issue and fork in parallel — do not edit vendor/.

Pair it with a health check. Because the package has no visible test suite or CI signal, add your own smoke test that boots the panel and asserts the search resource route returns 200 for an admin user. That single test will catch most upgrade breakage.