README

Manage authorization with granular role-based permissions in your Laravel apps.

Table of Contents

• Goal
• Requirements
• Installation
• Implementation
• Upgrading
• Configuration
• API Reference
  • Traits
  • Policies
  • Models
  • Artisan Commands
  • REST API Endpoints
  • Events
  • Blade Components
• Examples

Goal

Provide a simple method of managing ACL in a Laravel application built on the Laravel Authorization functionality. By leveraging Laravel's native Authorization functionality there is no additional learning or implementation curve. All you need to know is Laravel, and you will know how to use Governor for Laravel.

Requirements

Additional Requirements

• Bootstrap 3 (needs to be included in your layout file)
• FontAwesome 4 (needs to be included in your layout file)

Installation

The user with the lowest primary key will be set up as the SuperAdmin. If you're starting on a new project, be sure to add an initial user now. If you already have users, you can update the role-user entry to point to your intended user, if the first user is not the intended SuperAdmin. Now let's get the package installed.

Install via composer:

composer require genealabs/laravel-governor

Implementation

1. First we need to update the database by running the migrations and data seeders:

   php artisan migrate --path="vendor/genealabs/laravel-governor/database/migrations"
   php artisan db:seed --class=LaravelGovernorDatabaseSeeder

2. If you have seeders of your own, run them now:

   php artisan db:seed

3. Next, assign permissions (this requires you have users already populated):

   php artisan db:seed --class=LaravelGovernorPermissionsTableSeeder

4. Now we need to make the assets available:

   php artisan governor:publish --assets

5. Lastly, add the Governing trait to the User model of your app:

   use GeneaLabs\LaravelGovernor\Traits\Governing;
   
   class User extends Authenticatable
   {
       use Governing;
   }

   For non-User models that should be governed (have ownership tracking and permission-scoped queries), use the Governable trait instead:

   use GeneaLabs\LaravelGovernor\Traits\Governable;
   
   class BlogPost extends Model
   {
       use Governable;
   }

Upgrading

The following upgrade guides should help navigate updates with breaking changes.

From 0.11.5+ to 0.12 [Breaking]

The role_user pivot table has replaced the composite key with a primary key, as Laravel does not fully support composite keys. Run:

php artisan db:seed --class="LaravelGovernorUpgradeTo0120"

From 0.11 to 0.11.5 [Breaking]

The primary keys of the package's tables have been renamed. (This should have been a minor version change, instead of a patch, as this was a breaking change.) Run:

php artisan db:seed --class="LaravelGovernorUpgradeTo0115"

From 0.10 to 0.11 [Breaking]

The following traits have changed:

• Governable has been renamed to Governing.
• Governed has been renamed to Governable.
• the governor_created_by has been renamed to governor_owned_by. Run migrations to update your tables.

  php artisan db:seed --class="LaravelGovernorUpgradeTo0110"

• replace any reference in your app from governor_created_by to governor_owned_by.

From 0.6 to Version 0.10 [Breaking]

To upgrade from version previous to 0.10.0, first run the migrations and seeders, then run the update seeder:

php artisan migrate --path="vendor/genealabs/laravel-governor/database/migrations"
php artisan db:seed --class="LaravelGovernorDatabaseSeeder"
php artisan db:seed --class="LaravelGovernorUpgradeTo0100"

to 0.6 [Breaking]

1. If you were extending GeneaLabs\LaravelGovernor\Policies\LaravelGovernorPolicy, change to extend GeneaLabs\LaravelGovernor\Policies\BasePolicy;
2. Support for version of Laravel lower than 5.5 has been dropped.

Configuration

Publish the configuration file if you need to customize defaults:

php artisan governor:publish --config

Config Options

Caching

Governor can cache lookup table queries across requests to reduce database load. This is disabled by default.

To enable caching, publish the config file and update the cache section:

'cache' => [
    'enabled' => true,
    'ttl' => 3600, // seconds, or null for "forever"
],

Cache is automatically invalidated when any lookup table model (Action, Entity, Ownership, Permission, Role) is created, updated, or deleted. Invalidation is coarse-grained: a change to any single lookup table flushes the cache for all lookup tables. This keeps the invalidation logic simple and reliable, which is appropriate given that lookup tables change infrequently.

Views

If you would like to customize the views, publish them:

php artisan governor:publish --views

and edit them in resources/views/vendor/genealabs-laravel-governor.

Tables

Tables will automatically be updated with a governor_owned_by column that references the user that created the entry. There is no more need to run separate migrations or work around packages that have models without a created_by property.

Admin Views

The easiest way to integrate Governor into your app is to add menu items to the relevant section of your app's menu (restrict access using Laravel Authorization methods). The following named routes are available:

• Role Management: genealabs.laravel-governor.roles.index
• User-Role Assignments: genealabs.laravel-governor.assignments.index
• Teams: genealabs.laravel-governor.teams.index
• Groups: genealabs.laravel-governor.groups.index

For example:

<li><a href="{{ route('genealabs.laravel-governor.roles.index') }}">Governor</a></li>

403 Unauthorized

We recommend making a custom 403 error page to let the user know they don't have access. Otherwise the user will just see the default error message. See https://laravel.com/docs/errors#custom-http-error-pages for more details on how to set those up.

API Reference

Traits

Governor provides two traits for your Eloquent models. Use Governing on your User model (it includes Governable automatically). Use Governable on any other model that should be governed.

Governing Trait

Namespace: GeneaLabs\LaravelGovernor\Traits\Governing Use on: Your User model

This trait adds role management, team membership, and permission resolution to the User model. It includes the Governable trait, so you do not need to add both.

hasRole(string $name): bool

Check whether the user has a specific role.

• Parameters: $name — the role name (e.g. 'SuperAdmin', 'Member')
• Returns: true if the user has the given role or is a SuperAdmin

if ($user->hasRole('Editor')) {
    // user has the Editor role
}

roles(): BelongsToMany

Eloquent relationship to the user's assigned roles.

• Returns: BelongsToMany relationship to Role via governor_role_user

$roleNames = $user->roles->pluck('name'); // ['SuperAdmin', 'Member']

ownedTeams(): HasMany

Eloquent relationship to teams owned by this user.

• Returns: HasMany relationship to Team where governor_owned_by matches the user

$myTeams = $user->ownedTeams;

teams(): BelongsToMany

Eloquent relationship to teams the user is a member of.

• Returns: BelongsToMany relationship to Team via governor_team_user

$teamNames = $user->teams->pluck('name');

permissions (Accessor)

All permissions associated with the user's roles.

• Returns: Collection of Permission models

$permissions = $user->permissions;

effectivePermissions (Accessor)

Deduplicated permissions across all roles, collapsed to the highest ownership level per entity/action pair. If any role grants "any" ownership, the effective permission is "any"; if the best is "own", it returns "own".

• Returns: Collection of Permission models with role_name and team_name set to null

$effective = $user->effectivePermissions;

Governable Trait

Namespace: GeneaLabs\LaravelGovernor\Traits\Governable Use on: Any Eloquent model that should have ownership tracking and permission-scoped queries

ownedBy(): BelongsTo

Eloquent relationship to the user who owns this model.

• Returns: BelongsTo relationship to the auth model via governor_owned_by

$owner = $blogPost->ownedBy;

teams(): MorphToMany

Eloquent polymorphic relationship to teams associated with this model.

• Returns: MorphToMany relationship to Team via governor_teamables

$teams = $blogPost->teams;

Query Scopes

All scopes filter query results based on the authenticated user's permissions. If the user has "any" ownership for the relevant action, the query is unmodified. If the user has "own" ownership, results are limited to records they own or belong to their teams. If neither, the query returns no results.

These scopes can be applied directly to any query builder instance, making them useful in Nova or other admin panels:

Nova example:

use Laravel\Nova\Resource as NovaResource;
use Laravel\Nova\Http\Requests\NovaRequest;

abstract class Resource extends NovaResource
{
    public static function indexQuery(NovaRequest $request, $query)
    {
        return $query->viewAnyable();
    }
}

Policies

BasePolicy

Namespace: GeneaLabs\LaravelGovernor\Policies\BasePolicy

All Governor policies must extend this class. It provides automatic permission checking for standard Laravel policy methods. Policies are auto-detected from your app/Policies directory (and any paths configured via policy_paths in config) — you do not need to register them manually.

Default Policy Methods

These methods are implemented automatically. Override them only if you need custom behavior:

SuperAdmins bypass all permission checks and always return true.

Guest users (unauthenticated) are assigned the Guest role if it exists.

Custom Policy Actions

You can define custom actions beyond the standard CRUD operations by adding public methods to your policy class. Governor automatically detects any public methods that are not inherited from BasePolicy and registers them as custom actions in the permissions system.

class BlogPostPolicy extends BasePolicy
{
    public function publish(?Model $user, Model $model): bool
    {
        return $this->authorizeCustomAction($user, $model);
    }

    public function archive(?Model $user, Model $model): bool
    {
        return $this->authorizeCustomAction($user, $model);
    }
}

Custom actions are registered with names in the format App\Models\BlogPost:publish and appear in the role permission editor.

To check custom actions in your application:

$user->can('publish', $blogPost);

Creating a Policy

Create a policy class that extends BasePolicy. That's it — no methods are required for the default CRUD actions to work:

<?php

namespace App\Policies;

use GeneaLabs\LaravelGovernor\Policies\BasePolicy;

class BlogPostPolicy extends BasePolicy
{
    // All standard CRUD permissions are handled automatically.
    // Add custom methods only for non-standard actions.
}

Checking authorization uses standard Laravel authorization:

// In controllers
$this->authorize('update', $blogPost);

// In Blade templates
@can('delete', $blogPost)
    <button>Delete</button>
@endcan

// Directly on the user
$user->can('create', App\Models\BlogPost::class);
$user->can('update', $blogPost);

Models

Governor ships with the following Eloquent models. All can be swapped via the models config key.

Role

Table: governor_roles Primary Key: name (string, non-incrementing)

Relationships:

• permissions(): HasMany — permissions assigned to this role
• users(): BelongsToMany — users assigned to this role

Team

Table: governor_teams

Relationships:

• members(): BelongsToMany — team members (custom relation that prevents detaching the owner)
• invitations(): HasMany — pending team invitations
• permissions(): HasMany — team-level permissions
• ownedBy(): BelongsTo — the user who owns the team
• teams(): MorphToMany — parent teams (polymorphic)

Permission

Table: governor_permissions

Relationships:

• role(): BelongsTo — the associated role
• team(): BelongsTo — the associated team (if team-level)

Entity

Table: governor_entities Primary Key: name (string, non-incrementing)

Entities represent governed model types. They are auto-created when policies are detected.

Relationships:

• group(): BelongsTo — optional entity group
• permissions(): HasMany — permissions for this entity

Methods:

• displayName(): string — returns the entity alias (from config) or the raw name

Action

Table: governor_actions Primary Key: name (string, non-incrementing)

Standard actions (create, update, view, viewAny, delete, restore, forceDelete) are seeded automatically. Custom actions are registered when policies define additional public methods.

Ownership

Table: governor_ownerships Primary Key: name (string, non-incrementing)

Ownership levels control the scope of a permission: no (denied), own (only records owned by the user or their team), any (all records).

Group

Table: governor_groups Primary Key: name (string, non-incrementing)

Groups organize entities in the permission editor UI.

Artisan Commands

governor:publish

Publish package assets, config, views, or migrations.

php artisan governor:publish --assets    # Publish frontend assets
php artisan governor:publish --config    # Publish config file
php artisan governor:publish --views     # Publish Blade views
php artisan governor:publish --migrations # Publish migration files

Flags can be combined:

php artisan governor:publish --config --views

governor:setup

Assign the SuperAdmin role to an existing user. Requires either --superadmin (email) or --user (ID).

php artisan governor:setup --superadmin=admin@example.com
php artisan governor:setup --user=1

The command will fail if:

• Neither option is provided
• Both options are provided
• The user does not exist
• The SuperAdmin role has not been seeded yet

REST API Endpoints

Governor provides two JSON API endpoints, prefixed with api + your configured url-prefix. These require the auth:api middleware (e.g. Laravel Passport or Sanctum).

Check User Ability

Route: GET /api/{url-prefix}/user-can/{ability} Route Name: genealabs.laravel-governor.api.user-can.show

Check if the authenticated user can perform a given action on a model.

// Can the user create a Role?
GET /api/genealabs/laravel-governor/user-can/create?model=GeneaLabs\LaravelGovernor\Role

// Can the user update Role with primary key 1?
GET /api/genealabs/laravel-governor/user-can/update?model=GeneaLabs\LaravelGovernor\Role&primary-key=1

Response: 200 OK with {"can": true} or {"can": false}

Check User Role

Route: GET /api/{url-prefix}/user-is/{role} Route Name: genealabs.laravel-governor.api.user-is.show

Check if the authenticated user has a specific role.

GET /api/genealabs/laravel-governor/user-is/SuperAdmin

Response: 200 OK with {"is": true} or {"is": false}

Web Routes

Governor registers the following resourceful web routes under the configured url-prefix, all using the web middleware group:

Events

Governor hooks into Eloquent model events to automate ownership tracking and cache invalidation.

Ownership Tracking Events

Team Events

Cache Invalidation

Blade Components

<x-governor-menu-bar />

Renders a navigation bar component for Governor's admin interface. Include it in your layout to provide navigation between roles, assignments, teams, and groups.

<x-governor-menu-bar />

Examples

Config File

<?php

return [
    'layout-view' => 'layouts.app',
    'content-section' => 'content',
    'auth-model-primary-key-type' => 'bigInteger',
    'models' => [
        'auth' => config('auth.providers.users.model') ?? config('auth.model'),
        'action' => GeneaLabs\LaravelGovernor\Action::class,
        'assignment' => GeneaLabs\LaravelGovernor\Assignment::class,
        'entity' => GeneaLabs\LaravelGovernor\Entity::class,
        'group' => GeneaLabs\LaravelGovernor\Group::class,
        'ownership' => GeneaLabs\LaravelGovernor\Ownership::class,
        'permission' => GeneaLabs\LaravelGovernor\Permission::class,
        'role' => GeneaLabs\LaravelGovernor\Role::class,
        'team' => GeneaLabs\LaravelGovernor\Team::class,
        'invitation' => GeneaLabs\LaravelGovernor\TeamInvitation::class,
    ],
    'user-name-property' => 'name',
    'url-prefix' => '/genealabs/laravel-governor/',
    'superadmins' => env('GOVERNOR_SUPERADMINS'),
    'admins' => env('GOVERNOR_ADMINS'),
    'entity-aliases' => [],
    'cache' => [
        'enabled' => false,
        'ttl' => 3600,
    ],
];

Complete Policy with Custom Actions

<?php

namespace App\Policies;

use GeneaLabs\LaravelGovernor\Policies\BasePolicy;
use Illuminate\Database\Eloquent\Model;

class BlogPostPolicy extends BasePolicy
{
    // Standard CRUD actions are inherited automatically.

    // Custom action: publish
    public function publish(?Model $user, Model $model): bool
    {
        return $this->authorizeCustomAction($user, $model);
    }

    // Custom action: archive
    public function archive(?Model $user, Model $model): bool
    {
        return $this->authorizeCustomAction($user, $model);
    }
}

Using Permission Scopes

// Get only blog posts the user can view
$posts = BlogPost::viewable()->paginate(15);

// Get only blog posts the user can edit
$editable = BlogPost::updatable()->get();

// Get only blog posts the user can delete
$deletable = BlogPost::deletable()->get();

Checking Roles and Permissions

// Check if user has a specific role
if ($user->hasRole('Editor')) {
    // ...
}

// Check policy authorization (standard Laravel)
if ($user->can('update', $blogPost)) {
    // ...
}

// Check custom action
if ($user->can('publish', $blogPost)) {
    // ...
}

// Get all effective permissions for a user
$permissions = $user->effectivePermissions;

Team Management

// Get user's teams
$teams = $user->teams;

// Get teams owned by the user
$ownedTeams = $user->ownedTeams;

// Get team members
$members = $team->members;

// Transfer team ownership (via web route)
POST /genealabs/laravel-governor/teams/{team}/transfer-ownership