mgomezbuceta/cakephp-aclmanager

Modern Authorization Manager for CakePHP 5.x - Role-based permission management system

v3.0.8 2025-10-09 16:22 UTC

Requires

• php: >=8.1
• cakephp/authorization: ^3.0
• cakephp/cakephp: ^5.0

Requires (Dev)

• cakephp/cakephp-codesniffer: ^5.0
• phpunit/phpunit: ^10.0

MIT

• Marcos Gómez Buceta
• Ivan Amat

• authorization
• plugin
• manager
• cakephp
• roles
• permissions
• rbac
• cake5
• cakephp5

README

🔐 CakePHP Authorization Manager

Modern Role-Based Permission Management for CakePHP 5.x

A powerful, modern web interface for managing role-based permissions using CakePHP's Authorization plugin.

Features • Installation • Quick Start • Documentation • Migration

🌟 Features

🎯 Role-Based Access Control Simple yet powerful RBAC system with role priorities and hierarchical permission management. 🔄 Auto-Discovery Automatically scans your application for controllers and actions—no manual configuration needed. 🎨 Modern UI Beautiful Bootstrap 5 interface with intuitive permission matrices and visual role management.

⚡ High Performance Built on CakePHP's Authorization plugin with permission caching for optimal performance. 🛡️ Secure by Default Strict permission checking mode with comprehensive authorization middleware integration. 🚀 CakePHP 5.x Native Fully compatible with CakePHP 5.x using modern Authorization instead of deprecated ACL.

💡 Why Authorization Manager?

Traditional ACL systems (acos/aros) are deprecated in CakePHP 5.x. This plugin provides:

• ✅ Modern Authorization - Uses CakePHP's official Authorization plugin
• ✅ Simplified Structure - No more complex ACO/ARO trees
• ✅ Visual Management - Web interface for managing permissions
• ✅ Role-Based - Industry-standard RBAC pattern
• ✅ Easy Integration - Drop-in authorization solution

📋 Requirements

Requirement	Version
PHP	≥ 8.1
CakePHP	≥ 5.0
CakePHP Authorization	≥ 3.0

🚀 Installation

Step 1: Install via Composer

composer require mgomezbuceta/cakephp-aclmanager
composer require cakephp/authorization

Step 2: Load the Plugin

Add to your src/Application.php:

public function bootstrap(): void
{
    parent::bootstrap();

    $this->addPlugin('AclManager', ['bootstrap' => true, 'routes' => true]);
}

Step 3: Run Migrations

bin/cake migrations migrate -p AclManager

Step 4: Sync Resources

Visit /authorization-manager and click "Sync Resources" to discover all your controllers and actions.

That's it! 🎉

⚡ Quick Start

Basic Setup

1. Create Roles

   • Visit /authorization-manager/roles
   • Click "New Role"
   • Create roles like: Administrator, Editor, Viewer

2. Assign Permissions

   • Click "Manage Permissions" for a role
   • Check/uncheck permissions for each controller/action
   • Click "Save Permissions"

3. Integrate with Your Auth

// In your AppController or specific controller
public function initialize(): void
{
    parent::initialize();

    $this->loadComponent('AclManager.AuthorizationManager', [
        'userModel' => 'Users',
        'roleField' => 'role_id'
    ]);
}

public function isAuthorized($user = null): bool
{
    return $this->AuthorizationManager->isAuthorized($user);
}

Add role_id to Your Users Table

ALTER TABLE users ADD COLUMN role_id INT NOT NULL;
ALTER TABLE users ADD FOREIGN KEY (role_id) REFERENCES roles(id);

📚 Documentation

🔧 Configuration Options

In your config/bootstrap.php:

use Cake\Core\Configure;

// Enable admin prefix
Configure::write('AclManager.admin', true);

// Actions to ignore during resource scan
Configure::write('AclManager.ignoreActions', [
    'isAuthorized',
    'beforeFilter',
    'initialize',
    'AclManager.*',      // Ignore plugin
    'DebugKit.*'         // Ignore DebugKit
]);

// Permission checking mode
Configure::write('AclManager.permissionMode', 'strict'); // or 'permissive'

// Enable permission caching
Configure::write('AclManager.cachePermissions', true);
Configure::write('AclManager.cacheDuration', '+1 hour');

// Default role for new users
Configure::write('AclManager.defaultRoleId', 2);

🗄️ Database Schema

The plugin creates three tables:

roles - User roles

id, name, description, priority, active, created, modified

permissions - Role permissions

id, role_id, controller, action, plugin, allowed, created, modified

resources - Available resources (auto-discovered)

id, controller, action, plugin, description, active, created, modified

🔌 Component Usage

// Load the component
$this->loadComponent('AclManager.AuthorizationManager');

// Check if user is authorized
$allowed = $this->AuthorizationManager->isAuthorized($user);

// Check specific permission
$allowed = $this->AuthorizationManager->checkPermission(
    $roleId,
    'Articles',
    'edit',
    'Blog' // plugin name (optional)
);

// Clear permission cache
$this->AuthorizationManager->clearCache();

// Handle unauthorized access
return $this->AuthorizationManager->handleUnauthorized();

🎯 Service Layer

use AclManager\Service\PermissionService;
use AclManager\Service\ResourceScannerService;

// Permission management
$permissionService = new PermissionService();

// Grant permission
$permissionService->grant($roleId, 'Articles', 'edit');

// Deny permission
$permissionService->deny($roleId, 'Articles', 'delete');

// Get permission matrix
$matrix = $permissionService->getPermissionMatrix($roleId);

// Copy permissions between roles
$permissionService->copyPermissions($sourceRoleId, $targetRoleId);

// Resource scanning
$scannerService = new ResourceScannerService();
$stats = $scannerService->scanAndSync();

// Get grouped resources
$resources = $scannerService->getGroupedResources();

🐛 Troubleshooting

No resources showing?

Visit /authorization-manager and click "Sync Resources"

Permission changes not taking effect?

// Clear cache
Configure::write('AclManager.cachePermissions', false);
// Or clear specific cache
$this->AuthorizationManager->clearCache();

Getting "access denied" after setup?

1. Make sure your User has a role_id assigned
2. Verify permissions are granted for that role
3. Check isAuthorized() is properly implemented

🔄 Migration from v2.x

⚠️ BREAKING CHANGE: Version 3.0 uses Authorization plugin instead of deprecated ACL.

Migration Steps:

1. Backup your data

CREATE TABLE backup_aros_acos AS SELECT * FROM aros_acos;

1. Update composer.json

composer remove cakephp/acl
composer require cakephp/authorization
composer update mgomezbuceta/cakephp-aclmanager

1. Run new migrations

bin/cake migrations migrate -p AclManager

1. Update routes

   • Old: /acl-manager
   • New: /authorization-manager

2. Update component

// Old
$this->loadComponent('AclManager.AclManager');

// New
$this->loadComponent('AclManager.AuthorizationManager');

1. Rebuild permissions
   • Create new roles matching your old ARO structure
   • Use "Sync Resources" to discover controllers
   • Manually assign permissions (old ACL data cannot be migrated)

🏗️ Architecture

┌─────────────────────────────────────────┐
│      PermissionsController               │
│      (Web Interface)                     │
└──────────────┬──────────────────────────┘
               │
      ┌────────┴────────┐
      │                 │
┌─────▼──────────┐ ┌───▼──────────────────┐
│ Permission     │ │ ResourceScanner      │
│ Service        │ │ Service              │
│                │ │                      │
│ • Check Auth   │ │ • Scan Controllers   │
│ • Grant/Deny   │ │ • Sync Resources     │
│ • Copy Perms   │ │ • Auto-Discovery     │
└────────────────┘ └──────────────────────┘
        │                     │
        └──────────┬──────────┘
                   │
      ┌────────────▼─────────────┐
      │  Database Tables          │
      │  • roles                  │
      │  • permissions            │
      │  • resources              │
      └───────────────────────────┘

🤝 Contributing

Contributions are welcome!

1. 🍴 Fork the repository
2. 🌿 Create your feature branch (git checkout -b feature/amazing-feature)
3. 💻 Write clean, documented code following PSR-12
4. ✅ Add tests for new functionality
5. 📝 Commit your changes (git commit -m 'Add amazing feature')
6. 🚀 Push to the branch (git push origin feature/amazing-feature)
7. 🎉 Open a Pull Request

📄 License

This project is licensed under the MIT License - see LICENSE.md for details.

Copyright (c) 2025 Marcos Gómez Buceta
Copyright (c) 2016 Iván Amat

👨‍💻 Author

Marcos Gómez Buceta

🙏 Acknowledgments

This project evolved from the excellent ACL Manager foundation:

• Iván Amat - Original CakePHP 4.x Acl Manager
• Frédéric Massart (FMCorz) - Original CakePHP 2.x AclManager

Special thanks to the CakePHP community for their continuous support.

⭐ If you find this plugin useful, please give it a star! ⭐

Made with ❤️ for the CakePHP community

Report Bug • Request Feature