currentMenu
introduction

MyCLabs ACL is a library that helps managing permissions on your model.

It is different from other ACL libraries in that it focuses on controlling access to your model classes (Doctrine entities). As such, you access control model follows your real model, which makes it possible to have access in cascade easily (e.g. if you can access a category, you can also access all the sub-categories it contains).

It is also optimized as much as possible: authorizations are stored in database in a way to allow very efficient filtering at the SQL level through Doctrine queries (you can load only the objects a user can access). No other ACL system that we know of allows this.

Requirements:

• PHP 5.4
• Use Doctrine as the ORM for your model
• Doctrine 2.5 (currently in beta)

Vocabulary:

• Security identity: the entity which will be granted some access (this is generally the user)
• Resource: a thing to which we want to control the access
• Authorization: allows a security identity (user) to do something on a resource
• Role: a role gives authorizations to a user (e.g. an administrator, an article editor, a project owner, …)

There are 2 kinds of resources:

• an entity (example: article #123)
• all entities of a given type (example: all articles), which is represented by the classname of the entity

Overview

We hate being lost and confused, so everything you have to do with ACL is done on the ACL service. You can start by creating it:

// full configuration shown in the documentation
$acl = new ACL($entityManager);

You give permissions to a user by adding it a role:

$acl->grant($user, new ArticleEditorRole($user, $article));

Roles are classes that you write and which define the permissions a user has on a resource.

You remove permissions to a user by removing the role:

$acl->revoke($user, $role);

Test permissions:

$acl->isAllowed($user, Actions::EDIT, $article);

You can also filter your queries to get only the entities the user has access to:

$qb = $entityManager->createQueryBuilder();
$qb->select('article')->from('Model\Article', 'article');

ACLQueryHelper::joinACL($qb, $user, Actions::EDIT);

// This query will return only the articles the user can edit
$articles = $qb->getQuery()->getResult();

Features

• stored in database (you don't need to handle persistence yourself)
• extremely optimized:
  • filters queries at database level (you don't load entities the user can't access)
  • joins with only 1 extra table
  • bypasses Doctrine's ORM to insert authorizations in database (fast and efficient)
  • cascade delete at database level
• authorization cascading/inheritance
• authorizations are rebuildable: you can change what an "ArticleEditor" can do afterwards and just rebuild the ACL
• supports your custom actions on top of standard actions like "view", "edit", "delete", …

Limitations

• because of Doctrine limitations you need to flush your resources before giving or testing authorizations
• backed up by the database: testing isAllowed means one call to the database