\documentclass{article}
\usepackage{ulem}
\pagestyle{headings}
\begin{document}
\part{Horde Permissions Framework}
This documentation is for Horde 5 and mostly also applies to Horde 4.

There are three aspects to the permissions framework.  The first is to tell Horde what permissions your application has.  Horde uses a unified tree structure to track all permissions, with each application having a branch off the root.  In your application, you must create a list of permissions that Horde will then merge with other applications.

Next, an administrator needs to be able to assign or revoke privileges.  This part is completely abstracted and there isn't much to say for developers.  Horde itself has a UI for administering permissions, but it's just a front-end to the permissions API.  Therefore, your application can choose to manage permissions in its own UI or business logic, but it doesn't strictly need to (and probably shouldn't).

The most important part is to enforce them.  As a developer, you need to add code into your business logic to check permissions before doing something protected.  None of the framework is useful without this step.

\section{Defining Available Permissions}
To allow Horde to manage your permissions, it needs to know what they are.  This is where the design stage comes in.  Internally, Horde identifies permissions via a tree.

Each application defines its portion of the tree.  Whenever the Horde API is invoked, it needs to resolve a permission name, so it calls a function called \_app\_perms() within each application (if it exists) and merges its results.\newline
In this example we'll add the boolean (yes/no) permission "arbitrary\_permission" to our application and then add a numeric (count) sub-permission

In foo/lib/Application.php:

\begin{verbatim}

  public function perms()
    {
        $permissions = array(
            'arbitrary_permission' => array(
                'title' => _("Textual description"),
                'type' => 'boolean'
            ),
            'arbitrary_permission:some_count_permission' => array(
                'title' => _("Textual description"),
                'type' => 'int'
            )
        );
   return $perms;
}
\end{verbatim}

Now you can go to the Horde administration workflow and click on 'Permissions'.  On this page, you will be able to see the permissions tree.  Add a child node for your 'foo' application.  Then when you add a child to the 'foo' application, you will see your new permission in the list of permissions (the only item in this list in this example).

This example is obviously very simplistic.  The flexibility comes in when populating the above list dynamically from persistent storage.  For example, if your application manages widgets, you can make a database call in perms()  and loop over your result set.

\begin{verbatim}

while(($row = ($resultSet->next()) !== null) {
    $widgetId = $row['widgetId'];
    $widgetName = $row['widgetName'];

    $perms['tree']['foo'][$widgetId] = false;
    $perms['title']["foo:$widgetId"] = $widgetName 
}
\end{verbatim}

Using this strategy, one can create ACL's that apply to a specific object, rather than static permissions, like "create widgets".  Permissions can even be nested.\newline
One can create a static permission called "widgets" whose permission mappings represent what a given user can do to ALL widgets, then dynamically add children permissions for specific widgets.

Notice the use of the array key ['type'].  There are three types of permissions, which determine the levels of that permission a user may have.  In the first example, type Boolean, the user either has the permission, or they don't.  The second type (default if not specified) is 'matrix', which allows for various levels, specifically, SHOW, READ, EDIT, and DELETE.  A user may have any of these levels assigned, or none. The last type of permission is "int" or numeric which is handy to define limits (allow max 10 widgets for this user).

\section{Applying Permissions / Persistent Storage}
This part of the process is completely abstracted and your application shouldn't deal with it.  However, it is obviously important to understand.  Horde exposes its API via two classes: Perms and Horde\_Permission.\newline
Perms contains the actions one performs, such as adding or removing permissions.  Horde\_Permission is an entity class that represents a permission.  The PhpDocumentor\footnote{http://example.com/index.php?page=PhpDocumentor} documentation at http://dev.horde.org/api/framework/\footnote{http://dev.horde.org/api/framework/} (choose the Horde\_Perms package) covers these classes fairly well.\newline
\begin{verbatim}

// Get a Horde_Perms_Base related instance
$perms = $injector->getInstance('Horde_Perms');
\end{verbatim}

To add a new permission (assuming it's already defined) into persistent storage, use \$perms->newPermission(), which gives you back a Horde\_Permission object that you can then populate with users and permission assignments.

\begin{verbatim}

// See the permission tree. Useful for traversal, admin scripts or for looking at things when debugging
$perms->getTree();
\end{verbatim}

\newline
Example Output:\newline
    [4] => foo\newline
    [5] => foo:administrator\newline
    [14] => foo:configure\newline
    [12] => foo:download\newline
    [11] => foo:read\newline
    [9] => foo:reseller\newline
    [10] => foo:rest-api\begin{verbatim}

// Get a Horde_Perms_Permission object representing a node in the permission tree

$permission = $perms->getPermission('foo:download');
\end{verbatim}

\begin{verbatim}

// Make sure we loaded the right permission

echo $permission->getName();
\end{verbatim}

\newline
foo:download\begin{verbatim}

// add a boolean true for this permission for user lang and immediately save to backend

$permission->addUserPermission('lang', true);
$permission->save();

// The same, but shorter

$permission->addUserPermission('lang', true, true);

// Most permissions are matrix permissions.
$permission->addUserPermission('lang', Horde_Perms::SHOW);
$permission->addUserPermission('lang', Horde_Perms::READ);
$permission->addUserPermission('lang', Horde_Perms::EDIT);
$permission->addUserPermission('lang', Horde_Perms::DELETE);

// Give all permission levels at once for this permission and this user
$permission->addUserPermission('lang', Horde_Perms::ALL);
// Don't forget to save
$permission->save();

// Group permissions are just the same - give all trainees read and show, then save.

$permission->addGroupPermission('trainees', Horde_Perms:READ);
$permission->addGroupPermission('trainees', Horde_Perms:SHOW, true);
\end{verbatim}

\section{Using / Enforcing Permissions}
None of this code matters if your application doesn't actually check these permissions.  This is best done in your business logic and NOT at the user interface level.  To check if a user has a given permission, simply call Perms::hasPermission() through the singleton object.  For example:

\begin{verbatim}

// TODO: H5 registry-> example

// Old H3 example
public function myBusinessMethod($widgetId)
{
    if(!$GLOBALS['perms']->hasPermission("foo:$widgetId", Auth::getAuth(), PERMS_EDIT))
            throw new Exception(_("Access denied."));

    // your business code
}
\end{verbatim}

\end{document}
