Acl Helper Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require curiosity26/acl-helper-bundle
   

   Ensure the bundle is enabled in config/bundles.php:

   return [
       // ...
       Curiosity26\AclHelperBundle\Curiosity26AclHelperBundle::class => ['all' => true],
   ];
   

2. First Use Case: Inject AclHelper into your controller/service and query ACL-filtered entities directly:

   use Curiosity26\AclHelperBundle\Helper\AclHelper;
   use Symfony\Component\Security\Acl\Permission\BasicPermissionMap;
   
   public function __construct(private AclHelper $aclHelper) {}
   
   public function listAction(): array
   {
       $agent = $aclHelper->createAgent(MyEntity::class);
       $permMap = new BasicPermissionMap();
       $query = $aclHelper->getQueryBuilder(MyEntity::class, $agent, $permMap, 'VIEW');
   
       return $query->getQuery()->getResult();
   }
   

3. Key Files:

   • src/Helper/AclHelper.php: Core logic for ACL-aware queries.
   • Tests/ directory: Example implementations (e.g., TestObject).
   • Resources/config/services.yaml: Service configuration.

Implementation Patterns

Core Workflow

1. Agent Creation:

   $agent = $aclHelper->createAgent(MyEntity::class);
   

   • Wraps the current user/security context for ACL checks.

2. Permission Mapping: Use BasicPermissionMap or extend it for custom permissions:

   $permMap = new BasicPermissionMap();
   $permMap->addPermission('EDIT'); // Add custom permissions if needed
   

3. Query Construction:

   $queryBuilder = $aclHelper->getQueryBuilder(
       MyEntity::class,
       $agent,
       $permMap,
       'VIEW' // Permission to check
   );
   

   • Returns a QueryBuilder pre-filtered for ACLs.
   • Supports pagination (e.g., ->setMaxResults(10)).

4. Integration with Doctrine:

   $entities = $queryBuilder
       ->where('e.active = :active')
       ->setParameter('active', true)
       ->getQuery()
       ->getResult();
   

Advanced Patterns

• Dynamic Permissions: Pass a closure for dynamic permission checks:

  $queryBuilder = $aclHelper->getQueryBuilder(
      MyEntity::class,
      $agent,
      $permMap,
      fn(MyEntity $entity) => $entity->isEditableBy($user)
  );
  

• Bulk Operations: Use getQueryBuilder() for DELETE/UPDATE queries to filter records by ACLs:

  $queryBuilder->delete();
  

• Caching: Cache QueryBuilder instances if permissions rarely change:

  $cacheKey = 'acl_query_' . $userId . '_' . md5(serialize($permMap));
  $queryBuilder = $cache->get($cacheKey, fn() => $aclHelper->getQueryBuilder(...));
  

Gotchas and Tips

Pitfalls

1. Associations Not Filtered:

   • The bundle does not filter associated entities (e.g., User::with('posts')).
   • Workaround: Manually filter associations post-query or use a separate query for each.

2. Field-Level Security:

   • ACLs apply to entity visibility, not field visibility.
   • Workaround: Use Symfony’s PropertyAccess or custom hydrators to mask fields.

3. Performance with Large Datasets:

   • Complex ACL rules (e.g., nested OR conditions) can bloat queries.
   • Tip: Use database indexes on owner_id and ACL-related fields.

4. Permission Map Limitations:

   • BasicPermissionMap is rigid. Extend it for custom logic:

     class CustomPermissionMap extends BasicPermissionMap {
         public function __construct() {
             $this->addPermission('APPROVE'); // Add custom permissions
         }
     }
     

5. Deprecated Symfony ACL:

   • The bundle relies on Symfony’s deprecated Security.Acl component.
   • Tip: Monitor for updates or consider migrating to Symfony’s Voter system.

Debugging

• Query Dumping: Enable Doctrine’s query logging to inspect generated SQL:

  # config/packages/doctrine.yaml
  doctrine:
      dbal:
          logging: true
          logging_format: '%%timestamp%% %%sql%%'
  

• Permission Debugging: Log the effective permissions for an entity:

  $aclHelper->debugPermissions(MyEntity::class, $agent, $permMap);
  

Extension Points

1. Custom ACL Providers: Override the default ACL provider by binding your own service:

   # config/services.yaml
   services:
       App\Security\CustomAclProvider:
           tags: [curiosity26.acl_helper.provider]
   

2. QueryBuilder Modifiers: Subscribe to events to modify queries:

   $aclHelper->addQueryModifier(function (QueryBuilder $qb, string $entityClass) {
       $qb->andWhere('e.published = :published')
          ->setParameter('published', true);
   });
   

3. Event Listeners: Listen for acl_helper.query_built to inspect/modify queries:

   $dispatcher->addListener('acl_helper.query_built', function (QueryBuiltEvent $event) {
       $event->getQueryBuilder()->setMaxResults(50);
   });