Acl Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require nuxia/acl-bundle  # Updated repo per README
   

   Add to config/bundles.php:

   return [
       // ...
       Nuxia\AclBundle\NuxiaAclBundle::class => ['all' => true],
   ];
   

2. Database Setup: Run migrations (if using Doctrine):

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. First Use Case: Define a role and permission in a controller:

   use Nuxia\AclBundle\Security\Acl\Permission\PermissionMap;
   use Nuxia\AclBundle\Security\Acl\Permission\Permission;
   
   // Grant a role a permission
   $permissionMap = $this->get('nuxia_acl.permission_map');
   $permission = $permissionMap->getPermission('entity', 'edit');
   $role = $this->get('security.role_hierarchy')->getReachableRole('ROLE_ADMIN');
   $permissionMap->grant($role, $permission);
   

Implementation Patterns

Workflows

1. Role-Based Access Control (RBAC):

   • Use RoleHierarchy to define role inheritance (e.g., ROLE_ADMIN inherits ROLE_USER).
   • Example:

     # config/security.yaml
     security:
         role_hierarchy:
             ROLE_ADMIN: [ROLE_USER, ROLE_EDITOR]
     

2. Permission Management:

   • Define permissions in a PermissionMap service (e.g., entity.create, entity.edit).
   • Dynamically grant/revoke permissions:

     $permissionMap->grant($role, $permission);
     $permissionMap->revoke($role, $permission);
     

3. Integration with Symfony Security:

   • Use voters to enforce ACL checks:

     use Nuxia\AclBundle\Security\Voter\AclVoter;
     
     class EntityVoter extends AclVoter {
         protected function supportsAttribute($attribute) {
             return $attribute === 'EDIT';
         }
     }
     

   • Register in security.yaml:

     security:
         access_control:
             - { path: ^/admin, roles: ROLE_ADMIN, permissions: [EDIT] }
     

4. Entity-Level Permissions:

   • Attach permissions to specific entities (e.g., a Post with PUBLISH permission):

     $aclProvider = $this->get('nuxia_acl.acl_provider');
     $acl = $aclProvider->createAcl($entity);
     $acl->insertObjectAce($entity, 'OWNER', 'GRANT', 'EDIT');
     $aclProvider->updateAcl($acl);
     

Gotchas and Tips

Pitfalls

1. Deprecated Package:

   • The original alexdpy/acl-bundle is abandoned; use nuxia/acl-bundle (linked in README).
   • Migrate configurations/services if switching from the old bundle.

2. Permission Caching:

   • Permissions are cached by default. Clear cache after runtime changes:

     php bin/console cache:clear
     

3. Doctrine ORM Dependency:

   • The bundle assumes Doctrine ORM for ACL storage. For other DBALs, implement a custom AclStorage service.

4. Role Hierarchy Conflicts:

   • Explicitly define role hierarchies to avoid unexpected permission inheritance:

     # Avoid implicit conflicts
     ROLE_SUPER_ADMIN: ROLE_ADMIN
     ROLE_ADMIN:       [ROLE_USER, ROLE_EDITOR]
     

Debugging

• Check ACLs:

  $acl = $aclProvider->findAcl($entity);
  dump($acl->getEntries()); // Inspect permissions
  

• Enable ACL Logging: Add to config/packages/monolog.yaml:

  handlers:
      acl:
          type: stream
          path: "%kernel.logs_dir%/acl.log"
          level: debug
          channels: ["acl"]
  

Extension Points

1. Custom Permission Maps:

   • Extend PermissionMap to add domain-specific permissions:

     class CustomPermissionMap extends PermissionMap {
         public function __construct() {
             $this->addPermission('post', 'PUBLISH');
         }
     }
     

   • Register as a service:

     services:
         app.custom_permission_map:
             class: App\Security\CustomPermissionMap
             tags: ['nuxia_acl.permission_map']
     

2. Override ACL Storage:

   • Implement Nuxia\AclBundle\Security\Acl\AclStorageInterface for non-Doctrine setups.

3. Event Listeners:

   • Listen for ACL events (e.g., acl.update) to trigger side effects:

     use Nuxia\AclBundle\Event\AclEvent;
     
     $dispatcher->addListener('acl.update', function (AclEvent $event) {
         // Log or notify on ACL changes
     });