solutionforest / laravel-recommender
Simple recommendation engine for Laravel — self-hosted for-you feeds (collaborative filtering, trending, cached pages).
Package info
github.com/solutionforest/laravel-recommender
pkg:composer/solutionforest/laravel-recommender
Requires
- php: ^8.3
- illuminate/bus: ^10.0|^11.0|^12.0|^13.0
- illuminate/cache: ^10.0|^11.0|^12.0|^13.0
- illuminate/console: ^10.0|^11.0|^12.0|^13.0
- illuminate/contracts: ^10.0|^11.0|^12.0|^13.0
- illuminate/database: ^10.0|^11.0|^12.0|^13.0
- illuminate/http: ^10.0|^11.0|^12.0|^13.0
- illuminate/pagination: ^10.0|^11.0|^12.0|^13.0
- illuminate/queue: ^10.0|^11.0|^12.0|^13.0
- illuminate/routing: ^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^10.0|^11.0|^12.0|^13.0
- illuminate/view: ^10.0|^11.0|^12.0|^13.0
- laravel/prompts: ^0.1.25|^0.2|^0.3
- nesbot/carbon: ^2.72|^3.0
Requires (Dev)
- larastan/larastan: ^3.0
- orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
- pestphp/pest: ^2.0|^3.0|^4.0
- phpstan/phpstan: ^2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main / 0.11.x-dev
- v0.11.2
- v0.11.1
- v0.11.0
- v0.10.10
- v0.10.9
- v0.10.8
- v0.10.7
- v0.10.6
- v0.10.5
- v0.10.4
- v0.10.3
- v0.10.2
- v0.10.1
- v0.10.0
- v0.9.0
- v0.8.5
- v0.8.4
- v0.8.3
- v0.8.2
- v0.8.1
- v0.8.0
- v0.7.1
- v0.7.0
- v0.6.3
- v0.6.2
- v0.6.1
- v0.6.0
- v0.5.1
- v0.5.0
- v0.4.0
- v0.3.0
- v0.2.0
- v0.1.1
- v0.1.0
- v0.0.15
- v0.0.14
- v0.0.13
- v0.0.12
- v0.0.11
- v0.0.10
- v0.0.9
- v0.0.8
- v0.0.7
- v0.0.6
- v0.0.5
- v0.0.4
- v0.0.3
- v0.0.2
- v0.0.1
- dev-test/probe-flaky
- dev-docs/screenshots-0.11
- dev-feat/speed-probe
- dev-feat/slow-checks
- dev-docs/laravel12-end
- dev-docs/support-dates
- dev-ci/security
- dev-chore/phpstan-10
- dev-release/v0.10.6
- dev-docs/release-via-pr
- dev-fix/review-0.10.5
- dev-docs/audit
- dev-fix/similar-scope
- dev-docs/refresh-0.9
- dev-release/v0.10.0
- dev-feat/similar-items
- dev-feat/jitter
- dev-feat/laravel-10-support
- dev-feat/db-cache-safety
- dev-feat/seen-env
- dev-docs/clarify-feed-memory
- dev-test/heavy-stress
- dev-feat/v0.8.0
- dev-feat/v0.7.1
- dev-feat/v0.7.0
- dev-fix/v0.6.3
- dev-feat/v0.6.2-polish
- dev-docs/advanced-usage
- dev-feat/simpler-0.6
- dev-docs/changelog-dup-0015
- dev-docs/changelog-links
- dev-chore/release-0.5.1
- dev-docs/remove-improvements
- dev-feat/bootstrap-presets
- dev-feat/impressions-quality-trend
- dev-feat/catalog-tail-cursor
- dev-chore/release-0.2.0
- dev-feat/roadmap-batch
- dev-chore/release-0.1.1
- dev-refactor/examples-simple-api
- dev-chore/release-0.1.0
- dev-feat/simple-api
- dev-feat/dashboard
This package is auto-updated.
Last update: 2026-11-14 13:03:34 UTC
README
Laravel Recommender
Build a “for you” feed from the interactions your Laravel app already records.
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.
- Learn from activity: scheduled commands update trending scores and find items that users interacted with together (called neighbours).
- 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. - 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:
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.
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:
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.


