Policy functions

Access in Exponential is granted with roles and policies. A policy lets the users of a role use a whole module, or one function of a module, possibly only with some limitations (sections, classes, subtrees, languages ...). Which function a view needs is set in the module's definition, module.php. This page explains how views, functions and limitations fit together, for developers who write modules and for administrators who build roles.

Views and functions

A module defines its views in $ViewList and its policy functions in $FunctionList. Each view names the functions it needs under functions. From kernel/notification/module.php:

$ViewList["settings"] = array(
    "functions" => array( 'use' ),
    "script" => "settings.php",
    'ui_context' => 'administration',
    "default_navigation_part" => 'ezmynavigationpart',
    "params" => array( ),
    'unordered_params' => array( 'offset' => 'Offset', 'q' => 'Query', 'class' => 'ClassFilter' ) );

$ViewList["runfilter"] = array(
    "functions" => array( 'administrate' ),
    "script" => "runfilter.php",
    "default_navigation_part" => 'ezsetupnavigationpart',
    "params" => array( ) );

$FunctionList['use'] = array( );
$FunctionList['administrate'] = array( );

A user with a policy for notification/use may open notification/settings and notification/addtonotification; notification/runfilter, status and job need notification/administrate. A policy for notification/* grants every function of the module.

Several functions for one view

The entries of functions are combined with and; inside an entry, and (or &&), or (or ||) and parentheses can be used.

// kernel/content/module.php: both functions are needed
$ViewList['tipafriend'] = array(
    'functions' => array( 'tipafriend', 'read' ), ... );
// the same, as one expression
'functions' => array( 'tipafriend and read' ),

// kernel/section/module.php: any one of the three is enough
$ViewList['list'] = array(
    'functions' => array( 'view or edit or assign' ), ... );

Each function name in the expression is replaced by whether the user has it; any other word makes the view refuse access and writes an error to the debug output.

Views without functions

A view that names no function can only be used with a policy for the whole module (<module>/*). A module without any functions, such as collaboration, is therefore granted only as a whole. Views listed in site.ini [RoleSettings] PolicyOmitList[] (such as user/login and switchlanguage/to) are not checked at all.

Before the 3.9.3 release, a policy for any function of a module also opened the views of that module that named no function. That changed in 3.9.3 and 3.10; modules should still not mix views with and without functions.

Limitations

A function can support limitations, given as its value in $FunctionList. From kernel/content/module.php:

$FunctionList['diff'] = array( 'Class' => $ClassID,
                               'Section' => $SectionID,
                               'Owner' => $Assigned,
                               'Node' => $Node,
                               'Subtree' => $Subtree );
$FunctionList['tipafriend'] = array();

content/diff can be limited by class, section, owner, node and subtree; content/tipafriend is all or nothing. A policy with several limitations allows only what all of them allow together. Which limitation a view or a template checks is up to its code: $user->hasAccessTo( $module, $function ) in PHP returns yes, no or limited with the policies; templates use fetch( 'user', 'has_access_to', hash( 'module', ..., 'function', ... ) ).

Finding the functions

• In the administration, Users > Roles and policies: the role editor lists every module, its functions and their limitations.
• The policies of every module, generated from the module.php files, and every module view with the function it needs.
• ./console exp:cleanuppolicies lists policies of modules that no longer exist (and removes them with --apply).

More

• Roles, policies and unactivated users.
• Role and policy template operators and the order of policies.
• Language-based permissions.