Close search
Hoa

Hack book of Hoa\Acl

Unfortunately, the documentation of this library has not been written yet. However, the README.md file may contain enough information to help you. This document is an extract of the README.md file.
Sorry for this inconvenience. Be ensured we are working hard to fix this.

Help on IRC Help on Gitter Documentation Board

This library allows to create and manipulate an Access Control List (ACL). The actors of an ACL are the following:

Whilst the word “list” is contained in its name, the underlying structure is a graph (please, see the Hoa\Graph library) where vertices (i.e. nodes) are groups.

Learn more.

Quick usage

As a quick overview, we propose the following actors:

Basically, there are 2 services: A product and a blog page. It can look like a little shop. Visitors can be logged or not. If logged, then it can buy a product. The shop can be administrated by editors, with different roles: One for the products and one for the blog. Thus, we have 4 groups: Visitor, buyer, editor and administrator.

Create the ACL

We start by creating all the actors, in separated variables for the sake of clarity:

$groupVisitor       = new Hoa\Acl\Group('group_visitor');
$groupBuyer         = new Hoa\Acl\Group('group_buyer');
$groupEditor        = new Hoa\Acl\Group('group_editor');
$groupAdministrator = new Hoa\Acl\Group('group_administrator');

$userAnonymousVisitor = new Hoa\Acl\User('user_visitor_anonymous');
$userLoggedVisitor    = new Hoa\Acl\User('user_visitor_logged');
$userProductEditor    = new Hoa\Acl\User('user_editor_product');
$userBlogEditor       = new Hoa\Acl\User('user_editor_blog');

$permissionRead  = new Hoa\Acl\Permission('permission_read');
$permissionWrite = new Hoa\Acl\Permission('permission_write');
$permissionBuy   = new Hoa\Acl\Permission('permission_buy');

$serviceProduct  = new Hoa\Acl\Service('service_product');
$serviceBlogPage = new Hoa\Acl\Service('service_blog_page');

Then, we put them together: We create an ACL instance, we add services on users and groups, we add users on groups, we add groups inside the ACL instance and finally we add permissions on groups.

// Create an ACL instance.
$acl = new Hoa\Acl();

// Add services to users and groups.
// The visitor group shares the product and the blog page services.
$groupVisitor->addServices([$serviceProduct, $serviceBlogPage]);
// The buyer group shares the product and the blog page services (reminder:
// Services are not inherited).
$groupBuyer->addServices([$serviceProduct, $serviceBlogPage]);
// The product editor user owns the product service.
$userProductEditor->addServices([$serviceProduct]);
// The blog editor user owns the blog page service.
$userBlogEditor->addServices([$serviceBlogPage]);

// Add users to groups.
// The visitor group contains one anonymous visitor user.
$groupVisitor->addUsers([$userAnonymousVisitor]);
// The buyer group contains one logged visitor user.
$groupBuyer->addUsers([$userLoggedVisitor]);
// The editor group contains two users: Product editor and blog editor.
$groupEditor->addUsers([$userProductEditor, $userBlogEditor]);

// Add groups to the ACL instance.
$acl->addGroup($groupVisitor);
// The buy group inherits permissions from the visitor group.
$acl->addGroup($groupBuyer, [$groupVisitor]);
$acl->addGroup($groupEditor);
// The administrator group inherits permissions from the editor group.
$acl->addGroup($groupAdministrator, [$groupEditor]);

// Add permissions.
// The visitor group has permission to read.
$acl->allow($groupVisitor, [$permissionRead]);
// The buy group has permission to buy.
$acl->allow($groupBuyer, [$permissionBuy]);
// The editor group has permission to read and write.
$acl->allow($groupEditor, [$permissionRead, $permissionWrite])

This is important to keep in mind that users and services are not inherited between groups.

Query the ACL

Now our ACL is build, we can query it by, for example, using the isAllowed method. This method takes at least 2 arguments: A user and a permission. It checks if a user has a certain permission. In addition, a service can be provided too, and then it checks if a user has a certain permission on a specific service. Let's see some examples.

$acl->isAllowed($userAnonymousVisitor, $permissionRead, $serviceProduct) // true
$acl->isAllowed($userAnonymousVisitor, $permissionBuy, $serviceProduct) // false
$acl->isAllowed($userLoggedVisitor, $permissionRead, $serviceProduct) // true
$acl->isAllowed($userLoggedVisitor, $permissionBuy, $serviceProduct) // true
$acl->isAllowed($userLoggedVisitor, $permissionWrite) // false
$acl->isAllowed($userProductEditor, $permissionBuy) // false
$acl->isAllowed($userProductEditor, $permissionWrite) // true
$acl->isAllowed($userBlogEditor, $permissionWrite) // true
$acl->isAllowed($userProductEditor, $permissionWrite, $serviceBlogPage) // false
$acl->isAllowed($userBlogEditor, $permissionWrite, $serviceBlogPage) // true

Using objects for users, permissions and services can sometimes be cumbersome. Thus, we can use their respective IDs instead. Consequently, one can write:

$acl->isAllowed('user_editor_blog', 'permission_write', 'service_blog_page') // true

Thinner query with specific asserter

It may happen that the ACL, with users, permissions, services and groups, cannot be able to expres all your constraints. That's why an asserter can be provided.

An asserter must implement the Hoa\Acl\Assertable interface and expect the assert method to be implemented. It will receive the $userId, $permissionId and optionally the $serviceId data. This assert method must compute a boolean that will be used as the latest step of the isAllowed method.

Imagine the following scenario where a logged user cannot buy another product before M minutes if the amount of the current shopping bag is greater than X:

class DoNotBuyThatMuch implements Hoa\Acl\Assertable
{
    public function assert($userId, $permissionId, $serviceId)
    {
        $shoppingBag = getShoppingBagOf($userId);

        return
            X < $shoppingBag->getAmount() &&
            time() + M * 60 > $shoppingBag->getCheckoutTime();
    }
}

$acl->isAllowed(
    $userLoggedVisitor,
    $permissionBuy,
    $serviceProduct,
    new DoNotBuyThatMuch()
);

Obviously, the assert body can be complex and this library does not address asserter aggregation or similar problems. However, the Hoa\Ruler library perfectly fills this role, you might want to consider it.

An error or a suggestion about the documentation? Contributions are welcome!

Comments

menu