Download the PHP package amdadulhaq/guard-laravel without Composer

Guard - Modern Role & Permission Management for Laravel

[!IMPORTANT] This package is being renamed to avoid confusion with Laravel's own Guard/Gate terminology. Future development moves to custodian-laravel — same API, new name. New projects should start there; existing projects on guard-laravel keep working and can migrate later.

A powerful, flexible, and developer-friendly role and permission management system for Laravel applications.

Quick Start

Get up and running in 5 minutes:

Upgrading from an older version? Check the Upgrade Guide for detailed migration instructions.

1. Install via Composer

2. Publish and run migrations

3. Setup your User model

4. Create your first role and permission

5. Protect your routes

Features

• Modern PHP & Laravel - Built for PHP 8.2+ and Laravel 11/12/13
• Flexible Permission System - Users can have permissions via roles
• Wildcard Permissions - Use posts.* to match all post-related permissions
• Real-Time Gate Integration - A single Gate::before hook resolves permissions and roles live; native @can, @canany, @cannot support with no stale definitions
• Middleware Protection - role, permission, and role_or_permission middleware
• Blade Directives - @role, @hasrole, @hasanyrole, @hasallroles
• Type-Safe Enums - IDE-friendly PermissionType enum
• Guarded Roles - Guarded roles cannot be deleted; attempts throw GuardedRoleException
• Permission Groups - Organize permissions by resource
• Interactive Commands - Laravel Prompts for creating roles/permissions
• Clean Architecture - Separated concerns with traits and contracts
• Developer Tools - Pint, Pest, Rector, and Larastan included

Support & Sponsorship

Building and maintaining high-quality open-source packages takes hundreds of hours of dedicated time. If you use Guard in your commercial applications or it saves you significant development time, please consider supporting the project.

Sponsor the Project Ensure the package stays actively maintained, receives rapid bug fixes, and continuous feature updates by becoming a monthly sponsor.

Table of Contents

• Installation
• Upgrade Guide
• Configuration
• Usage
  • User Setup
  • Creating Roles
  • Creating Permissions
  • Wildcard Permissions
  • Role Management
  • Permission Management
  • Checking Access
  • Middleware
  • Gate Integration
  • Blade Directives
  • Artisan Commands
  • Query Scopes
• Models Reference
• Exceptions
• Performance
• Database Structure
• Enums
• Development
• Troubleshooting
• FAQ

Installation

Requirements

• PHP: 8.2, 8.3, 8.4, or 8.5
• Laravel: 11.x, 12.x, or 13.x
• Database: MySQL 5.7+, PostgreSQL 9.6+, SQLite 3.8+, or SQL Server 2017+

Step 1: Install via Composer

Step 2: Publish and Run Migrations

This creates 4 tables:

• roles - Role definitions
• permissions - Permission definitions
• permission_role - Role-permission relationships
• role_user - User-role relationships Pivot table names are derived from model table names; the defaults shown above are used unless you customize model tables.

Step 3: Configure User Model

Step 4: (Optional) Publish Config

Configuration

The config/guard.php file:

Custom Models

To extend or replace the default models, point the config at your own classes — all relations, commands, and gate checks resolve them from the config:

Pivot table names are derived automatically from the models' table names.

Usage

User Setup

Add the Roleable contract and trait to your user model:

Notes:

• Roleable trait on the user model handles both role and permission checks.
• Users do not receive permissions directly.
• Assign permissions to roles, then users inherit them from those roles.

Creating Roles

Roles can also be created via the CLI — see Artisan Commands.

Creating Permissions

Authorization only ever checks name — label, description, and group are display metadata for building admin UIs.

Note that getGroup() and byGroup() derive the group from the permission name prefix (users from users.create), not the stored group column, so the resource.action naming convention gives you grouping for free; the column is available for your own custom queries.

Permissions can also be created via the CLI — see Artisan Commands.

Wildcard Permissions

Wildcard permissions automatically match all sub-permissions:

The is_wildcard boolean is automatically set when the name ends with *.

A permission named just * matches every permission — a super-admin grant. Wildcards can be disabled entirely via GUARD_WILDCARD_ENABLED=false.

Role Management

Assigning Roles:

Checking Roles:

Permission Management

Assigning to Roles:

Checking Role Permissions:

Checking User Permissions:

Checking Access

Role Checking:

Permission Checking:

Middleware

All middleware supports multiple values (requires ANY):

Responses: unauthenticated requests receive 401; authenticated users lacking access receive 403 (via PermissionDeniedException). Middleware aliases can be renamed in the middleware section of the config.

Gate Integration

Guard registers a single Gate::before hook that resolves any ability as a permission or role at check time. New roles and permissions are usable immediately — no cache to clear, no gates to re-register. When the ability is not granted by Guard, the hook returns null, so your own Gate::define gates and policies still run as normal:

Blade Directives

Guard provides custom Blade directives for role checking, in addition to Laravel's built-in @can directives. All directives render nothing for guests — no need to wrap them in @auth:

Custom Role Directives:

Built-in Laravel Directives (via Gate integration):

Artisan Commands

Create a Role:

Create a Permission:

Both commands support Laravel Prompts when optional assignment arguments are omitted.

• guard:create-role prompts for an optional user identifier and accepts a user ID, email, or name.
• guard:create-permission prompts for an optional role identifier and accepts a role ID or role name.

Upgrade helper:

Rewrites your application code from older Guard versions to the current architecture — updates v1/v2 trait and contract usage in app/Models, removes API calls deleted in v3, cleans the published config, and publishes any pending schema upgrade migrations. See the Upgrade Guide for details.

Query Scopes

Models Reference

Exceptions

Role and permission mutators (assignRole, givePermissionTo, syncRoles, revokeRole, ...) throw Illuminate\Database\Eloquent\ModelNotFoundException when a name does not resolve to an existing model — typos fail loudly instead of silently doing nothing.

Performance

Permission checks are memoized per model instance, so repeated hasPermission() calls within a request hit the database once. Role checks use the loaded roles relation, which Guard refreshes automatically after any role mutation.

Database Structure

Enums

PermissionType

Development

Code Quality Tools

Troubleshooting

Common Issues

Performance Tips

1. Use wildcard permissions to reduce permission count

2. Filter at database level instead of loading all users:

3. Eager load when needed:

FAQ

Contributing

We welcome contributions! Please see CONTRIBUTING for details.

Changelog

See CHANGELOG for recent changes.

Security

Please review our security policy for reporting vulnerabilities.

Star History

If Guard helps you, a star helps the project grow.

Credits

License

The MIT License (MIT). See License File for details.

Made with ❤️ for the Laravel community