This page covers epesi's permissions system: Clearance, which controls what a user's account can do, and Permissions, which modules use to check whether a given action is allowed.
epesi includes a powerful, configurable permissions system that lets you adjust an installation to fit nearly any requirement.
The first concept to understand when managing permissions in epesi is Clearance. Every user has one or more Clearances assigned, and the Clearances a user holds determine which features are available to them. Clearances are configured per user by an administrator, in the Login Panel section of the user's Contact form. The default Clearances are:
ALL - All Users - granted to every active user in the system; mainly used for clear rule presentation
ADMIN - Admin - granted to regular administrators, assigned on the Contact panel
SUPERADMIN - Superadmin - granted to super-administrators, assigned on the Contact panel
ACCESS:employee - Access: Employee - granted to any user whose contact has "Employee" set in the contact's Access field
ACCESS:manager - Access: Manager - granted to any user whose contact has "Manager" set in the contact's Access field
You can add more access levels by extending the Contacts/Access CommonData table. New levels added this way are managed the same way as Access: Manager or Access: Employee. Note that some modules extend the Contacts/Access table automatically.
To add a Clearance level, extend the Contacts/Access table:
Utils_CommonDataCommon::extend_array('Contacts/Access',array('my_clearance'=>'My Clearance'));Take note of the key — that's the value you'll use as the required Clearance when defining default rules for new Permissions:
ACCESS:my_clearanceAny module can define new Permissions, which can then be checked to see whether a given user can access a part of the system. Create a new Permission with:
Base_AclCommon::add_permission($permission_name [, $default_rule1 [, $default_rule2, ...]]);$permission_name should be a string describing the feature the permission unlocks. The optional rules that follow are default rules — they grant access right after installation, before an administrator has a chance to adjust anything. Each rule is an array of clearances. If a rule lists more than one clearance, the user must hold all of them for the rule to pass; if any single clearance is missing, that rule is rejected. You can provide multiple rules to cover different types of users — a user is granted access if they pass any one of the rules.
To check whether the current user has access to a part of the system:
Base_AclCommon::check_permission($permission_name);This returns true if access should be granted, false otherwise.
When uninstalling your module, remove any permissions it introduced:
Base_AclCommon::delete_permission($permission_name);Don't manipulate permission values or rules outside of your module's install/uninstall routines — administrators have their own interface for adjusting permissions afterward, and changing them elsewhere would fight that.
Permissions can be referenced across modules, but make sure any permission you check was introduced by a module you've listed as a dependency.