elemenx/laravel-acquaintances

This light package, with no dependencies, gives Eloquent models the ability to manage friendships (with groups). And interactions such as: Likes, favorites, votes, subscribe, follow, ..etc. And it includes advanced rating system.

Maintainers

Details

github.com/elemenx/laravel-acquaintances

Source

Installs: 114

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 72

v3.4.2 2021-01-28 08:05 UTC

Requires

  • php: >=7.1

Requires (Dev)

MIT 92218de4f1df41fc4a927c2bf1ecf63f5400c61b

  • Mohamed Kawsara <mkwsra.woop@gmail.com>

laravelfriendsfriendshipsRatinglikeeloquentRateFollowerssocial-mediafriend-systeminteractionsfollowshipswish-list

This package is auto-updated.

Last update: 2024-10-29 06:18:51 UTC

README

Total Downloads Latest Version License

Laravel News Article

Supports Laravel 8 and below, with no dependencies

TL;DR

Gives eloquent models:

  • Friendships & Groups ability
  • Interactions ability such as:
    • Likes
    • Favorites
    • Votes (up/down)
    • Subscribe
    • Follow
    • Ratings

Take this example:

$user1 = User::find(1);
$user2 = User::find(2);

$user1->befriend($user2);
$user2->acceptFriendRequest($user1);

// The messy breakup :(
$user2->unfriend($user1);
  1. Introduction
  2. Installation
  3. Friendships:
  4. Interactions
  5. Events
  6. Contributing

Introduction

This light package gives Eloquent models the ability to manage their acquaintances and other cool useful stuff. You can easily design your social-like System (Facebook, Twitter, Foursquare...etc).

Acquaintances includes:
  • Send Friend Requests
  • Accept Friend Requests
  • Deny Friend Requests
  • Block a User
  • Group Friends
  • Rate a User or a Model, supporting multiple aspects
  • Follow a User or a Model
  • Like a User or a Model
  • Subscribe a User or a Model
  • Favorite a User or a Model
  • Vote (Upvote & Downvote a User or a Model)

Installation

First, install the package through Composer.

$ composer require elemenx/laravel-acquaintances

Laravel 5.8 and up => version 2.x (branch master)

Laravel 5.7 and below => version 1.x (branch v1)

Laravel 5.4 and down

Then include the service provider inside config/app.php.

'providers' => [
//    ...
    ElemenX\Acquaintances\AcquaintancesServiceProvider::class,
//    ...
];

Publish config and migrations:

$ php artisan vendor:publish --provider="ElemenX\Acquaintances\AcquaintancesServiceProvider"

Configure the published config in:

config\acquaintances.php

Finally, migrate the database to create the table:

$ php artisan migrate

Setup a Model

Example:

use ElemenX\Acquaintances\Traits\Friendable;
use ElemenX\Acquaintances\Traits\CanFollow;
use ElemenX\Acquaintances\Traits\CanBeFollowed;
use ElemenX\Acquaintances\Traits\CanLike;
use ElemenX\Acquaintances\Traits\CanBeLiked;
use ElemenX\Acquaintances\Traits\CanRate;
use ElemenX\Acquaintances\Traits\CanBeRated;
//...

class User extends Model
{
    use Friendable;
    use CanFollow, CanBeFollowed;
    use CanLike, CanBeLiked;
    use CanRate, CanBeRated;
    //...
}

All available APIs are listed below for Friendships & Interactions.

Friendships:

Friend Requests:

Add Friendable Trait to User model.

use ElemenX\Acquaintances\Traits\Friendable;

class User extends Model
{
    use Friendable;
}

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 Friend Requests:

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);

Retrieve Friend Requests:

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 pending Friend Requests

$user->getFriendRequests();

Get the number of Friends

$user->getFriendsCount();

Get the number of Pending Requests

$user->getPendingsCount();

Get the number of mutual Friends with another user

$user->getMutualFriendsCount($otherUser);

Retrieve Friends:

To get a collection of friend models (ex. User) use the following methods:

getFriends()

$user->getFriends();
// or panigated
$user->getFriends($perPage = 20, $group_name);
// or paginated with certain fields 
$user->getFriends($perPage = 20, $group_name, $fields = ['id','name']);

Parameters:

  • $perPage: integer (default: 0), Get values paginated
  • $group_name: string (default: ''), Get collection of Friends in specific group paginated
  • $fields: array (default: ['*']), Specify the desired fields to query.

getFriendsOfFriends()

$user->getFriendsOfFriends();
// or
$user->getFriendsOfFriends($perPage = 20);
// or 
$user->getFriendsOfFriends($perPage = 20, $fields = ['id','name']);

Parameters:

  • $perPage: integer (default: 0), Get values paginated
  • $fields: array (default: ['*']), Specify the desired fields to query.

getMutualFriends()

Get mutual Friends with another user

$user->getMutualFriends($otherUser);
// or 
$user->getMutualFriends($otherUser, $perPage = 20);
// or 
$user->getMutualFriends($otherUser, $perPage = 20, $fields = ['id','name']);

Parameters:

  • $other: Model (required), The Other user model to check mutual friends with
  • $perPage: integer (default: 0), Get values paginated
  • $fields: array (default: ['*']), Specify the desired fields to query.

Friend Groups:

The friend groups are defined in the config/acquaintances.php file. The package comes with a few default groups. To modify them, or add your own, you need to specify a slug and a key.

// config/acquaintances.php
//...
'groups' => [
    'acquaintances' => 0,
    'close_friends' => 1,
    'family' => 2
];

Since you've configured friend groups, you can group/ungroup friends using the following methods.

Group a Friend

$user->groupFriend($friend, $group_name);

Remove a Friend from family group

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

Remove a Friend from all groups

$user->ungroupFriend($friend);

Get the number of Friends in specific group

$user->getFriendsCount($group_name);

To filter friendships by group you can pass a group slug.

$user->getAllFriendships($group_name);
$user->getAcceptedFriendships($group_name);
$user->getPendingFriendships($group_name);
...

Interactions

Traits Usage:

Add CanXXX Traits to User model.

use ElemenX\Acquaintances\Traits\CanFollow;
use ElemenX\Acquaintances\Traits\CanLike;
use ElemenX\Acquaintances\Traits\CanFavorite;
use ElemenX\Acquaintances\Traits\CanSubscribe;
use ElemenX\Acquaintances\Traits\CanVote;

class User extends Model
{
    use CanFollow, CanLike, CanFavorite, CanSubscribe, CanVote;
}

Add CanBeXXX Trait to target model, such as 'Post' or 'Book' ...:

use ElemenX\Acquaintances\Traits\CanBeLiked;
use ElemenX\Acquaintances\Traits\CanBeFavorited;
use ElemenX\Acquaintances\Traits\CanBeVoted;
use ElemenX\Acquaintances\Traits\CanBeRated;

class Post extends Model
{
    use CanBeLiked, CanBeFavorited, CanBeVoted, CanBeRated;
}

All available APIs are listed below.

Follow

\ElemenX\Acquaintances\Traits\CanFollow

$user->follow($targets);
$user->unfollow($targets);
$user->toggleFollow($targets);
$user->followings()->get(); // App\User:class
$user->followings(App\Post::class)->get();
$user->isFollowing($target);

\ElemenX\Acquaintances\Traits\CanBeFollowed

$object->followers()->get();
$object->isFollowedBy($user);
$object->followersCount(); // or as attribute $object->followers_count
$object->followersCountReadable(); // return readable number with precision, i.e: 5.2K

Rate

\ElemenX\Acquaintances\Traits\CanRate

$user->rate($targets);
$user->unrate($targets);
$user->toggleRate($targets);
$user->ratings()->get(); // App\User:class
$user->rateings(App\Post::class)->get();
$user->hasRated($target);

\ElemenX\Acquaintances\Traits\CanBeRated

$object->raters()->get();
$object->isRatedBy($user);

$object->averageRating(); // or as attribute $object->average_rating
$object->averageRatingAllTypes(); // or as attribute $object->average_rating_all_types

$object->sumRating(); // or as attribute $object->sum_rating
$object->sumRatingAllTypes(); // or as attribute $object->sum_rating_all_types_all_types

$object->sumRatingReadable(); // return readable number with precision, i.e: 5.2K
$object->sumRatingAllTypesReadable(); // return readable number with precision, i.e: 5.2K


$object->ratingPercent($max = 5); // calculating the percentage based on the passed coefficient
$object->ratingPercentAllTypes($max = 5); // calculating the percentage based on the passed coefficient

// User Related: 

$object->userAverageRatingAllTypes(); // or as attribute $object->user_average_rating_all_types

$object->userSumRatingAllTypes(); // or as attribute $object->user_sum_rating_all_types

$object->userSumRatingReadable(); // return readable number with precision, i.e: 5.2K
$object->userSumRatingAllTypesReadable(); // return readable number with precision, i.e: 5.2K

Like

\ElemenX\Acquaintances\Traits\CanLike

$user->like($targets);
$user->unlike($targets);
$user->toggleLike($targets);
$user->hasLiked($target);
$user->likes()->get(); // default object: App\User:class
$user->likes(App\Post::class)->get();

\ElemenX\Acquaintances\Traits\CanBeLiked

$object->likers()->get();
$object->fans()->get(); // or $object->fans. it's an alias of likers()
$object->isLikedBy($user);
$object->likersCount(); // or as attribute $object->likers_count
$object->likersCountReadable(); // return readable number with precision, i.e: 5.2K

Favorite

\ElemenX\Acquaintances\Traits\CanFavorite

$user->favorite($targets);
$user->unfavorite($targets);
$user->toggleFavorite($targets);
$user->hasFavorited($target);
$user->favorites()->get(); // App\User:class
$user->favorites(App\Post::class)->get();

\ElemenX\Acquaintances\Traits\CanBeFavorited

$object->favoriters()->get(); // or $object->favoriters 
$object->isFavoritedBy($user);
$object->favoritersCount(); // or as attribute $object->favoriters_count
$object->favoritersCountReadable(); // return readable number with precision, i.e: 5.2K

Subscribe

\ElemenX\Acquaintances\Traits\CanSubscribe

$user->subscribe($targets);
$user->unsubscribe($targets);
$user->toggleSubscribe($targets);
$user->hasSubscribed($target);
$user->subscriptions()->get(); // default object: App\User:class
$user->subscriptions(App\Post::class)->get();

ElemenX\Acquaintances\Traits\CanBeSubscribed

$object->subscribers(); // or $object->subscribers 
$object->isSubscribedBy($user);
$object->subscribersCount(); // or as attribute $object->subscribers_count
$object->subscribersCountReadable(); // return readable number with precision, i.e: 5.2K

Vote

\ElemenX\Acquaintances\Traits\CanVote

$user->vote($target); // Vote with 'upvote' for default
$user->upvote($target);
$user->downvote($target);
$user->cancelVote($target);
$user->hasUpvoted($target);
$user->hasDownvoted($target);
$user->votes(App\Post::class)->get();
$user->upvotes(App\Post::class)->get();
$user->downvotes(App\Post::class)->get();

\ElemenX\Acquaintances\Traits\CanBeVoted

$object->voters()->get();
$object->isVotedBy($user);
$object->votersCount(); // or as attribute $object->voters_count
$object->votersCountReadable(); // return readable number with precision, i.e: 5.2K

$object->upvoters()->get();
$object->isUpvotedBy($user);
$object->upvotersCount(); // or as attribute $object->upvoters_count
$object->upvotersCountReadable(); // return readable number with precision, i.e: 5.2K

$object->downvoters()->get();
$object->isDownvotedBy($user);
$object->downvotersCount(); // or as attribute $object->downvoters_count
$object->downvotersCountReadable(); // return readable number with precision, i.e: 5.2K

Parameters

All the above mentioned methods of creating relationships, such as 'follow', 'like', 'unfollow', 'unlike', their syntax is as follows:

follow(array|int|\Illuminate\Database\Eloquent\Model $targets, $class = __CLASS__)

So you can call them like this:

// id / int|array
$user->follow(1); // targets: 1, $class = App\User
$user->follow(1, App\Post::class); // targets: 1, $class = App\Post
$user->follow([1, 2, 3]); // targets: [1, 2, 3], $class = App\User

// Model
$post = App\Post::find(7);
$user->follow($post); // targets: $post->id, $class = App\Post

// Model array
$posts = App\Post::popular()->get();
$user->follow($posts); // targets: [1, 2, ...], $class = App\Post

Query relations

$followers = $user->followers;
$followers = $user->followers()->where('id', '>', 10)->get();
$followers = $user->followers()->orderByDesc('id')->get();
$followers = $user->followers()->paginate(10);

You may use the others in the same way.

Working with model

use ElemenX\Acquaintances\Models\InteractionRelation;

// Get most popular object
// 1- All types
$relations = InteractionRelation::popular()->get();

// 2- subject_type = App\Post
$relations = InteractionRelation::popular(App\Post::class)->get(); 

// 3- subject_type = App\User
$relations = InteractionRelation::popular('user')->get();
 
// 4- subject_type = App\Post
$relations = InteractionRelation::popular('post')->get();

// 5- Pagination
$relations = InteractionRelation::popular(App\Post::class)->paginate(15);

Events

This is the list of the events fired by default for each action:

Contributing

See the CONTRIBUTING guide.

The initial version of this library was assisted by the following repos laravel-friendships & laravel-follow.

Change Log

See the log file.