[cvs] [Wiki] changed: Doc/Dev/PermsPackage

[Wiki Guest]

guest [66.66.8.61]  Thu, 02 Oct 2008 23:40:15 -0400

Modified page: http://wiki.horde.org/Doc/Dev/PermsPackage
New Revision:  2.1
Change log:  Removed extra + signs that were mistakenly added for formatting

@@ -1,12 +1,12 @@
-+Horde Permissions Framework+
++Horde Permissions Framework
  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.

-++Defining Available Permissions++
+++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.
  In this example we'll add the permission "arbitrary_permission" to  
application foo.
@@ -50,9 +50,9 @@
  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.  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 $perms[‘type’].  There are two 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.

-++Applying Permissions / Persistent Storage++
+++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.
  Perms contains the actions one performs, such as adding or removing  
permissions.  Horde_Permission is an entity class that represents a  
permission.  The PhpDocumentor documentation at  
http://dev.horde.org/api/framework/ (choose the Horde_Perms package)  
covers these classes fairly well.
  Note that the Permissions class is a singleton.  The instance is  
usually already defined in a global variable $GLOBALS[‘perms’].  It’s  
also possible to access the static singleton method like so:
@@ -68,9 +68,9 @@
  $p->addUserPermission(‘someUser’, PERMS_SHOW | PERMS_READ |  
PERMS_EDIT | PERMS_DELETE);
  $perms->addPermission($p);
  </code>

-++Using / Enforcing Permissions++
+++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:

  <code type="php">