Acl Manager Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require problematic/acl-manager-bundle:dev-master
   

   Register the bundle in AppKernel.php:

   new Problematic\AclManagerBundle\ProblematicAclManagerBundle(),
   

2. Enable ACL in security.yml:

   security:
       acl:
           connection: default
   

3. Initialize ACL:

   php app/console init:acl
   

First Use Case: Granting Permissions

Grant a user ownership of a persisted entity:

$comment = new Comment();
$em->persist($comment);
$em->flush();

$aclManager = $this->get('problematic.acl_manager');
$aclManager->addObjectPermission($comment, MaskBuilder::MASK_OWNER);

Implementation Patterns

Core Workflows

1. Entity-Level Permissions:

   • Use addObjectPermission()/setObjectPermission() for granular control.
   • Example: Restrict deletion for non-owners:

     $aclManager->revokePermission($comment, MaskBuilder::MASK_DELETE, $user);
     

2. Class-Level Permissions:

   • Apply permissions to all instances of a class:

     $aclManager->addClassPermission(Comment::class, MaskBuilder::MASK_EDIT, $user);
     

3. Field-Level Permissions:

   • Restrict access to specific fields:

     $aclManager->addObjectFieldPermission($comment, 'title', MaskBuilder::MASK_EDIT);
     

4. Bulk Operations:

   • Preload ACLs for collections to avoid N+1 queries:

     $aclManager->preloadAcls($comments);
     

Integration Tips

• Event Listeners: Hook into prePersist/preUpdate to auto-apply permissions:

  $entity->addLifecycleCallback(function($entity) {
      $aclManager->addObjectPermission($entity, MaskBuilder::MASK_OWNER);
  });
  

• Doctrine Events: Use onFlush to batch permission updates:

  $em->getEventManager()->addEventListener(
      Doctrine\ORM\Events::onFlush,
      function($event) use ($aclManager) {
          $uow = $event->getEntityManager()->getUnitOfWork();
          foreach ($uow->getScheduledEntityInsertions() as $entity) {
              $aclManager->addObjectPermission($entity, MaskBuilder::MASK_OWNER);
          }
      }
  );
  

Gotchas and Tips

Pitfalls

1. Persistence Requirement:

   • Error: AclManager fails silently if the entity lacks an ID.
   • Fix: Always flush() before granting permissions.

2. User Context:

   • Gotcha: Omitting $userEntity defaults to the current session user (not the entity owner).
   • Fix: Explicitly pass the target user:

     $aclManager->addObjectPermission($comment, MaskBuilder::MASK_OWNER, $ownerUser);
     

3. Permission Mask Conflicts:

   • Issue: setObjectPermission() overwrites all permissions, not just the specified mask.
   • Workaround: Use revokeAllObjectPermissions() first if partial updates are needed.

4. Field Permissions:

   • Warning: Field permissions (title) are case-sensitive and must match the entity property name exactly.

Debugging

• Check ACLs:

  $acl = $aclManager->findAcl($comment);
  dump($acl->getObjectIdentity()->getIdentifier());
  

• Log Mask Values: Enable Symfony’s ACL debug logging in config.yml:

  monolog:
      handlers:
          main:
              level: DEBUG
              channels: ["security"]
  

Extension Points

1. Custom Masks: Extend MaskBuilder to define domain-specific permissions:

   class CustomMaskBuilder extends MaskBuilder {
       const MASK_PUBLISH = 0x8000;
   }
   

   Register as a service:

   services:
       problematic.acl_manager.mask_builder:
           class: AppBundle\Security\CustomMaskBuilder
           tags: ['problematic.acl_manager.mask_builder']
   

2. Auditing: Subscribe to acl.update events to log permission changes:

   $dispatcher->addListener('acl.update', function($event) {
       $logger->info('Permission updated', [
           'entity' => $event->getEntity(),
           'mask' => $event->getMask(),
       ]);
   });
   

3. Performance: For large datasets, use preloadAcls() with a Doctrine\ORM\QueryBuilder to limit loaded entities:

   $qb = $repo->createQueryBuilder('c')
       ->where('c.createdAt > :date')
       ->setParameter('date', new \DateTime('-1 month'));
   $aclManager->preloadAcls($qb->getQuery()->getResult());