Acl Bundle Laravel Package

Getting Started

1. Install and register

   composer require oneup/acl-bundle
   

   // config/bundles.php
   Oneup\AclBundle\OneupAclBundle::class => ['all' => true],
   

2. Make Symfony's ACL component usable first. The bundle is a management layer, not a replacement, so the underlying security.acl config must be in place before anything works:

   # config/packages/security.yaml
   security:
       acl:
           connection: default
   

   Then create the ACL tables (bin/console init:acl, or let the Doctrine schema listener create acl_classes, acl_entries, acl_object_identities, acl_object_identity_ancestors, acl_security_identities).

3. Tell the bundle about your users. It needs to translate a domain user into a UserSecurityIdentity, and it ships with an adapter for the common user bundle of the era — you point the config at that service, or write a small adapter around your own User class. This is the one piece of glue you will almost certainly have to customize.

4. Where to look first: DependencyInjection/Configuration.php in the bundle (the authoritative config tree for your installed version), Resources/config/services.xml (the oneup_acl.* service ids), and the Admin/ or Controller/ directory — that is the ACL management UI. Use bin/console debug:container oneup and debug:container --tag=sonata.admin to see what actually got registered before you write any code against guessed service ids.

5. First real use case: open the ACL admin UI for a record (a Post, an Order, anything you store a DomainObjectInterface or plain entity for), grant VIEW/EDIT/OWNER to a user or role, then in a controller assert $this->denyAccessUnlessGranted('EDIT', $post) and in Twig {% if is_granted('VIEW', post) %}. If that loop works, the plumbing is correct.

Implementation Patterns

Grant on creation, not in the UI. The most valuable day-to-day pattern is seeding ACLs from domain events, so records are never orphaned without an owner:

// Doctrine listener on postPersist
$oid = ObjectIdentity::fromDomainObject($post);
$acl = $this->aclProvider->createAcl($oid);
$sid = UserSecurityIdentity::fromAccount($post->getAuthor());
$acl->insertObjectAce($sid, MaskBuilder::MASK_OWNER);
$this->aclProvider->updateAcl($acl);

Use the bundle's manager service instead of hand-rolling the mutable provider. Look for the Manager/ classes and the oneup_acl manager service; wrapping grant/revoke/setPermission calls there keeps the bundle's object-identity handling and cache invalidation consistent between your code and the admin UI. Dropping down to security.acl.provider for bulk work is fine, but don't mix the two on the same object in the same request without a flush in between.

Admin UI as the operator-facing surface, code as the policy. A healthy division: your code creates the initial OWNER ACE and enforces checks; the bundle's UI lets trusted users add VIEW/EDIT grants. Do not let business-critical rules live only in the UI — they become invisible to code review and untestable.

Integration points:

• Put ACL checks in a Symfony voter (isGranted('EDIT', $post)) rather than in query logic, so controllers, templates, and API serializers share one answer.
• Mount the ACL admin behind a firewall and an ROLE_ADMIN-style gate; the UI can rewrite any permission on any managed object.
• For non-Doctrine objects (files, external records), register an ObjectIdentity type mapping or use class-name identities so the UI and code agree on the identity string.

Batch/preload for lists. If you render a table of 50 records and check each one, you will generate hundreds of queries. Preload identities through the ACL provider (preloadObjectIdentities / preloadAcls on the mutable provider, or an equivalent batch call in the bundle's manager) before the loop.

Gotchas and Tips

• The bundle is thin and old. 49 stars and a low activity score mean you should treat it as a UI wrapper you may have to patch. Pin exact versions, and read the bundle source when a service id or config key doesn't behave as the README says — those docs drift.
• Symfony's ACL component itself is legacy. It is slow, schema-heavy, and discouraged for new applications. Adopt this bundle only if you are maintaining an existing ACL-based app; for new work, object-level permissions in your own tables or a dedicated authorization layer is usually a better trade.
• Identity string drift is the classic disaster. UserSecurityIdentity stores the username or the id, whichever your adapter returns. Migrating from username to id, or renaming users, silently invalidates every ACE. Pick one and never change it.
• Orphaned ACEs. Deleting a Post leaves its acl_object_identities and acl_entries rows behind, and a new record reusing that primary key inherits the old permissions. Add an onDelete/postRemove cleanup or a scheduled purge.
• Cache invalidation. The ACL provider caches aggressively. After manual SQL edits or imports, clear the ACL cache explicitly; otherwise the admin UI shows stale grants.
• Proxy class names. ObjectIdentity::fromDomainObject() on a lazy-loaded Doctrine proxy can produce the proxy class name on older versions, creating a second, empty ACL. Use ClassUtils::getClass() semantics when building identities manually.
• Config mismatches. If the bundle's admin reads ACL tables via a different connection than security.acl.connection, the UI will look empty while isGranted works. Keep both pointed at the same entity manager.
• Extension point: the user-manager adapter is the intended customization seam. Everything else (admin classes, templates) can be overridden through the bundle's Resources/ convention or by replacing service definitions in your app config.
• Debugging: AclProvider::getAces($sid, $oid, $type) is your ground truth when the UI and isGranted disagree; the mismatch is nearly always a different security identity or a different object identity string, not a broken voter.