timgavin/laravel-follow

A User can follow another User

v2.1.0 2025-12-08 22:43 UTC

Requires

• php: ^8.3

Requires (Dev)

• laravel/pint: ^1.26
• orchestra/testbench: ^10.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-laravel: ^4.0

MIT

• Tim Gavin

• laravel
• LaravelFollow
• Follow users

README

A simple Laravel package for following users.

Requirements

• PHP 8.3 or greater
• Laravel 12 or greater

Installation

Via Composer

$ composer require timgavin/laravel-follow

Import Laravel Follow into your User model and add the trait.

namespace App\Models;

use TimGavin\LaravelFollow\LaravelFollow;

class User extends Authenticatable
{
    use LaravelFollow;
}

Then run migrations.

php artisan migrate

Configuration

Publish the config file.

php artisan vendor:publish --tag=laravel-follow-config

Available options:

return [
    'cache_duration' => 60 * 60 * 24, // 24 hours in seconds
    'dispatch_events' => true,
    'user_model' => null, // falls back to auth config
];

Usage

Follow a user

Returns true if the user was followed, false if already following.

auth()->user()->follow($user);

Unfollow a user

Returns true if the user was unfollowed, false if not following.

auth()->user()->unfollow($user);

Toggle follow

Returns true if now following, false if unfollowed.

auth()->user()->toggleFollow($user);

Check if a user is following another user

@if (auth()->user()->isFollowing($user))
    You are following this user.
@endif

Check if a user is followed by another user

@if (auth()->user()->isFollowedBy($user))
    This user is following you.
@endif

Check if users are mutually following each other

@if (auth()->user()->isMutuallyFollowing($user))
    You follow each other.
@endif

Check if there is any follow relationship between two users

@if (auth()->user()->hasAnyFollowWith($user))
    There is a follow relationship.
@endif

Get following count

auth()->user()->getFollowingCount();

Get followers count

auth()->user()->getFollowersCount();

Get the users a user is following

auth()->user()->getFollowing();

Get the users a user is following with pagination

auth()->user()->getFollowingPaginated(15);

Get the users who are following a user

auth()->user()->getFollowers();

Get the users who are following a user with pagination

auth()->user()->getFollowersPaginated(15);

Get the most recent users who are following a user

// default limit is 5
auth()->user()->getLatestFollowers($limit);

Get an array of IDs of the users a user is following

auth()->user()->getFollowingIds();

Get an array of IDs of the users who are following a user

auth()->user()->getFollowersIds();

Get an array of IDs of both following and followers

auth()->user()->getFollowingAndFollowersIds();

Get all user IDs involved in any follow relationship (single query)

Returns IDs of users you're following AND users following you.

auth()->user()->getAllFollowUserIds();

Get follow status for multiple users in batch

Returns status for multiple users in just 2 queries instead of 2N. Useful for API responses.

$userIds = $users->pluck('id')->toArray();
$statuses = auth()->user()->getFollowStatusForUsers($userIds);

// Returns: [userId => ['is_following' => bool, 'is_followed_by' => bool]]

Query Scopes

Exclude follow-related users from queries

Excludes users involved in any follow relationship with the given user.

// Exclude users following or followed by the authenticated user
User::query()->excludeFollowRelated()->get();

// Exclude users following or followed by a specific user
User::query()->excludeFollowRelated($user)->get();

Relationships

Access the follows relationship (users this user is following).

$user->follows;

Access the followers relationship (users following this user).

$user->followers;

Get the follow relationship record where this user follows another.

$user->getFollowingRelationship($otherUser);

Get the follow relationship record where another user follows this user.

$user->getFollowerRelationship($otherUser);

Get all follow relationships between two users.

$user->getFollowRelationshipsWith($otherUser);

Caching

Cache the IDs of the users a user is following. Default duration is set in config.

auth()->user()->cacheFollowing();

// custom duration in seconds
auth()->user()->cacheFollowing(3600);

Get the cached IDs of the users a user is following.

auth()->user()->getFollowingCache();

Cache the IDs of the users who are following a user.

auth()->user()->cacheFollowers();

Get the cached IDs of the users who are following a user.

auth()->user()->getFollowersCache();

Clear the Following cache.

auth()->user()->clearFollowingCache();

Clear the Followers cache.

auth()->user()->clearFollowersCache();

Clear the Followers cache for another user. Useful after following a user to keep their followers cache in sync.

auth()->user()->clearFollowersCacheFor($user);

Clear the Following cache for another user.

auth()->user()->clearFollowingCacheFor($user);

Note: The cache is automatically cleared when calling follow() or unfollow(). However, only the current user's cache is cleared. Use clearFollowersCacheFor() to clear the target user's followers cache if needed.

Events

Events are dispatched when users follow or unfollow each other.

use TimGavin\LaravelFollow\Events\UserFollowed;
use TimGavin\LaravelFollow\Events\UserUnfollowed;

Event::listen(UserFollowed::class, function ($event) {
    // $event->userId - the user who followed
    // $event->followingId - the user who was followed
});

Event::listen(UserUnfollowed::class, function ($event) {
    // $event->userId - the user who unfollowed
    // $event->unfollowedId - the user who was unfollowed
});

Disable events in config.

'dispatch_events' => false,

Query Scopes

Query scopes are available on the Follow model.

use TimGavin\LaravelFollow\Models\Follow;

// Get follows where a user is following others
Follow::whereUserFollows($userId)->get();

// Get follows where a user is being followed
Follow::whereUserIsFollowedBy($userId)->get();

// Get all follows involving a user
Follow::involvingUser($userId)->get();

Upgrading

If upgrading from 1.x, please see the upgrade guide.

Change log

Please see the changelog for more information on what has changed recently.

Testing

$ composer test

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

License

MIT. Please see the license file for more information.