Search by

solutionforest / laravel-recommender

solutionforest

Simple recommendation engine for Laravel — self-hosted for-you feeds (collaborative filtering, trending, cached pages).

Package info

github.com/solutionforest/laravel-recommender

Documentation

pkg:composer/solutionforest/laravel-recommender

Statistics

Installs: 71

Dependents: 0

Suggesters: 0

Stars: 3

Open Issues: 0

v0.11.2 2026-11-14 12:30 UTC

README

Laravel Recommender

Laravel Recommender

Build a “for you” feed from the interactions your Laravel app already records.

PHP 8.3+ Laravel 10–13 PHPStan level 10 License: MIT Tests Latest release

Your users view, like, or purchase things. This package reads those events from your tables, finds items people interacted with together, and combines that signal with trending items and your own rules. It runs in your Laravel application; you do not need a separate recommendation service or a background in mathematics.

Your interactions → scheduled score updates → ranked items → JSON or Blade

You provide: item and interaction tables, visibility rules, and the fields to display. The package provides: ranking, cached lists, a shared trending feed, and tools to inspect results. Your app decides when to record interactions; the package also offers an explicit write helper. New or sparse data may produce trending results or an empty feed.

How we recommend

Imagine a reader likes post A. If other readers interacted with both A and B, post B can become a suggestion. Popular recent posts can also appear, and you can add your own rules.

  1. Learn from activity: scheduled commands update trending scores and find items that users interacted with together (called neighbours).
  2. Build a list: sources suggest candidates; the package filters out disallowed items, combines their scores, and can apply optional boosts, randomness (jitter), exploration and diversity rules.
  3. Serve the feed: the ranked list and cards are cached. Guests use a shared trending list; users with little history may see mostly trending items. If there are no eligible items, the feed can be empty.

Your app records the interactions (or lets $post->recordInteraction($user, 'like') write them with your feed's mapping) and controls visibility and card fields. Cards are shared across viewers, so add viewer-specific fields separately. The package stores derived scores, daily counters and neighbours in four rec_* tables. When ranked and trending items run out, feeds with a model can continue with the newest eligible items. See how it works for the full flow and operations for memory and impression costs.

Supported versions

Laravel PHP 8.3 PHP 8.4 PHP 8.5 Laravel security fixes until Supported here until Notes
13.x ✅ ✅ ✅ Q1 2028 No end date Also tested on MySQL 8 and with a Redis cache store
12.x ✅ ✅ ✅ 24 Feb 2027 First release after 31 Mar 2027 Use 12.60 or newer for Laravel's own security fixes; plan an upgrade to 13
11.x ✅ ✅ ✅ Ended 12 Mar 2026 First release after 31 Mar 2027 Open advisories that will not be fixed (composer audit); upgrade to 13. On PHP 8.5, Laravel 11 itself prints deprecation notices
10.x ✅ ✅ ⚠️ Ended 4 Feb 2025 First release after 31 Mar 2027 Best-effort. On PHP 8.5 CI only checks that the package installs and loads: Laravel 10's test tools do not run on PHP 8.5

✅ = the full test suite runs in CI on every push (SQLite). "Laravel security fixes until" is Laravel's own support policy; "Supported here until" is when this package drops that version. PHP 8.2 and older are not supported. Other databases (PostgreSQL, MariaDB) and cache stores with locks should work but are not tested in CI.

Your first feed

In an app with a Post model and interaction tables (post_likes, post_views with user_id, post_id, created_at):

1. Install and set up

composer require solutionforest/laravel-recommender
php artisan recommender:bootstrap posts

bootstrap migrates, asks for your tables, writes the feed, builds the first scores, checks everything (tables, columns, indexes, classes) and times each part once on real data, so a slow scope or a missing index shows up before any user hits it:

recommender:bootstrap

2. Tell the model what may be shown

use SolutionForest\Recommender\Eloquent\Recommendable;

class Post extends Model
{
    use Recommendable;

    public function scopeRecommendable($query, $context)    // optional: what may be shown
    {
        $query->where('published', true);
    }

    public function toRecommendationCard(): array           // optional: the JSON per item
    {
        return ['id' => $this->id, 'title' => $this->title];
    }
}

3. Add a route

Route::get('/posts/for-you', fn (Request $request) => Post::recommendedFor($request->user()));

That's it. The response is Laravel's paginator JSON (with next_cursor for infinite scroll), and the scoring jobs are scheduled for you — just keep Laravel's scheduler running. The whole feed bootstrap wrote is a few lines of config:

'posts' => [
    'preset' => 'social',   // catalog | social | events
    'model' => App\Models\Post::class,
    'interactions' => ['post_likes' => 'like', 'post_views' => 'view'],
],

For a related-posts block, $post->similar(6) returns the cards of the posts most often liked together with this one. See similar items.

Follow the first-feed tutorial → for other table shapes, custom classes and troubleshooting.

Choose your next step

I want to… Read
Understand the terms before starting Getting started
Follow a complete working setup First-feed tutorial
Understand ranking and cache behavior How it works
Change what influences the feed Tuning
Add my own rules, several feeds, A/B tests, tests Advanced usage
Look up methods, contracts and configuration Reference
Monitor feeds in the browser Dashboard
Run, monitor or rebuild in production Operations
See measured speed, load and concurrency results Performance
Explore the formulas Maths (optional)
Adapt an integration Examples — blog, products, events and reviews

Dashboard

Open /recommender to see each feed's health, what is broken and how to fix it, what is trending, and why a given user gets their recommendations.

Recommender dashboard

It is open in the local environment. In production, choose who can see it:

Gate::define('viewRecommender', fn ($user) => $user->is_admin);

php artisan recommender:doctor runs the same checks in the terminal and fails a deploy when something is wrong. Both also warn about slow parts in your own code — a source, a recommendable scope or cards slower than 200 ms, SQL slower than 1 s while the jobs run, or an interaction table without the indexes the jobs need; add --probe to time every part once before going live:

recommender:doctor

Dashboard guide →

Why does a user see this?

Use Explain a user on the dashboard (or php artisan recommender:explain posts 123): every item's score split by source, plus where it lands after exploration and diversity. Recommender::stats('posts', $post) tells you how good one item is. Rebuilds, pruning and scale are in operations; weights in tuning.

For coding agents

Package guidance is available in AGENTS.md and the Laravel Recommender skill. Copy the skill into a consuming application's .cursor/skills/ if desired.

Changelog · Releases · Publishing a release · MIT license