Checking Permissions

Checking Permissions
Prev	Chapter 7. Checking Permissions in the Control Panel	Next

Checking permissions is achieved using the Recite ACL manager. In order to perform a permissions query the Application_User_Permissions_Query and Application_User_Permissions_Query_Item classes.

Checking a Single Permission

To check a single permission use the Application_User_Permissions_Query_Item class. The name of the permission to check is passed as the only argument to the constructor.

You can then call the check() to check the permission. This method returns true if the current user has the permission or false if not.

Alternatively, you can use the assert() method. If the current user does not have access the Application_User_Permissions_Exception exception is thrown.

Example 7.1. Checking a single permission with both check() and assert()

<?php
    $item = new Application_User_Permissions_Query_Item('some:permission:to:check');
    
    if ($item->check()) {
        // current user has permission
    }
    else {
        // current user does not have permission
    }
    
    try {
        $item->assert();
        
        // current user has permission
    }
    catch (Exception $ex) {
        // current user does not have permission
    }
?>

Typically you won't have to explicitly catch the exception since Recite will handle a permissions exception automatically.

You can short-cut this code using the static BuildAndCheck() or BuildAndAssert() methods. You can use these when you don't need access to the permissions query item.

Example 7.2. Using Shorter Notation for Permissions Check

<?php
    if (Application_User_Permissions_Query_Item::BuildAndCheck('some:permission:to:check')) {
        // current user has permission
    }
    else {
        // current user does not have permission
    }
    
    try {
        Application_User_Permissions_Query_Item::BuildAndAssert('some:permission:to:check');
        
        // current user has permission
    }
    catch (Exception $ex) {
        // current user does not have permission
    }
?>

Checking Multiple Permissions

In the previous section I showed you how to check a single permission. Sometimes you will want to check a series of permissions at once. This will typically involve either wanting all of the permissions to pass, or any of the permissions to pass.

Requiring All Permissions to Pass

If you want a permissions query in which all permissions must succeed, you want an AND query.

To create a new AND query you must create a new instance of the Application_User_Permissions_Query class by calling its static NewAnd(). This will return an empty query which you can add permissions to.

To add a permission to query call the add() method. You can pass either a string (the name of the permission) or an instance of Application_User_Permissions_Query_Item.

Once you've built the query you can call either check() (to return a boolean) or assert() (to thrown an Application_User_Permissions_Exception exception).

Example 7.3. Checking multiple permissions at once with an "AND" permissions query

<?php
    $query = Application_User_Permissions_Query::NewAnd();
    $query->add('first:permission:to:check')
          ->add(new Application_User_Permissions_Query_Item('second:permission:to:check'))
          ->assert();
?>

In the above example both permission checks must succeed to avoid the exception being thrown.

Important

Permissions are processed lazily and in-order. This means that in an "AND" query, if a single permission check fails then no more permissions are checked. The resultant exception will only contain details about the permissions check that failed and not the remaineder of the permissions that might have failed if it had proceeded.

Requiring Any Permission to Pass

If you have a two or more permissions to check but only one of them needs to pass then you want an "OR" query.

The code used to build and check the query is the same as an "AND" query, except that you use the NewOr() static method to create an empty query object.

Example 7.4. Checking multiple permissions at once with an "AND" permissions query

<?php
    $query = Application_User_Permissions_Query::NewOr();
    $query->add('first:permission:to:check')
          ->add(new Application_User_Permissions_Query_Item('second:permission:to:check'))
          ->assert();
?>

In the above example either permission check must succeed to avoid the exception being thrown.

Important

Permissions are processed lazily and in-order. This means that in an "OR" query, as soon as a permissions check succeeds the query is complete. If the query fails then the resultant exception will contain details about every single permission in the query.

Prev	Up	Next
Defining Permissions	Home	Using Permissions in Templates