README

One polymorphic interaction system for likes, favorites, subscriptions, follows, votes, and custom actions.

AI skill

Install the package usage skill to give your coding agent the public APIs, setup rules, and examples from this repository:

npx skills@latest add edram/laravel-interactions

Installation

composer require edram/laravel-interactions
php artisan vendor:publish --tag="laravel-interactions-config"
php artisan vendor:publish --tag="laravel-interactions-migrations"
php artisan migrate

Set the default actor model used by relations such as likers() and followers():

// config/laravel-interactions.php
'default_actor' => App\Models\User::class,

The key_type configuration supports bigint, uuid, and ulid. Configure it before running the migration. Actors and interactables stored in the same interactions table must use the same key type.

Model setup

Actors use Interacts. Targets use Interactable. A model such as User that can both create and receive interactions uses both traits.

use Edram\LaravelInteractions\Concerns\Interactable;
use Edram\LaravelInteractions\Concerns\Interacts;

class User extends Authenticatable
{
    use Interactable;
    use Interacts;
}

class Post extends Model
{
    use Interactable;
}

class Comment extends Model
{
    use Interactable;
}

Both sides are polymorphic. A User, Team, or any other Eloquent model using Interacts can act on any model using Interactable.

Built-in interactions

$user->like($post);
$user->unlike($post);
$user->toggleLike($post);
$user->hasLiked($post);
$post->isLikedBy($user);
$post->likers;
$user->likedItems(Post::class)->paginate();

$user->favorite($post);
$user->unfavorite($post);
$post->favoriters;

$user->subscribe($post);
$user->unsubscribe($post);
$post->subscribers;

$user->follow($anotherUser);
$user->unfollow($anotherUser);
$user->following;
$anotherUser->followers;

$user->upvote($post);
$user->downvote($post, 3);
$user->vote($post, 5);
$user->cancelVote($post);
$post->voters;
$post->upvoters;
$post->downvoters;
$post->totalVotes();

like, favorite, subscribe, and follow are idempotent. Calling them repeatedly does not create duplicate records. A vote uses one record per actor and target; changing direction or weight updates that record.

To query a non-default actor model, pass its class explicitly:

$post->likersFor(Team::class)->paginate();
$post->interactors('bookmark', Team::class)->get();

Custom interactions

Custom action names are lowercase slugs up to 64 characters. Strings and string-backed enums are accepted.

$interaction = $user->interact(
    $post,
    'bookmark',
    metadata: ['folder' => 'reading'],
);

$user->hasInteracted($post, 'bookmark');
$user->toggleInteraction($post, 'bookmark');
$user->uninteract($post, 'bookmark');

$user->interactions('bookmark')->get();
$post->receivedInteractions('bookmark')->with('actor')->get();
$user->interactedItems('bookmark', Post::class)->paginate();
$post->interactors('bookmark', User::class)->paginate();

Use the optional signed integer value for weighted actions and metadata for additional structured data.

Feed status

Attach several interaction states to a model, collection, or paginator with one interaction query:

$posts = Post::paginate();

$user->attachInteractionStatus($posts, ['like', 'favorite', 'vote']);

$posts[0]->interaction_status;
// ['like' => true, 'favorite' => null, 'vote' => -1]

null means no interaction exists, true means an interaction without a value exists, and an integer is the stored value.

Events and deletion

The package dispatches these events only when persistence actually changes:

• Edram\LaravelInteractions\Events\InteractionCreated
• Edram\LaravelInteractions\Events\InteractionUpdated
• Edram\LaravelInteractions\Events\InteractionDeleted

Hard-deleting an actor or interactable removes its interactions. Soft deletion preserves them until the model is force deleted.

Development

composer test
composer analyse
composer format
composer validate --strict

License

The MIT License (MIT). Please see License File for more information.