README

This package gives Eloquent models the ability to manage friendships. You can build friend requests, accepted friendships, blocks, and friend groups.

Supported versions

32f48a81a50a2d5492c417310dbe1a1c9f865d4b

Laravel 12 supports PHP 8.2+, while Laravel 13 requires PHP 8.3+. Composer will automatically resolve compatible versions based on your project.

Models can:

• Send friend requests
• Accept friend requests
• Deny friend requests
• Block another model
• Group friends

Installation

Install the package through Composer.

composer require user-pixel-error/laravel-friendships

Laravel will auto-discover the service provider. Publish the config and migrations when you are ready to customize the table names or groups.

php artisan vendor:publish --provider="PixelError\Friendships\FriendshipsServiceProvider" --tag="friendships-config"
php artisan vendor:publish --provider="PixelError\Friendships\FriendshipsServiceProvider" --tag="friendships-migrations"
php artisan migrate

The config file will be published to:

config/friendships.php

Setup a Model

use Illuminate\Foundation\Auth\User as Authenticatable;
use PixelError\Friendships\Traits\Friendable;

class User extends Authenticatable
{
    use Friendable;
    // ...
}

How to use

Check the Test file to see the package in action

Send a Friend Request

$user->befriend($recipient);

Accept a Friend Request

$user->acceptFriendRequest($sender);

Deny a Friend Request

$user->denyFriendRequest($sender);

Remove Friend

$user->unfriend($friend);

Block a Model

$user->blockFriend($friend);

Unblock a Model

$user->unblockFriend($friend);

Check if Model is Friend with another Model

$user->isFriendWith($friend);

Check if Model has a pending friend request from another Model

$user->hasFriendRequestFrom($sender);

Check if Model has already sent a friend request to another Model

$user->hasSentFriendRequestTo($recipient);

Check if Model has blocked another Model

$user->hasBlocked($friend);

Check if Model is blocked by another Model

$user->isBlockedBy($friend);

Get a single friendship

$user->getFriendship($friend);

Get a list of all Friendships

$user->getAllFriendships();

Get a list of pending Friendships

$user->getPendingFriendships();

Get a list of accepted Friendships

$user->getAcceptedFriendships();

Get a list of denied Friendships

$user->getDeniedFriendships();

Get a list of blocked Friendships

$user->getBlockedFriendships();

Get a list of Friend Requests

$user->getFriendRequests();

Get friends collection

$user->getFriends();

Get friends paginator

$user->getFriends($perPage = 20);

Group a friend

$user->groupFriend($friend, 'close_friends');

Remove a friend from a group

$user->ungroupFriend($friend, 'close_friends');

Remove a friend from all groups

$user->ungroupFriend($friend);

Legacy namespace support

Older applications may still use the original package namespace:

use Hootlex\Friendships\Traits\Friendable;
use Hootlex\Friendships\Status;

This package includes Composer-loaded aliases so older imports can continue working while you migrate to the new namespace.

New applications should use:

use PixelError\Friendships\Traits\Friendable;
use PixelError\Friendships\Status;

After installing or updating the package, regenerate Composer autoload files if needed:

composer dump-autoload

Development tools

This package includes Laravel Pint and PHPStan/Larastan for code quality.

composer format       # Format code with Laravel Pint
composer format:test  # Check formatting without modifying files
composer analyse      # Run PHPStan/Larastan
composer test         # Run PHPUnit
composer ci           # Run style check, static analysis, and tests

v1.0.2 maintenance focus

Version v1.0.2 focuses on package stability:

• Fixed legacy namespace aliases
• Added Status legacy alias support
• Added cleaner FriendshipGroup model naming
• Kept FriendFriendshipGroups for backwards compatibility
• Added return types to the friendship API
• Added better tests for aliases, model naming, and return types
• Added Laravel Pint
• Added PHPStan/Larastan