From 37fec370bab30e6335f5a5224e0c415884e35ccd Mon Sep 17 00:00:00 2001
From: KawsaraMohamed MK <mkwsra@gmail.com>
Date: Fri, 1 Jan 2021 13:33:35 +0300
Subject: [PATCH] update readme

---
 README.md | 279 +++++++++++++++++++++++++++++++++---------------------
 1 file changed, 171 insertions(+), 108 deletions(-)

diff --git a/README.md b/README.md
index a047228..19b363d 100755
--- a/README.md
+++ b/README.md
@@ -10,10 +10,10 @@
 
 Supports Laravel 8 and below, with no dependencies
 
-
 ## TL;DR
 
 Gives eloquent models:
+
 - Friendships & Groups ability
 - Interactions ability such as:
     - Likes
@@ -22,8 +22,9 @@ Gives eloquent models:
     - Subscribe
     - Follow
     - Ratings
-    
+
 Take this example:
+
 ```php
 $user1 = User::find(1);
 $user2 = User::find(2);
@@ -35,6 +36,7 @@ $user2->acceptFriendRequest($user1);
 $user2->unfriend($user1);
 
 ```
+
 1. [Introduction](#introduction)
 1. [Installation](#installation)
 2. [Friendships:](#friendships)
@@ -57,11 +59,13 @@ $user2->unfriend($user1);
 4. [Events](#events)
 5. [Contributing](#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).
+
+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
@@ -75,6 +79,7 @@ You can easily design your social-like System (Facebook, Twitter, Foursquare...e
 - Vote (Upvote & Downvote a User or a Model)
 
 ---
+
 ## Installation
 
 First, install the package through Composer.
@@ -82,64 +87,76 @@ First, install the package through Composer.
 ```sh
 $ composer require multicaret/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`.
 
 ```php
 'providers' => [
-    ...
+//    ...
     Multicaret\Acquaintances\AcquaintancesServiceProvider::class,
-    ...
+//    ...
 ];
 ```
 
 Publish config and migrations:
+
 ```sh
 $ php artisan vendor:publish --provider="Multicaret\Acquaintances\AcquaintancesServiceProvider"
 ```
 
 Configure the published config in:
+
 ```
 config\acquaintances.php
 ```
 
 Finally, migrate the database to create the table:
+
 ```sh
 $ php artisan migrate
 ```
 
 ---
+
 ## Setup a Model
 
 Example:
+
 ```php
-use Multicaret\Acquaintances\Traits\CanBeFollowed;
+use Multicaret\Acquaintances\Traits\Friendable;
 use Multicaret\Acquaintances\Traits\CanFollow;
+use Multicaret\Acquaintances\Traits\CanBeFollowed;
 use Multicaret\Acquaintances\Traits\CanLike;
-use Multicaret\Acquaintances\Traits\Friendable;
+use Multicaret\Acquaintances\Traits\CanBeLiked;
+use Multicaret\Acquaintances\Traits\CanRate;
+use Multicaret\Acquaintances\Traits\CanBeRated;
 //...
 
 class User extends Model
 {
     use Friendable;
-    use CanLike;
     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.
 
 ```php
@@ -152,116 +169,143 @@ class User extends Model
 ```
 
 #### Send a Friend Request
+
 ```php
 $user->befriend($recipient);
 ```
 
 #### Accept a Friend Request
+
 ```php
 $user->acceptFriendRequest($sender);
 ```
 
 #### Deny a Friend Request
+
 ```php
 $user->denyFriendRequest($sender);
 ```
 
 #### Remove Friend
+
 ```php
 $user->unfriend($friend);
 ```
 
 #### Block a Model
+
 ```php
 $user->blockFriend($friend);
 ```
 
 #### Unblock a Model
+
 ```php
 $user->unblockFriend($friend);
 ```
 
 #### Check if Model is Friend with another Model
+
 ```php
 $user->isFriendWith($friend);
 ```
 
-
 ### Check Friend Requests:
 
 #### Check if Model has a pending friend request from another Model
+
 ```php
 $user->hasFriendRequestFrom($sender);
 ```
 
 #### Check if Model has already sent a friend request to another Model
+
 ```php
 $user->hasSentFriendRequestTo($recipient);
 ```
 
 #### Check if Model has blocked another Model
+
 ```php
 $user->hasBlocked($friend);
 ```
 
 #### Check if Model is blocked by another Model
+
 ```php
 $user->isBlockedBy($friend);
 ```
+
 ---
+
 ### Retrieve Friend Requests:
+
 #### Get a single friendship
+
 ```php
 $user->getFriendship($friend);
 ```
 
 #### Get a list of all Friendships
+
 ```php
 $user->getAllFriendships();
 ```
 
 #### Get a list of pending Friendships
+
 ```php
 $user->getPendingFriendships();
 ```
 
 #### Get a list of accepted Friendships
+
 ```php
 $user->getAcceptedFriendships();
 ```
 
 #### Get a list of denied Friendships
+
 ```php
 $user->getDeniedFriendships();
 ```
 
 #### Get a list of blocked Friendships
+
 ```php
 $user->getBlockedFriendships();
 ```
 
 #### Get a list of pending Friend Requests
+
 ```php
 $user->getFriendRequests();
 ```
 
 #### Get the number of Friends
+
 ```php
 $user->getFriendsCount();
 ```
+
 #### Get the number of Pending Requests
+
 ```php
 $user->getPendingsCount();
 ```
 
 #### Get the number of mutual Friends with another user
+
 ```php
 $user->getMutualFriendsCount($otherUser);
 ```
 
 ## Retrieve Friends:
+
 To get a collection of friend models (ex. User) use the following methods:
+
 #### `getFriends()`
+
 ```php
 $user->getFriends();
 // or panigated
@@ -269,13 +313,15 @@ $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 
+* `$group_name`: string (default: `''`), Get collection of Friends in specific group paginated
 * `$fields`: array (default: `['*']`), Specify the desired fields to query.
 
-
 #### `getFriendsOfFriends()`
+
 ```php
 $user->getFriendsOfFriends();
 // or
@@ -283,12 +329,16 @@ $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
+
 ```php
 $user->getMutualFriends($otherUser);
 // or 
@@ -298,48 +348,54 @@ $user->getMutualFriends($otherUser, $perPage = 20, $fields = ['id','name']);
 ```
 
 Parameters:
-* `$other`: Model (required), The Other user model to check mutual friends with  
+
+* `$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`.
+
+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`.
 
 ```php
 // 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
+
 ```php
 $user->groupFriend($friend, $group_name);
 ```
 
 #### Remove a Friend from family group
+
 ```php
 $user->ungroupFriend($friend, 'family');
 ```
 
 #### Remove a Friend from all groups
+
 ```php
 $user->ungroupFriend($friend);
 ```
 
 #### Get the number of Friends in specific group
+
 ```php
 $user->getFriendsCount($group_name);
 ```
 
 #### To filter `friendships` by group you can pass a group slug.
+
 ```php
 $user->getAllFriendships($group_name);
 $user->getAcceptedFriendships($group_name);
@@ -348,7 +404,9 @@ $user->getPendingFriendships($group_name);
 ```
 
 ## Interactions
+
 ### Traits Usage:
+
 Add `CanXXX` Traits to User model.
 
 ```php
@@ -385,21 +443,21 @@ All available APIs are listed below.
 #### `\Multicaret\Acquaintances\Traits\CanFollow`
 
 ```php
-$user->follow($targets)
-$user->unfollow($targets)
-$user->toggleFollow($targets)
-$user->followings()->get() // App\User:class
-$user->followings(App\Post::class)->get()
-$user->isFollowing($target)
+$user->follow($targets);
+$user->unfollow($targets);
+$user->toggleFollow($targets);
+$user->followings()->get(); // App\User:class
+$user->followings(App\Post::class)->get();
+$user->isFollowing($target);
 ```
 
 #### `\Multicaret\Acquaintances\Traits\CanBeFollowed`
 
 ```php
-$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
+$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
@@ -407,41 +465,41 @@ $object->followersCountReadable() // return readable number with precision, i.e:
 #### `\Multicaret\Acquaintances\Traits\CanRate`
 
 ```php
-$user->rate($targets)
-$user->unrate($targets)
-$user->toggleRate($targets)
-$user->ratings()->get() // App\User:class
-$user->rateings(App\Post::class)->get()
-$user->hasRated($target)
+$user->rate($targets);
+$user->unrate($targets);
+$user->toggleRate($targets);
+$user->ratings()->get(); // App\User:class
+$user->rateings(App\Post::class)->get();
+$user->hasRated($target);
 ```
 
 #### `\Multicaret\Acquaintances\Traits\CanBeRated`
 
 ```php
-$object->raters()->get()
-$object->isRatedBy($user)
+$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->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->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->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
+$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->userAverageRatingAllTypes(); // or as attribute $object->user_average_rating_all_types
 
-$object->userSumRatingAllTypes() // or as attribute $object->user_sum_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
+$object->userSumRatingReadable(); // return readable number with precision, i.e: 5.2K
+$object->userSumRatingAllTypesReadable(); // return readable number with precision, i.e: 5.2K
 
 
 ```
@@ -451,22 +509,22 @@ $object->userSumRatingAllTypesReadable() // return readable number with precisio
 #### `\Multicaret\Acquaintances\Traits\CanLike`
 
 ```php
-$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()
+$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();
 ```
 
 #### `\Multicaret\Acquaintances\Traits\CanBeLiked`
 
 ```php
-$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
+$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
@@ -474,21 +532,21 @@ $object->likersCountReadable() // return readable number with precision, i.e: 5.
 #### `\Multicaret\Acquaintances\Traits\CanFavorite`
 
 ```php
-$user->favorite($targets)
-$user->unfavorite($targets)
-$user->toggleFavorite($targets)
-$user->hasFavorited($target)
-$user->favorites()->get() // App\User:class
-$user->favorites(App\Post::class)->get()
+$user->favorite($targets);
+$user->unfavorite($targets);
+$user->toggleFavorite($targets);
+$user->hasFavorited($target);
+$user->favorites()->get(); // App\User:class
+$user->favorites(App\Post::class)->get();
 ```
 
 #### `\Multicaret\Acquaintances\Traits\CanBeFavorited`
 
 ```php
-$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
+$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
@@ -496,21 +554,21 @@ $object->favoritersCountReadable() // return readable number with precision, i.e
 #### `\Multicaret\Acquaintances\Traits\CanSubscribe`
 
 ```php
-$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()
+$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();
 ```
 
 #### `Multicaret\Acquaintances\Traits\CanBeSubscribed`
 
 ```php
-$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
+$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
@@ -518,39 +576,40 @@ $object->subscribersCountReadable() // return readable number with precision, i.
 #### `\Multicaret\Acquaintances\Traits\CanVote`
 
 ```php
-$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()
+$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();
 ```
 
 #### `\Multicaret\Acquaintances\Traits\CanBeVoted`
 
 ```php
-$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->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->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
+$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 of the above mentioned methods of creating relationships, such as 'follow', 'like', 'unfollow', 'unlike', their syntax is as follows:
+All the above mentioned methods of creating relationships, such as 'follow', 'like', 'unfollow', 'unlike', their syntax
+is as follows:
 
 ```php
 follow(array|int|\Illuminate\Database\Eloquent\Model $targets, $class = __CLASS__)
@@ -576,9 +635,10 @@ $user->follow($posts); // targets: [1, 2, ...], $class = App\Post
 ### Query relations
 
 ```php
-$followers = $user->followers
-$followers = $user->followers()->where('id', '>', 10)->get()
-$followers = $user->followers()->orderByDesc('id')->get()
+$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.
@@ -607,6 +667,7 @@ $relations = InteractionRelation::popular(App\Post::class)->paginate(15);
 ```
 
 ## Events
+
 This is the list of the events fired by default for each action:
 
 |Event name                     |Fired                                          |
@@ -631,12 +692,14 @@ This is the list of the events fired by default for each action:
 |acq.subscriptions.subscribe    |When a an item or items get subscribed         |                 
 |acq.subscriptions.unsubscribe  |When a an item or items get unsubscribed       |                 
 
-
 ### Contributing
+
 See the [CONTRIBUTING](CONTRIBUTING.md) guide.
 
-The initial version of this library was assisted by the following repos [laravel-friendships](https://github.com/hootlex/laravel-friendships)
+The initial version of this library was assisted by the following
+repos [laravel-friendships](https://github.com/hootlex/laravel-friendships)
 & [laravel-follow](https://github.com/overtrue/laravel-follow).
 
 ### Change Log
+
 See the [log](CHANGELOG.md) file.