README

A powerful, plug-and-play recommendation engine for any Laravel Eloquent model.

Supports 11 recommendation algorithms, automatic interaction tracking, caching, queue integration, analytics, and full extensibility—all running locally without external APIs.

✨ Features

✅ 11 Built-in Algorithms
- Popular
- Trending
- Related
- Content-Based
- Collaborative (User-Based)
- Collaborative (Item-Based)
- Personalized
- Recently Viewed
- Similar
- Random
- Hybrid
✅ Automatic interaction tracking
✅ Configurable interaction weights
✅ Time-based decay for trending items
✅ Works with any Eloquent model
✅ Trait-based integration
✅ Redis, Database & File cache support
✅ Queue support (Redis, Database, Sync)
✅ Hybrid recommendation engine
✅ Analytics & Artisan commands
✅ Easily register custom algorithms
✅ SOLID architecture
✅ PSR-12 compliant
✅ Fully tested with Pest
✅ Laravel 9, 10, 11, 12 & 13 support
✅ PHP 8.1+

Installation

Install via Composer.

composer require awais69735/recommendation-engine

Publish the configuration and migrations.

php artisan vendor:publish --provider="Awais69735\Recommendation\Providers\RecommendationServiceProvider"

Run migrations.

php artisan migrate

This will publish:

config/recommendation.php
Database migrations

Configuration

All package settings are located inside:

config/recommendation.php

Algorithms

Enable or disable individual algorithms.

'algorithms' => [

    'popular' => [
        'enabled' => true,

        'weights' => [
            'viewed'     => 1.0,
            'purchased'  => 2.0,
            'liked'      => 1.5,
        ],
    ],

    'trending' => [

        'enabled' => true,

        'decay' => 0.9,

        'windows' => [
            'hour'  => 1,
            'day'   => 24,
            'week'  => 168,
            'month' => 720,
        ],

        'default_window' => 'week',
    ],

    'hybrid' => [

        'enabled' => true,

        'mix' => [
            'popular'       => 0.30,
            'trending'      => 0.20,
            'content'       => 0.30,
            'collaborative' => 0.20,
        ],
    ],

];

Cache

'cache' => [

    'driver' => env('RECOMMENDATION_CACHE_DRIVER', 'redis'),

    'ttl' => env('RECOMMENDATION_CACHE_TTL', 3600),

],

Queue

'queue' => [

    'enabled' => env('RECOMMENDATION_QUEUE_ENABLED', true),

    'connection' => env('RECOMMENDATION_QUEUE_CONNECTION', 'redis'),

    'queue_name' => 'recommendations',

],

Database Tables

All database table names can be customized.

'tables' => [

    'interactions'       => 'recommendation_interactions',

    'scores'             => 'recommendation_scores',

    'cache'              => 'recommendation_cache',

    'settings'           => 'recommendation_settings',

    'models'             => 'recommendation_models',

    'algorithm_results'  => 'recommendation_algorithm_results',

],

Usage

1. Add the Trait

use Awais69735\Recommendation\Traits\CanBeRecommended;

class Product extends Model
{
    use CanBeRecommended;
}

Your model now supports recommendation methods.

2. Track User Interactions

$product->trackView($user);

$product->trackPurchase($user);

$product->trackLike($user);

$product->trackInteraction(
    InteractionType::ADDED_TO_CART,
    $user
);

Or use the Tracker contract.

use Awais69735\Recommendation\Contracts\TrackerInterface;
use Awais69735\Recommendation\Enums\InteractionType;

$tracker = app(TrackerInterface::class);

$tracker->track(
    $product,
    InteractionType::PURCHASED,
    $user
);

3. Retrieve Recommendations

Using the Facade

use Awais69735\Recommendation\Facades\Recommendation;

$popular = Recommendation::popular();

$popularProducts = Recommendation::popular(
    new Product(),
    5
);

$trending = Recommendation::trending('week', 10);

$related = Recommendation::related($product);

$similar = Recommendation::similar($product);

$random = Recommendation::random(Product::class, 5);

$hybrid = Recommendation::hybrid(null, 10, $customMix);

$personalized = Recommendation::personalized($user);

$recentlyViewed = Recommendation::recentlyViewed(
    $user,
    $sessionId
);

Using the Trait

$popular = Product::popular(5);

$related = $product->related();

$similar = $product->similar();

$random = Product::random();

$hybrid = Product::hybrid(10, $mix);

All methods return a collection of RecommendationResult.

$result->model;

$result->score;

$result->source;

Recommendation Algorithms

Algorithm	Description
Popular	Weighted interactions such as views, purchases and likes
Trending	Recent interactions using time decay
Related	Shared categories, tags, metadata and keywords
Content-Based	TF-IDF style cosine similarity
Collaborative	Finds similar users and recommends their preferred items
Item-Based	People who viewed or purchased this also viewed or purchased
Personalized	User-specific recommendations
Recently Viewed	Recently viewed items for authenticated and guest users
Similar	Returns items similar to the current model
Random	Weighted random recommendations
Hybrid	Combines multiple algorithms

Analytics & Artisan Commands

Command	Description
`recommendation:cache`	Warm recommendation cache
`recommendation:clear`	Clear recommendation cache
`recommendation:sync`	Sync metadata
`recommendation:recalculate`	Recalculate recommendation scores
`recommendation:cleanup`	Remove old interactions
`recommendation:analytics`	Display analytics and statistics

Events

The package dispatches the following events.

Event	Description
RecommendationGenerated	Recommendation results created
RecommendationUpdated	Scores recalculated
RecommendationCached	Results stored in cache
InteractionTracked	User interaction recorded
AlgorithmExecuted	Algorithm execution completed

You may listen to these events inside your application's EventServiceProvider.

Register Custom Algorithms

use Awais69735\Recommendation\Facades\Recommendation;
use Awais69735\Recommendation\DTOs\RecommendationContext;

Recommendation::extend(
    'myAlgorithm',
    function (RecommendationContext $context) {

        // Custom logic

        // Return Collection<RecommendationResult>

    }
);

Use it.

Recommendation::algorithm('myAlgorithm');

Testing

Run the test suite.

vendor/bin/pest

The package includes:

Unit Tests
Feature Tests
SQLite in-memory testing
Algorithm testing
Integration testing

📚 Documentation

Detailed documentation is available in the docs/ directory.

Document	Description
Architecture	Learn how the package is structured, including managers, services, repositories, contracts, DTOs, and recommendation engines.
Installation	Complete installation guide, requirements, publishing assets, migrations, and troubleshooting.
Configuration	Detailed explanation of every configuration option available in `config/recommendation.php`.
Recommendation Algorithms	In-depth guide to all built-in algorithms, their use cases, scoring strategies, and configuration.
Interaction Tracking	Learn how interactions are tracked, supported interaction types, guest sessions, and custom tracking.
Caching	Configure Redis, Database, or File caching, cache invalidation, warming, and performance optimization.
Queue Processing	Offload heavy recommendation calculations to queues and learn deployment best practices.
Extending the Package	Create and register custom recommendation algorithms using the package's extension points.
Events	Explore the available events and learn how to build listeners for analytics, logging, and cache management.
Artisan Commands	Reference for all available Artisan commands with examples and scheduling recommendations.
Testing	Learn how to test recommendations, interactions, custom algorithms, and package integrations using Pest.
Performance	Best practices for scaling to millions of interactions with caching, indexing, queues, and optimized queries.
FAQ	Answers to common questions, troubleshooting tips, and recommended practices.

Contributing

Contributions are welcome.

Please ensure:

PSR-12 coding standards
New tests for new features
Clear documentation updates

License

This package is open-sourced software licensed under the MIT License.

See the LICENSE file for more information.

awais69735 / recommendation-engine

Maintainers

Package info

Statistics

Security