Your subclass of Perm defines an array $permissions, which translates permission names into bit patterns. For example, the definition of Example_Perm in the distributed local.inc defines the names user, author, editor, supervisor and admin, all of which translate into a bit pattern with a single bit set.

A user may be assigned any number of permissions as a comma separated list of permission names (no spaces!) in the perms column of the auth_user table. The effective permissions of the user are determined by logically OR'ing the bit patterns of these permissions.

A page may require any permissions as a comma separated list of permission names (again no spaces!) with the $perm->check() function. The required permissions are again determined by logically OR'ing the bit patterns of these permissions. Similarly, a page function may be protected by requiring permissions with $perm->check().

Access is granted to a protected page or a protected page function, if the effective permissions of the authenticated user have all the required bits set, that is: If the effective permissions of the user logically AND'ed with the required permissions are equal to the required permissions.

With the permission names as defined in Example_Perm from the distribution, a user kris may be defined with admin permission in the auth_user table. A page that requires admin,user permission with $perm->check("user,admin") is inaccessible to this user. This is how it is calculated:

         Effective Permissions of User: admin              translates into:    16
         Required Permissions of Page : user,admin
                       translates into:    1 OR 16 == 17Permission Check:
                 Effective Permissions 16 AND     Required Permissions  17
         ARE     16 & 17 =             16
         MUST BE Required Permissions  17 -> access denied
 

The example permissions as defined in Example_Perm from the distribution are called atomic permissions, because each of them has only a single bit set. Atomic permissions are the simplest of all schemes, because they allow for easy permission checks: To access a page protected with user,admin, you need to have at least user,admin rights in your auth_user table.

Another common scheme used in permission definitions are inclusive permissions. In this scheme, each permission definition has all bits of its predecessor set plus one addition bit. For example

         class Inclusive_Perm extends Perm {
           var $classname = "Inclusive_Perm";

           var $permissions = array(
                                     "user"       => 1,
                                     "author"     => 3,
                                     "editor"     => 7,
                                     "supervisor" => 15,
                                     "admin"      => 31
                              );
         }

defines a set of inclusive permissions. In this example, a user kris with admin permissions can easily access a page protected with editor permissions. This is how it is calculated:

         Effective Permissions of User: admin
                       translates into:    31

         Required Permissions of Page : editor
                       translates into:     7

         Permission Check:
                 Effective Permissions 31
         AND     Required Permissions   7
         ARE     31 & 7 =               7

         MUST BE Required Permissions   7 -> access granted
 

Inclusive Permissions are easy to deal with, too, because a user with a higher access level may access all pages or page functions with a lower access level.

Due to limitations of your machines integer size you can only define up to 31 permission levels.