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: ^11.0|^12.0|^13.0
- illuminate/cache: ^11.0|^12.0|^13.0
- illuminate/console: ^11.0|^12.0|^13.0
- illuminate/contracts: ^11.0|^12.0|^13.0
- illuminate/database: ^11.0|^12.0|^13.0
- illuminate/pagination: ^11.0|^12.0|^13.0
- illuminate/queue: ^11.0|^12.0|^13.0
- illuminate/support: ^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: ^9.0|^10.0|^11.0
- pestphp/pest: ^3.0|^4.0
- phpstan/phpstan: ^2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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. It does not record interactions for you. 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, 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 and controls visibility and card fields. Cards are shared across viewers, so add viewer-specific fields separately. The package stores derived scores and neighbours in three rec_* tables. Personal paging uses a bounded seen set, so repeats can occur after expiry or resets. See how it works for the full flow and operations for cache and production details.
Your first feed
Requires PHP 8.3+ and Laravel 11, 12, or 13. In an existing Laravel app with a Post model and interaction tables:
composer require solutionforest/laravel-recommender php artisan migrate php artisan recommender:make-feed posts
The wizard creates three classes and registers a feed. Edit the generated classes to match your schema, then build scores and neighbours:
php artisan recommender:update-scores posts php artisan recommender:build-neighbours posts php artisan recommender:status posts
Expose the feed from a route:
use Illuminate\Http\Request; use Illuminate\Support\Facades\Route; use SolutionForest\Recommender\Facades\Recommender; Route::get('/posts/recommended', function (Request $request) { $feed = Recommender::page('posts', $request->user()?->id, (int) $request->query('page', 1)); return response()->json($feed->toPaginatorArray(['path' => $request->url()])); });
Follow the first-feed tutorial → for the required table shape, checks, scheduler and troubleshooting. Run the maintenance commands after your app has recorded interactions; the first score run excludes the most recent minute.
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 |
| Look up methods, contracts and configuration | Reference |
| Run, monitor or rebuild in production | Operations |
| Explore the formulas | Maths (optional) |
| Adapt an integration | Examples — blog, products, events and reviews |
| Review proposed usability improvements | Improvement proposals |
Inspect and tune
php artisan recommender:explain posts 123
Replace 123 with a real user ID. This shows source and booster scores for a fresh build before exploration and diversity; it is a diagnostic, not a guarantee of the exact cached page. If the user has little history or few shared interactions, trending may be the only useful signal. See tuning before changing weights.
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.