Updated Docs

Author: yubarajshrestha

README.md

@@ -73,12 +73,18 @@ class User(Model, SoftDeletesMixin, Authenticates, HasRoles):
 ## Usage
 
 **Role**
+
 Methods that can be used in role model object:
 
 ```python
+""" Creating Role """
+role = Role.create({
+  "name": "Admin",
+  "slug": "admin" # must be unique
+})
+
 """ collection can be synced """
 permission_collection = Permission.all()
-role = Role.find(1)
 
 role.sync_permissions(permission_collection)
 
@@ -101,12 +107,18 @@ role.detatch_permission(1) # passing permission id instead of object, ignores if
 ```
 
 **Permission**
+
 Methods that can be used in permission model object:
 
 ```python
+""" Creating Permission """
+permission = Permission.create({
+  "name": "Create Post",
+  "slug": "create-post" # must be unique
+})
+
 """ collection can be synced """
 roles_collection = Role.all()
-permission = Permission.find(1)
 
 permission.sync_roles(role_collection)
 
@@ -129,6 +141,7 @@ permission.detatch_role(1) # passing role id instead of object, ignores if role
 ```
 
 **User**
+
 Methods that can be used in user model object:
 
 ```python
@@ -137,8 +150,8 @@ user = User.first()
 # Add/Remove single role
 role = Role.first()
 
-user.attach_role(role) # or you can pass role id
-user.detatch_role(role) # or you can pass role id
+user.assign_role(role) # or you can pass role id
+user.remove_role(role) # or you can pass role id
 
 # if you want to add multiple roles
 roles = Role.all()
@@ -149,14 +162,75 @@ user.sync_roles(roles) # or you can also pass list of ids...
 user.sync_roles([])
 
 # check if user has role
-user.has_role("role-slug") # returns boolean
+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.
+
+```jinja2
+{% if user.is_("admin") %}
+    <p>You are an admin</p>
+{% endif %}
+```
+
+Checking if user has any of the roles
+
+```jinja2
+{% 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
+
+```jinja2
+{% 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}.
+
+```jinja2
+{% if user.can_("edit-post") %}
+    <p>You can edit post</p>
+{% endif %}
+```
+
+Checking if user can do any one or more of the {permissions}
+
+```jinja2
+{% 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}
+
+```jinja2
+{% if user.can_("edit-post,delete-post") %}
+    <p>You can edit post and also delete post.</p>
+{% endif %}
 ```
 
 ## Contributing

setup.py

@@ -8,7 +8,7 @@
     # Versions should comply with PEP440.  For a discussion on single-sourcing
     # the version across setup.py and the project code, see
     # https://packaging.python.org/en/latest/single_source_version.html
-    version="0.1.2",
+    version="0.1.3",
     packages=[
         "masonite_permission",
         "masonite_permission.config",

src/masonite_permission/masonite_permission.py

@@ -0,0 +1,6 @@
+from masonite.configuration import config
+
+
+class MasonitePermission:
+    def __init__(self) -> None:
+        self.conf = config("masonite-permission")

src/masonite_permission/models/has_roles.py

@@ -10,13 +10,14 @@ class HasRoles:
     def roles(self):
         """User can have multiple roles"""
         from ..models.role import Role
+
         return Role
-    
+
     def permissions(self):
         """User can have multiple permissions"""
         from ..models.permission import Permission
-        
-        roles = self.roles.pluck('id')
+
+        roles = self.roles.pluck("id")
         return (
             Permission.join("permission_role as pr", "pr.permission_id", "=", "id")
             .where_in("pr.role_id", roles)
@@ -71,7 +72,7 @@ def sync_roles(self, roles):
         QueryBuilder().table("role_user").where("user_id", self.id).delete()
         self.save_many("roles", roles)
 
-    def attach_role(self, role):
+    def assign_role(self, role):
         """Assign a role to a user
 
         Arguments:
@@ -93,7 +94,7 @@ def attach_role(self, role):
         if not exists:
             self.attach("roles", role)
 
-    def detatch_role(self, role):
+    def remove_role(self, role):
         """Detach a role from a user
 
         Arguments:
@@ -113,4 +114,82 @@ def detatch_role(self, role):
         )
 
         if exists:
-            self.detach("roles", role)
+            self.detach("roles", role)
+
+    def has_permission(self, permission):
+        """Check if user has a permission"""
+        if type(permission) != str:
+            raise PermissionException("permission must be a string!")
+
+        return self.permissions().pluck("slug").contains(permission)
+
+    def has_any_permission(self, permissions):
+        """Check if user has any of the permissions"""
+        from ..models.permission import Permission
+
+        if type(permissions) != Collection and type(permissions) != list:
+            raise PermissionException(
+                "argument must be a collection of permissions or list of permission ids!"
+            )
+
+        if len(permissions) != 0:
+            permission = permissions[0]
+            if isinstance(permission, str):
+                permissions = Permission.where_in("slug", permissions).get().pluck("slug")
+
+        slugs = set(self.permissions().pluck("slug"))
+
+        return len(slugs.intersection(permissions)) > 0
+
+    def has_all_permissions(self, permissions):
+        """Check if user has all of the permissions"""
+
+        if permissions is None or len(permissions) == 0 or type(permissions) != list:
+            raise PermissionException("permissions must be list of permission slugs!")
+
+        slugs = self.permissions().pluck("slug")
+        return set(permissions).issubset(slugs) and len(set(permissions) - set(slugs)) == 0
+
+    def can_(self, permissions):
+        """Check if user has a permission"""
+        if type(permissions) != str:
+            raise PermissionException("permission must be a string!")
+
+        action = "all"  # can be all or any
+
+        # check if permissions contains a comma
+        if "," in permissions:
+            permissions = permissions.split(",")
+        elif "|" in permissions:
+            action = "any"
+            permissions = permissions.split("|")
+        else:
+            permissions = [permissions]
+
+        if action == "all":
+            return self.has_all_permissions(permissions)
+
+        if action == "any":
+            return self.has_any_permission(permissions)
+
+    def is_(self, roles):
+        """Check if user has a role"""
+        if type(roles) != str:
+            raise PermissionException("role must be a string!")
+
+        action = "all"  # can be all or any
+
+        # check if permissions contains a comma
+        if "," in roles:
+            roles = roles.split(",")
+        elif "|" in roles:
+            action = "any"
+            roles = roles.split("|")
+        else:
+            roles = [roles]
+
+        if action == "all":
+            return self.has_all_roles(roles)
+
+        if action == "any":
+            return self.has_any_role(roles)

src/masonite_permission/providers/PermissionGateProvider.py

@@ -0,0 +1,13 @@
+from masonite.providers import Provider
+from masonite.facades import Gate
+
+
+class PermissionGateProvider(Provider):
+    def __init__(self, application):
+        self.application = application
+
+    def register(self):
+        pass
+
+    def boot(self):
+        pass

src/masonite_permission/providers/PermissionProvider.py

@@ -2,6 +2,8 @@
 
 from masonite.packages import PackageProvider
 
+from ..masonite_permission import MasonitePermission
+
 
 class PermissionProvider(PackageProvider):
     def configure(self):

src/masonite_permission/providers/__init__.py

@@ -1,2 +1,3 @@
 # flake8: noqa: E501
 from .PermissionProvider import PermissionProvider
+from .PermissionGateProvider import PermissionGateProvider

tests/integrations/app/controllers/WelcomeController.py

@@ -12,7 +12,9 @@ class WelcomeController(Controller):
     """WelcomeController Controller Class."""
 
     def show(self, view: View):
-        return view.render("welcome")
+        user = User.first()
+
+        return view.render("welcome", {"user": user})
 
     def test(self):
         """users = [{
@@ -84,13 +86,14 @@ def test(self):
 
         Methods:
             user.sync_roles([role])
-            user.attach_role(role)
-            user.detatch_role(role)
+            user.assign_role(role)
+            user.remove_role(role)
             user.has_role(role)
             user.has_any_role(roles)
             user.has_all_roles(roles)
         """
         # role.sync_permissions(Permission.all())
         # return role.permissions
         # user.attach_role(role)
-        return user.permissions().pluck('name')
+        return user.roles
+        return {"result": user.roles}

tests/integrations/config/providers.py

@@ -23,7 +23,7 @@
 from masonite.notification.providers import NotificationProvider
 from masonite.validation.providers import ValidationProvider
 
-from src.masonite_permission.providers import PermissionProvider
+from src.masonite_permission.providers import PermissionProvider, PermissionGateProvider
 
 PROVIDERS = [
     FrameworkProvider,
@@ -47,4 +47,5 @@
     AuthorizationProvider,
     ORMProvider,
     PermissionProvider,
+    PermissionGateProvider,
 ]

tests/integrations/templates/welcome.html

@@ -5,7 +5,15 @@
 <div class="h-screen flex flex-col items-center justify-center">
   <img src="/logo.png" alt="Masonite Logo" class="h-16 w-16 mb-4">
   <div class="text-gray-500 text-5xl mb-10 tracking-wide">
-    Masonite 4
+    Masonite 4 {{ user.can_('create-post,delete-post') }}
+    {% if user.has_role("admin") %}
+    <p>You are an admin</p>
+    {% endif %}
+
+    {% if user.is_("admin") %}
+    <p>You are an admin</p>
+    {% endif %}
+
   </div>
 
   <nav class="flex space-x-4 justify-center text-gray-500 uppercase text-sm">