edram/laravel-interactions

Laravel interactions package

0.0.2 2026-07-13 05:38 UTC

Requires

• php: ^8.3
• illuminate/contracts: ^12.0 || ^13.0
• illuminate/database: ^12.0 || ^13.0
• illuminate/support: ^12.0 || ^13.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.24
• orchestra/testbench: ^10.0 || ^11.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-laravel: ^4.0

MIT

• edram

• laravel
• interactions

Published on Packagist.org on 2026-07-13 05:46 UTC

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(), followers(), subscribers(), and voters():

// 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.

For a smaller model API, combine the core concerns with only the semantic concerns the model needs:

use Edram\LaravelInteractions\Concerns\Actor\Follows;
use Edram\LaravelInteractions\Concerns\Actor\HasInteractions;
use Edram\LaravelInteractions\Concerns\Actor\Likes;
use Edram\LaravelInteractions\Concerns\Target\HasFollowers;
use Edram\LaravelInteractions\Concerns\Target\HasLikers;
use Edram\LaravelInteractions\Concerns\Target\ReceivesInteractions;

class User extends Authenticatable
{
    use HasInteractions;
    use Follows;
    use Likes;
    use ReceivesInteractions;
    use HasFollowers;
}

class Post extends Model
{
    use ReceivesInteractions;
    use HasLikers;
}

Actor semantic concerns require HasInteractions. Target semantic concerns require ReceivesInteractions. Interacts and Interactable remain the convenient all-in-one alternatives.

Actor models

Any Eloquent model using Interacts, or HasInteractions with selected Actor concerns, can initiate interactions. default_actor is not an allowlist; it only chooses the related model when a target-side relation omits its Actor class.

class Team extends Model
{
    use Interactable;
    use Interacts;
}

$user->like($post);
$team->like($post);

$post->likers()->get();            // User from default_actor
$post->likers(Team::class)->get(); // Team

$user->follow($team);
$team->followers()->get();         // User from default_actor
$team->followers(Team::class)->get();

A direct Eloquent relation returns one Actor model type. Query interaction records and eager load the polymorphic actor relation when all types are required:

$likes = $post->receivedInteractions('like')
    ->with('actor')
    ->get();

$actors = $likes->pluck('actor')->filter();

When no Actor class is passed, the package resolves default_actor and then falls back to auth.providers.users.model. Pass the class explicitly to override either default.

Built-in interactions

Interaction	Actor API	Target API
Like	like, unlike, toggleLike, hasLiked, likes, likedItems	isLikedBy, likers, likersFor
Favorite	favorite, unfavorite, toggleFavorite, hasFavorited, favorites, favoriteItems	isFavoritedBy, favoriters
Subscribe	subscribe, unsubscribe, toggleSubscribe, hasSubscribed, subscriptions, subscribedItems	isSubscribedBy, subscribers
Follow	follow, unfollow, toggleFollow, isFollowing, following	isFollowedBy, followers
Vote	vote, upvote, downvote, cancelVote, hasVoted, votes	isVotedBy, voters, upvoters, downvoters, totalVotes

$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.