Social Interactions Laravel Package

Getting Started

Requirements: PHP ^8.3|^8.4, Laravel ^12.0|^13.0. If you're on Laravel 10/11 or PHP 8.2, stay on 1.1.x — 2.0.0 does not back-fill support.

Fresh install

composer require toneflix/social-interactions:^2.0

Publish the package assets (config + migrations) and run them:

php artisan vendor:publish --provider="Toneflix\SocialInteractions\SocialInteractionsServiceProvider"
php artisan migrate

If the provider isn't listed, run a bare php artisan vendor:publish and select the toneflix/social-interactions entry — the tag names are the thing most likely to drift between majors, so confirm against the README rather than copying tags from an old blog post.

First use case: add the package's interaction trait to your User model (the acting side) and to the models that receive interactions — typically Post, Comment, Video. Then the smallest end-to-end flow is: a user likes a post, you read the count back, and the user unlikes it. Get that working in a tinker session or a single Pest test before wiring controllers.

First place to look: the published config file. It defines the interaction types/resolvers and model bindings, and it is the single file you must hand-edit during the upgrade (see Gotchas).

Implementation Patterns

Upgrade path (1.1.x → 2.0.0). This is a rename-only major: vendor toneflix-code → toneflix, namespace ToneflixCode\SocialInteractions → Toneflix\SocialInteractions. No behavioural changes are described.

composer remove toneflix-code/social-interactions
composer require toneflix/social-interactions:^2.0

Do the removal in a separate commit from the require, and do the namespace sweep before running tests:

grep -rn "ToneflixCode\\\\SocialInteractions" app/ config/ database/ tests/
# then rewrite imports, and fix the class strings inside config/social-interactions.php
composer dump-autoload
php artisan config:clear && php artisan cache:clear

Trait-based modelling. The value of a package like this is that interactions are polymorphic and live outside your domain models. Add the trait to the actor (User) and to each interactable model, then keep controllers thin:

// app/Models/Post.php
use Toneflix\SocialInteractions\Concerns\InteractsWithSocial; // verify exact trait name in README

class Post extends Model
{
    use InteractsWithSocial;
}

Wrap the actions in your own service or action classes (LikePost, BookmarkPost) so the package API appears in one place. That containment is what made the 2.0 namespace change a one-file edit for teams that did it, and a find-and-replace across forty controllers for teams that didn't.

Read counts without N+1. Interaction counts are almost always rendered in a list. Eager-load the count on the index query rather than calling a count method per row in Blade:

$posts = Post::query()
    ->withCount('likes')      // confirm relation names against the published config
    ->latest()
    ->paginate(20);

Then $post->likes_count in the view. If your index is hot, cache the count on the model (updated in the same transaction as the interaction write) rather than aggregating on every request.

Toggle semantics. Likes and bookmarks are idempotent by nature — a double-tap should not create two rows. Prefer the package's toggle-style methods over create(), and enforce the invariant at the database level with a unique index on (user_id, interactable_type, interactable_id, type) in your own migration if the package doesn't ship one.

API resources. Return interaction state as a flag alongside the count so the client can render the button without a second round trip:

return [
    'id'         => $post->id,
    'likes'      => $post->likes_count,
    'liked'      => $post->isLikedBy($request->user()), // check method name
];

CI matrix. Align your own CI with the package's: test on PHP 8.3 and 8.4 against Laravel 12 and 13. Testbench ^10.11|^11.1 and Pest ^4 are the dev-tooling baseline, so if you maintain a package that depends on this one, mirror those constraints.

Gotchas and Tips

Two packages installed at once. composer remove before composer require is not cosmetic. Leaving both installed gives you duplicate service providers, two config files, and a class-resolution coin flip. If composer refuses the removal because something still requires it, find the dependent with composer why toneflix-code/social-interactions.

The published config is the sneaky part. The upgrade notes call it out explicitly, and it's the most common miss: your config/social-interactions.php was published under the old namespace and may contain fully-qualified class strings for model bindings or interaction resolvers. A use-statement sweep won't touch it. Grep the config directory, not just app/.

Stale caches will fool you. After the namespace change, run composer dump-autoload, php artisan config:clear, and php artisan cache:clear. A cached config or a stale classmap produces "class not found" errors that look like a broken install when the code is actually correct.

Laravel 12/13 only. Don't attempt the upgrade on Laravel 11 expecting it to work because the changelog's feature line reads like a routine bump. The Illuminate constraint is ^12.0|^13.0 — hard. Same for PHP: 8.3 is the floor.

Orphaned interactions. Polymorphic rows outlive the models they point at unless the package registers morph-map cleanup or you add cascading deletes. When a Post is deleted, its likes should go with it. Test this — a stale-row build-up is invisible until your counts are wrong six months later.

Semantic versioning honesty. A vendor rename plus a platform bump is a legitimate major, but it means 2.0.0 ships no new capability. Don't schedule a "what's new" review with your team; schedule a mechanical upgrade window, and put the saved effort into the trait-containment refactor if you skipped it earlier.

Extension points. The package is config-driven: custom interaction types and model bindings belong in the published config, not in forked vendor code. If you find yourself needing to modify vendor/toneflix/, you want an event listener or a subclass registered through the config instead — forking makes every future vendor change a merge.

Pin the major. Given the vendor rename, toneflix/social-interactions:^1.1 will not resolve to anything after the move. Update composer.json constraints in every service that shares the codebase, and check your lock files into version control so the switch is reviewable.