README

Laravel Relatable

Relate Eloquent models to other models — of any type — and control how strongly they relate. Each relation has a base score and a boost; their product, the relation's weight, orders the related models.

Relations are directed: Action can relate to Fastpace with a score of 1.0 and to Genre with 0.5, while Genre relates back to Action with a score of its own.

Installation

You can install the package via Composer:

composer require foxws/laravel-relatable

The migration for the relatables table runs automatically. You may publish all of the package's resources at once:

php artisan vendor:publish --tag="relatable"

Or, you may publish each resource individually:

php artisan vendor:publish --tag="relatable-config"
php artisan vendor:publish --tag="relatable-migrations"

Tip

Let your AI agent do the hard parts. This package ships a Laravel Boost skill, relatable-development, that teaches your agent how to install, configure and use Laravel Relatable. Install Boost and select the skill when prompted:

composer require laravel/boost --dev
php artisan boost:install

Already using Boost? Run php artisan boost:update --discover to pick up the skill. Then just ask, for example: "Relate my Video model to tags and order them by weight."

Usage

Add the InteractsWithRelated trait to each model that relates to others:

use Foxws\Relatable\Concerns\InteractsWithRelated;
use Illuminate\Database\Eloquent\Model;

class Tag extends Model
{
    use InteractsWithRelated;
}

Then relate models, with an optional score and boost:

$action->attachRelated($fastpace, score: 1.0);
$action->attachRelated($genre, score: 0.5);

// Relations are directed. Relate both ways (Action → Genre and Genre → Action),
// with a lower score back.
$action->attachRelated($genre, score: 0.5, mutual: true, mutualScore: 0.25);

// Relate exactly these models, removing the rest.
$action->syncRelated([
    $fastpace,
    ['model' => $genre, 'score' => 0.5, 'boost' => 2.0],
]);

$action->detachRelated($genre);               // only Action → Genre
$action->detachRelated($genre, mutual: true); // and Genre → Action

$action->relates; // Collection of related models, highest weight first
$action->getRelates(Video::class); // only related videos

See the documentation for mutual relations, scoring, querying relations, and configuration.

Changelog

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

Contributing

Thank you for considering contributing to Laravel Relatable! Please review our contributing guide to get started.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• francoism90
• All Contributors

Inspired by spatie/laravel-relatable.

License

Laravel Relatable is open-sourced software licensed under the MIT license.