Add friendship features to your ActiveRecord models.
HasFriendship allows ActiveRecord objects to send, accept, and decline friend requests using self-refernetial polymorphic association.
Getting started
Add HasFriendship to your Gemfile:
gem 'has_friendship'
After you install HasFriendship, you need to run the generator:
$ rails generate has_friendship
The generator will copy a migration that creates friendships
table. Run the migration to finish the setup.
$ rake db:migrate
Upgrading to 0.1.0
0.1.0
adds a blocking feature for friendables. This requires an additional
column in the friendships
table, and a migration should be run. You will need
to run the generator and run the new migration.
Upgrading to 1.x.x
If upgrading from <= 0.1.3 to 1.x.x, please run the following generator:
$ rails generate has_friendship_update
Then, run the migration:
$ rake db:migrate
Usage
Simply drop in has_friendship
to a model:
class User < ActiveRecord::Base
has_friendship
end
Managing friendship
Now, instances of User
can send, accept, and decline friend requests:
@mac = User.create(name: "Mac")
@dee = User.create(name: "Dee")
# @mac sends a friend request to @dee
@mac.friend_request(@dee)
# @dee can accept the friend request
@dee.accept_request(@mac)
# @dee can also decline the friend request
@dee.decline_request(@mac)
A friendship can also be removed:
# @dee removes @mac from its friends
@dee.remove_friend(@mac)
Blocking a friendable
A friendable can be blocked. When blocked, the friendable cannot request or remove friendship to the one that initially blocked it.
@dee.request_friend(@mac)
# @mac blocks @dee from making any more friendship actions
@mac.block_friend(@dee)
# @mac unblocks @dee
# Only @mac can perform this action
@mac.unblock_friend(@dee)
Checking friendship
# Check if there is an accepted friendship between @mac and @dee
@mac.friends_with?(@dee)
Type of friends
There are four types of friends:
- requested_friends
- pending_friends
- blocked_friends
- friends
Each type returns an array of friends, which should be looped through to access specific friends. They can be accessed using association.
requested_friends
Instances that sent friend request that has not been accepted.
@mac.friend_request(@dee)
@dee.requested_friends # => [@mac]
pending_friends
Instances that received but has not accepted the friend request.
@mac.friend_request(@dee)
@mac.pending_friends # => [@dee]
blocked_friends
Instances that are blocked from taking any friendship actions
@dee.friend_request(@mac)
@mac.block_friend(@dee)
@mac.blocked_friends # => [@dee]
friends
Instances with accepted Friendship.
@mac.friend_request(@dee)
@dee.accept_request(@mac)
@mac.friends # => [@dee]
@dee.friends # => [@mac]
Callbacks
To use callbacks you can add methods described below, to your Friendable model.
def on_friendship_created(friendship)
...
end
def on_friendship_accepted(friendship)
...
end
def on_friendship_blocked(friendship)
...
end
Roadmap
Thanks for all the contributors. Pull requests are encouraged for the following features.
- Make a separate table/model for friendship blocking records, with
blocker_id
andblockee_id
. Currently,Friendship
model is kind of bloated. - Implement state machine for friendship status. (#24)