masonite-permission 0.1.4

Associate users with roles and permissions

Masonite Permission

Introduction

Associate users with roles and permissions

Getting Started

Install the package using pip:

pip install masonite-permission

Add PermissionProvider to your project in config/providers.py:

# config/providers.py
# ...
from masonite_permission import PermissionProvider

# ...
PROVIDERS = [
    # ...
    # Third Party Providers
    PermissionProvider,
    # ...
]

Publish the package configuration files.

python craft package:publish masonite-permission

This will add migrations and other masonite-permission related configuration to your project. Run your migrations to create the related database tables.

python craft migrate

Now, extend User model class with HasRoles mixin.

from masoniteorm.models import Model
from masoniteorm.scopes import SoftDeletesMixin
from masonite.authentication import Authenticates
from masonite_permission.mixins import HasRoles

class User(Model, SoftDeletesMixin, Authenticates, HasRoles):
    """User Model."""

    __fillable__ = ["name", "email", "password"]
    __hidden__ = ["password"]
    __auth__ = "email"

Usage

Working with Role

Creating Role

""" Creating Role
    Arguments:
        name: The name of the role
        slug: The slug of the role, must be unique
"""
from masonite_permission.models import Role

role = Role.create({
    "name": "Admin",
    "slug": "admin"
})

Add permissions into roles

""" Add permissions into roles
    Available Methods:
        1. sync_permissions: Syncs the permissions with the role
            arguments: Takes a list of permission ids or permission collection
        2. attach_permission: Adds a permission to a role
            arguments: Takes permission model object or permission id
        3. detach_permission: Removes a permission from the role
            arguments: Takes permission model object or permission id
"""

""" Syncing permissions with role, adds provided permissions and removes all other permissions
    Arguments:
        permissions: Takes a list of permission ids or permission collection
"""
permission_collection = Permission.all()
permission_ids = [1, 2, 3, 4, ...]

role.sync_permissions(permission_collection)
# or
role.sync_permissions(permission_ids)
# or
role.sync_permissions([]) # clears all permissions from role

""" Attach permission, this will add new permission into role if already not added
    Arguments:
        permission: Takes permission model object or permission id
"""
permission = Permission.first()

role.attach_permission(permission)
# or
role.attach_permission(1)

""" Detach permission, this will remove permission from role if already added
    Arguments:
        permission: Takes permission model object or permission id
"""
permission = Permission.first()

role.detach_permission(permission)
# or
role.detach_permission(1)

Working with Permission

Creating Permission

""" Creating Permission
    Arguments:
        name: The name of the permission
        slug: The slug of the permission, must be unique
"""
from masonite_permission.models import Permission
permission = Permission.create({
  "name": "Create Post",
  "slug": "create-post" # must be unique
})

Add permissions into roles

""" Add permissions into roles
    Available Methods:
        1. sync_roles: Syncs the roles with the permission
            arguments: Takes a list of role ids or role collection
        2. attach_role: Adds a permission to a role
            arguments: Takes role model object or role id
        3. detach_role: Removes a permission from a role
            arguments: Takes role model object or role id
"""

""" Syncing permissions with role, adds provided roles and removes all other roles
    Arguments:
        roles: Takes a list of role ids or role collection
"""
role_collection = Role.all()
role_ids = [1, 2, 3, 4, ...]

permission.sync_roles(role_collection)
# or
permission.sync_roles(role_ids)
# or
permission.sync_roles([]) # clears all role from permission

""" Attach role, this will add new permission into role if already not added
    Arguments:
        role: Takes role model object or role id
"""
role = Role.first()

permission.attach_role(role)
# or
permission.attach_role(1)

""" Detach role, this will remove permission from role if already added
    Arguments:
        role: Takes role model object or role id
"""
role = Role.first()

permission.detach_role(role)
# or
permission.detach_role(1)

Working with User

user = User.first()

# Add/Remove single role
role = Role.first()

user.assign_role(role) # or you can pass role id
user.revoke_role(role) # or you can pass role id

# add/remove multiple roles
roles = Role.all()

user.sync_roles(roles) # or you can also pass list of ids...
user.sync_roles([]) # clears all roles from user

# check if user has role
user.has_role("role-1") # returns boolean

# check if user has any of the roles
user.has_any_role(["role-1", "role-2"]) # returns boolean

# check if user has all of the roles
user.has_all_roles(["role-1", "role-2"]) # returns boolean

# check if user has permission
user.has_permission("permission-1") # returns boolean

# check if user has any of the permissions
user.has_any_permission(["permission-1", "permission-2"]) # returns boolean

# check if user has all of the permissions
user.has_all_permissions(["permission-1", "permission-2"]) # returns boolean

Using in Template

In case of Roles Checking if user has role.

{% if user.is_("admin") %}
    <p>You are an admin</p>
{% endif %}

Checking if user has any of the roles

{% if user.is_("admin|editor|truck-driver") %}
    <p>You can be either admin, editor, truck driver or all of those</p>
{% endif %}

Checking if user has all of the roles

{% if user.is_("admin,editor,truck-driver") %}
    <p>You are an admin, editor and also truck-driver</p>
{% endif %}

In case of Permissions Checking if user can do {permission}.

{% if user.can_("edit-post") %}
    <p>You can edit post</p>
{% endif %}

Checking if user can do any one or more of the {permissions}

{% if user.can_("edit-post|delete-post") %}
    <p>You can either edit-post, delete-post or both.</p>
{% endif %}

Checking if user can do all of the {permissions}

{% if user.can_("edit-post,delete-post") %}
    <p>You can edit post and also delete post.</p>
{% endif %}

Contributing

Please read the Contributing Documentation here.

Maintainers

• Yubaraj Shrestha

License

Masonite Permission is open-sourced software licensed under the MIT license.