Download the PHP package edulazaro/larallow without Composer

Larallow for Laravel: A package to handle roles and permissions

Larallow is a flexible Laravel package for managing roles and permissions with advanced features including scoped roles and permissions, polymorphic relations, translation support, and seamless integration with PHP enums for permissions. Zero configuration required.

Why this package when Spatie Permissions exists?

Spatie Permissions is a great package. However it stores permissions in the database by default and does not handle well scopes or permissions for different actors, also requiring to specify the guard for each permission. It's all about your preferences and project requirements.

Features

• Manage roles and permissions for any actor model (User, Client, etc.)
• Support for scoped roles via polymorphic roleable models (e.g., specific projects, teams)
• Support for scoped permissions via polymorphic permissionable models (e.g., specific resources)
• Define permissions with a fluent API in a similar way you define Laravel routes
• Fluent querying and checking with Permissions and Roles helper classes
• Built-in translation support for role names without external packages
• Permission hierarchy (implications)

Installation

Add the package via Composer:

Publish migrations and run them:

Quick Start

1. Add traits to your model

2. Define permissions (in a service provider)

3. Assign and check permissions

4. Work with roles

Tenants and scopes

These two get mixed up more than anything else here, and it is worth two minutes because the answer also explains why only roles take a tenant.

Permissions are application level. edit-post is part of your application's vocabulary, declared in code and the same for everyone: there is no permissions table and nobody owns one. So a permission has no tenant. It has a scope, which is the element it applies to.

Roles are rows a tenant creates. A role is a name and a set of permissions, stored in the database, and one customer's "Editor" can be a different row from another customer's "Editor" with different permissions inside. That is something to own, so it takes a tenant.

So the asymmetry is not an omission. A permission has nothing to own; a role does.

Which one does my case need

Same role everywhere, granted per place → scope. A user belongs to several companies and holds a different role in each:

There is one manager row and it means the same thing everywhere. Only the grants differ. Permissions work the same way, and this is how a permission gets confined to a customer:

Each customer writing its own roles → tenant. Acme wants roles with names and permissions that mean nothing to Globex:

Both companies can now have a manager role and they are separate definitions: the unique index is on the handle plus the tenant, so handles are free to repeat.

The tables say the same thing. The tenant sits on the definition and on nothing else:

roles                tenant + scope       the definition
actor_role                    scope       a grant
actor_permissions             scope       a grant

Neither grant table carries a tenant. actor_role does not need one, because it already points at the role and the role knows whose it is.

One question settles it: delete the tenant and a role definition disappears; delete the scope and only that one grant disappears.

You will often need neither. Start without them and add the one the question points at.

Setup

Actor Traits

Add the HasPermissions and HasRoles traits to your actor models (User, Client, etc.):

You can use only one trait if you don't need both features.

Role Tenant Trait

For models that own roles (e.g., Account, Group, Organization), add the IsRoleTenant trait:

This allows you to retrieve roles belonging to that tenant:

Morph Maps (Recommended)

For consistent and secure morph relationships, define all models in your morph map:

This is optional but heavily recommended, especially when dealing with multiple actor types or scopes.

Permissions

Defining Permissions

Register permissions using Permission::create() in a service provider:

For specific actor types

Use for() to restrict permissions to specific actor models:

For specific scopes

Use on() to restrict permissions to specific scope models (e.g., Office, Group):

Grouping permissions

Define multiple permissions with shared configuration:

Permission implications (hierarchy)

Define permission hierarchies where higher-level permissions imply lower-level ones:

Using enums

Translating permission labels

Or for easier text management you can use Laratext package:

Assigning Permissions

Assign permissions directly to actors:

With scope

Alternative syntax

Removing Permissions

Syncing Permissions

Sync permissions to match a given list (adds missing, removes others):

Checking Permissions

Direct permissions only

Check if user has a permission directly assigned (not via roles):

You can also retrieve the list of permissions directly assigned to an actor:

Combined (direct + role-based)

Check if user has permission either directly or via a role:

Check any vs all

Blade directives

Roles

Creating Roles

Assigning Roles

With tenant (multi-tenancy)

Removing Roles

Syncing Roles

Sync roles to match a given list:

Checking Roles

You can also retrieve the roles assigned to an actor:

Check any vs all

Blade directives

Role Permissions

Add permissions to roles:

Remove permissions from roles:

You can also use the relationship directly:

Checking Role Permissions

Check if user has permissions through their roles (ignoring direct permissions):

Query Scopes

Filter actors by their permissions:

These scopes automatically include implied permissions.

Advanced

Permission Query Builder

Query registered permissions:

Filtering permissions

Multi-tenancy

The tenant() method scopes role operations to a specific tenant:

During assignment, an InvalidArgumentException is thrown if any role does not belong to the specified tenant.

Deleting Roles

Make sure to detach any assignments or permissions related to this role before deleting to maintain data integrity.

Translation Support

Roles support multilingual translations without external packages:

Testing

Run the package tests with:

Contributing

Contributions are welcome! Please fork the repo, add tests, and submit a PR.

License

Larallow is open-sourced software licensed under the MIT license.