Laravel Block

A simple Laravel package for blocking users.

Requirements

• PHP 8.3 or greater
• Laravel 12 or greater

Installation

Via Composer

$ composer require timgavin/laravel-block

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

namespace App\Models;

use TimGavin\LaravelBlock\LaravelBlock;

class User extends Authenticatable
{
    use LaravelBlock;
}

Then run migrations.

php artisan migrate

Configuration

Publish the config file.

php artisan vendor:publish --tag=laravel-block-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

Block a user

Returns true if the user was blocked, false if already blocking.

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

Unblock a user

Returns true if the user was unblocked, false if not blocking.

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

Toggle block

Returns true if now blocking, false if unblocked.

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

Check if a user is blocking another user

@if (auth()->user()->isBlocking($user))
    You are blocking this user.
@endif

Check if a user is blocked by another user

@if (auth()->user()->isBlockedBy($user))
    This user is blocking you.
@endif

Check if users are mutually blocking each other

@if (auth()->user()->isMutuallyBlocking($user))
    You are both blocking each other.
@endif

Check if there is any block relationship between two users

@if (auth()->user()->hasAnyBlockWith($user))
    There is a block relationship.
@endif

Get blocking count

auth()->user()->getBlockingCount();

Get blockers count

auth()->user()->getBlockersCount();

Get the users a user is blocking

auth()->user()->getBlocking();

Get the users a user is blocking with pagination

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

Get the users who are blocking a user

auth()->user()->getBlockers();

Get the users who are blocking a user with pagination

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

Get the most recent users who are blocking a user

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

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

auth()->user()->getBlockingIds();

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

auth()->user()->getBlockersIds();

Get an array of IDs of both blocking and blockers

auth()->user()->getBlockingAndBlockersIds();

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

Useful for feed exclusion - returns IDs of users you're blocking AND users blocking you.

auth()->user()->getAllBlockUserIds();

Get block 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()->getBlockStatusForUsers($userIds);

// Returns: [userId => ['is_blocking' => bool, 'is_blocked_by' => bool]]

Get block status for a single user

Returns bidirectional block status in a single query. Useful for profile pages.

$status = auth()->user()->getBlockStatusFor($user);

// Returns: ['is_blocking' => bool, 'is_blocked_by' => bool]

Query Scopes

Exclude blocked users from queries

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

// Exclude users blocked by or blocking the authenticated user
User::query()->excludeBlocked()->get();

// Exclude users blocked by or blocking a specific user
User::query()->excludeBlocked($user)->get();

Relationships

Access the blocks relationship (users this user is blocking).

$user->blocks;

Access the blockers relationship (users blocking this user).

$user->blockers;

Get the block relationship record where this user blocks another.

$user->getBlockingRelationship($otherUser);

Get the block relationship record where another user blocks this user.

$user->getBlockerRelationship($otherUser);

Get all block relationships between two users.

$user->getBlockRelationshipsWith($otherUser);

Caching

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

auth()->user()->cacheBlocking();

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

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

auth()->user()->getBlockingCache();

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

auth()->user()->cacheBlockers();

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

auth()->user()->getBlockersCache();

Clear the Blocking cache.

auth()->user()->clearBlockingCache();

Clear the Blockers cache.

auth()->user()->clearBlockersCache();

Clear the Blockers cache for another user. Useful after blocking a user to keep their blockers cache in sync.

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

Clear the Blocking cache for another user.

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

Note: The cache is automatically cleared when calling block() or unblock(). However, only the current user's cache is cleared. Use clearBlockersCacheFor() to clear the target user's blockers cache if needed.

Events

Events are dispatched when users block or unblock each other.

use TimGavin\LaravelBlock\Events\UserBlocked;
use TimGavin\LaravelBlock\Events\UserUnblocked;

Event::listen(UserBlocked::class, function ($event) {
    // $event->userId - the user who blocked
    // $event->blockedId - the user who was blocked
});

Event::listen(UserUnblocked::class, function ($event) {
    // $event->userId - the user who unblocked
    // $event->unblockedId - the user who was unblocked
});

Disable events in config.

'dispatch_events' => false,

Query Scopes

Query scopes are available on the Block model.

use TimGavin\LaravelBlock\Models\Block;

// Get blocks where a user is blocking others
Block::whereUserBlocks($userId)->get();

// Get blocks where a user is being blocked
Block::whereUserIsBlockedBy($userId)->get();

// Get all blocks involving a user
Block::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 tim@timgavin.me instead of using the issue tracker.

License

MIT. Please see the license file for more information.