rolify

Add rolify to your Gemfile and run bundle to install the gem.

Requirements:

• Rails >= 4.2
• ActiveRecord >= 4.2 OR Mongoid >= 4.0
• Ruby 2.2+

gem "rolify"

Use the Rolify generator to create your Role model, add migrations, and update your User class. By default, it uses Role and User as class names. You can specify custom names if your authentication solution uses a different User class.

If using Mongoid, add the --orm=mongoid flag.

Note for Rolify versions < 3.3: Use rails g rolify:role Role User instead.

rails g rolify Role User

Use the Rolify Rails generator to set up the necessary ActiveRecord models and migrations for role management. By default, the generator expects a model named User to exist in your application. If your user model has a different name, you must provide it as an argument.

To use the generator, run the following command in your terminal:

rails generate rolify [USER_CLASS_NAME]

Example for a model named Account:

rails generate rolify Account

Rolify supports active_record (the default) and mongoid. You can switch the adapter used during testing by setting the ADAPTER environment variable before running bundle or rake commands.

ADAPTER=mongoid bundle
ADAPTER=mongoid rake

To avoid N+1 query issues when checking roles for a collection of users, preload the roles and use has_cached_role?.

Warning: You must preload the roles correctly. If you preload only specific roles using with_role, has_cached_role? will return false for any roles not included in that preload.

@user.add_role :admin, Forum
@user.add_role :member, Forum

# Preload roles to allow cached checking
users = User.with_role(:admin, Forum).preload(:roles)
users.each do |user|
  user.has_cached_role?(:member, Forum) # no extra queries
end

You can assign roles globally, to a specific resource instance, or to a resource class.

• Global role: user.add_role :admin
• Instance-scoped role: user.add_role :moderator, forum_instance
• Class-scoped role: user.add_role :moderator, Forum

To remove a role, use user.remove_role :role_name.

The rolify method is added to your User class. You can use it to define callbacks that trigger when roles are added or removed.

Supported callback options:

• before_add
• after_add
• before_remove
• after_remove

You can also use the inverse_of option to disambiguate relationships.

class User < ActiveRecord::Base
  rolify :before_add => :before_add_method

  def before_add_method(role)
    # do something before it gets added
  end
end

To allow roles to be scoped to a specific resource, add the resourcify method to that resource's class.

class Forum < ActiveRecord::Base
  resourcify
end

Check if a user has a specific role using has_role?.

• Global check: user.has_role? :admin
• Instance check: user.has_role? :moderator, forum_instance
• Class check: user.has_role? :moderator, Forum (returns true for both class-scoped and instance-scoped roles).

Use has_strict_role? to check for the exact role scope without falling back to global or class-level roles.

# Global
user.has_role? :admin

# Instance
user.has_role? :moderator, Forum.first

# Class
user.has_role? :moderator, Forum

# Strict (only returns true if the role was explicitly added to that specific scope)
user.has_strict_role? :moderator, Forum.last