Download the PHP package boreistudio/filament-recommendations without Composer

Filament Recommendations

Recommendation engine plugin for Filament v5. Co-occurrence, content-based and collaborative filtering strategies with first-class multi-tenancy support.

• Single-tenant and multi-tenant ready. The plugin never assumes a specific tenancy package. It exposes a TenantResolver contract that your project implements.
• Multi-panel by design. A separate Super-Admin panel (global config, health, cross-tenant debug) can be generated apart from the per-tenant panel.
• Background recomputation. Never compute recommendations synchronously in a user request.

Requirements

• PHP 8.3+
• Laravel 12 or 13
• Filament v5

Quickstart

Make a model recommendable, and show recommendations in a resource page in five lines:

Installation

Then run the interactive installer:

The installer asks you about your topology (single vs multi-tenant), your Tenant model, whether to generate a separate Super-Admin panel, and which publishables to copy. It writes config/recommendations.php and optionally generates the panel providers.

For CI/non-interactive installs, flags are available:

The command is idempotent: re-running it will not overwrite existing files unless you pass --force.

After publishing the migrations, register them in the package's tables:

When you generate the panels during installation, register the generated App\Providers\Filament\TenantPanelProvider (and SuperAdminPanelProvider, if chosen) in bootstrap/providers.php.

Configuration

config/recommendations.php:

Tenancy

The plugin never assumes a tenancy package. Implement TenantResolver and bind it in config/recommendations.php under tenancy.resolver:

In single-tenant mode you can leave the resolver unset (the plugin falls back to a resolver that always returns null).

Models with the trait also implement Recommendable and get sensible defaults:

• getRecommendationFeatures(): array — empty by default, used by content-based strategies
• getRecommendationKey() — the model primary key
• getRecommendationTenantId() — delegates to the TenantResolver, override to pin a tenant

When tenancy.enabled is true, the recommendations and recommendation_events tables are scoped to the resolved tenant automatically, so a tenant can never read another tenant's data.

Strategies

Strategies implement BoreiStudio\FilamentRecommendations\Strategies\RecommendationStrategy and return a ranked list of [recommended_type, recommended_id, score] for a subject model, always scoped to the resolved tenant.

Co-occurrence ("who also viewed")

CoOccurrenceStrategy counts how many times two items appear together in the same interaction, using an aggregated SQL query (GROUP BY + COUNT), never loading the dataset into PHP. It is the default strategy.

Content-based

ContentBasedStrategy recommends items with similar normalized attributes, based on getRecommendationFeatures(). Categorical / multi-value attributes use Jaccard similarity; numeric attributes are min-max scaled across the candidate set. Attribute weights are configurable per model:

Two models with identical features recommend each other with score 1.0; completely disjoint features score ~0.

Collaborative filtering (advanced / optional)

CollaborativeFilteringStrategy is an item-based approach ("users who interacted with this item also interacted with these others") built on a user-item matrix from recommendation_events, ranked by cosine similarity over the shared user space.

This strategy is more expensive and only becomes useful with a meaningful volume of per-user interactions. It is meant for advanced setups — prefer CoOccurrenceStrategy by default.

Record interactions with an actor (user) so the matrix can be built:

Activate it per model:

The optional rubix/ml dependency (composer suggest) can power a more sophisticated implementation if you need it.

Filament integration

Widget

Add the RecommendationsWidget to the header of a resource's View/Edit page in one line:

Or register it anywhere on a panel:

The widget shows the cached recommendations for the current record, scoped to the tenant automatically.

Configuration cluster

The settings page and the in-panel documentation are grouped under a single Recommendations cluster (/admin/recommendations-config):

• settings — per-tenant strategy + result limit per model, and last rebuild time
• docs — in-panel documentation (toggle with ->documentation(true|false))

Super-admin panel

If you generated the SuperAdminPanelProvider during recommendations:install, register the plugin with the super-admin page:

The SuperAdminRecommendationsPage shows pending/failed jobs, the last rebuild per tenant (via the TenantProvider), and lets you trigger recalculation per tenant or globally.

Guard integration. The plugin does not assume a super-admin user model. Restrict access to the super-admin panel with your existing auth: implement FilamentUser::canAccessPanel() on your user model to return true only for the super-admin panel id (or gate it via a role/permission).

Recalculation

Recommendations are stored in the recommendations table and are never computed synchronously in a user request.

Rebuild command

In multi-tenant mode the command iterates all tenants when a TenantProvider is configured in config/recommendations.php under tenancy.tenant_provider:

Scheduler

The rebuild and prune commands are good candidates for the scheduler:

Automatic recalculation on interaction

By default every recordInteraction() dispatches a recalculation job for the subject (and context), so the loop works out of the box:

To recalculate only via recommendations:rebuild, disable it:

Caching

recommend() results are cached per subject and tenant, so the expensive query never runs on every request. The cache is invalidated automatically when a recalculation job runs for that subject.

If you change recommendations outside the plugin (e.g. editing the recommendations table directly), clear the cache with php artisan cache:clear or invalidate per subject:

Pruning interaction events

Events power the co-occurrence strategy but grow without bound. Prune old ones with the retention policy (events.retention_days), optionally per tenant:

Production hardening

Error handling

Clear exceptions are thrown for common misconfigurations:

Integrating with a tenancy package

The plugin never assumes a tenancy package — it works through the TenantResolver / TenantProvider contracts. Example with spatie/laravel-multitenancy:

The same pattern applies to stancl/tenancy (use tenancy()->tenant?->getKey() / Tenant::query()->pluck('id')).

Benchmarks

Co-occurrence computation is fully aggregated in SQL (never loaded into PHP). On SQLite via testbench:

• ~10k events across 5 tenants × 20 users × 100 products: co-occurrence compute resolves in ~0.2s (20 subjects).
• A tenant-scoped count over 5,000 events for one subject: ~0.4s including row inserts.

Development

Clone the repository and install dependencies:

Run the test suite in both tenancy modes:

Run the code style and static analysis:

The test matrix (PHP 8.3/8.4 × Laravel 12/13 × single/multi-tenant) runs on GitHub Actions for every push.

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The MIT License (MIT). Please see License File for more information.