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

💡 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
• ✅ Multilingual - Spanish and Galician translations included

📋 Requirements

🚀 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

// In config/app.php, add to the return array:
return [
    // ... existing configuration ...

    'AclManager' => [
        'adminAccess' => [
            // Which role IDs can access the Authorization Manager
            'adminRoleIds' => [1, 2],  // Allow role IDs 1 and 2

            // Which role names can access
            'adminRoleNames' => ['admin', 'superuser'],

            // Specific emails (useful for initial setup)
            'adminEmails' => [
                'admin@example.com',
            ],
        ],
        'redirects' => [
            'login' => ['controller' => 'Users', 'action' => 'login'],
            'unauthorized' => ['controller' => 'Dashboard', 'action' => 'index'],
        ],
    ],
];

// In your UsersController login action, after successful authentication:
public function login()
{
    $result = $this->Authentication->getResult();

    if ($result->isValid()) {
        // Check if there's a redirect parameter
        $redirect = $this->request->getQuery('redirect');

        if ($redirect) {
            // Redirect back to the original URL
            return $this->redirect($redirect);
        }

        // Default redirect
        $target = $this->Authentication->getLoginRedirect() ?? '/dashboard';
        return $this->redirect($target);
    }

    if ($this->request->is('post') && !$result->isValid()) {
        $this->Flash->error(__('Invalid username or password'));
    }
}

use Cake\I18n\I18n;

// Set Spanish (default)
I18n::setLocale('es_ES');

// Or Galician
I18n::setLocale('gl_ES');

// Or English
I18n::setLocale('en_US');

use Cake\Core\Configure;

// 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);

🛠️ Cambios recientes (Unreleased)

Pequeño resumen de cambios detectados el 2025-12-02:

• Se ha añadido Utilities/* a ignoreActions para excluir utilidades del escaneo de recursos.
• AuthorizationManagerComponent ahora utiliza 'App' como valor por defecto para el parámetro plugin cuando no está presente.
• PermissionsTable y ResourcesTable: tipos de columna boolean correctamente definidos (allowed, active).
• ResourceScannerService::getGroupedResources() filtra plugins, controladores y acciones según ignoreActions antes de devolver los recursos agrupados.
• Plantillas de permisos (templates/Permissions/*) integran adminRoleIds para evitar que roles administrativos sean eliminados desde la UI; el enlace "Clear All" ahora invoca la acción clearPermissions y el campo oculto plugin mantiene su valor real.
• Archivos de traducción: limpieza de cadenas (ej. eliminación de la cadena "Deny").
• Nueva política src/Policy/AclManagerPolicy.php que delega en PermissionService.
• Se añadió la clase CSS .disabled-link en templates/layout/default.php para estilos de enlaces inactivos.

Nota: Se han detectado archivos en la carpeta .snapshots/. Estos archivos suelen ser generados por herramientas locales y no deberían comitearse. Se han eliminado del repositorio y añadida una entrada en .gitignore para evitar futuros commits accidentales.

🗄️ 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

1. 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              │
      └───────────────────────────┘
```text

---

## 🤝 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](LICENSE.md) for details.

```text
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