HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

ocPortal Developer's Guide: The Permissions system

» Return to Contents



Permissions are drawn off usergroup membership, and access control is defined on usergroup level. Preferably a forum would allow multiple usergroups per member, in order to allow overlapping (not just plain stacked) permissions - but most unfortunately are rather simplistic, which is just as limiting to the forum as well as to ocPortal. OCF supports advanced multiple usergroup membership features.

The permission architecture in ocPortal is particularly rich, giving the user a high degree of control over their site, without the need for additional complexity (because permissions are overrided on a per-page and per-category basis, but otherwise apply globally).

The term 'module' in the permissions sense is not exactly the same as a 'module' in the usual ocPortal sense. A permissions module is usually the same name as the main module for viewing the content in question, but it may not be if the main module supports multiple types of content: for example, the catalogues module has support for both catalogue-permissions and category-permissions, so the permission modules are 'catalogues_catalogue' and 'catalogues_category'.
When specific permissions are overrided by pages, the pages that the overriding is defined for is usually the content management page; for example, if add_midrange_content is overridden for the download system as a whole, it would be overridden with the page name 'cms_downloads'. It could also be overridden on a per-download-category basis, in which case the permissions module would be 'downloads'.
A third point of confusion is that of SEO modules: these define yet another set of 'module' names: these are however totally unrelated to permissions.

sources/permissions.php

Global_functions_permissions.php

Function summary

void init__permissions ()
void handle_permission_check_logging (MEMBER member, ID_TEXT op, array params, boolean result)
void access_denied (ID_TEXT class, string param, boolean force_login)
boolean has_zone_access (MEMBER member, ID_TEXT zone)
boolean has_actual_page_access (?MEMBER member, ?ID_TEXT page, ?ID_TEXT zone, ?array cats, ?mixed sp)
void load_up_all_self_page_permissions (MEMBER member)
boolean has_page_access (MEMBER member, ID_TEXT page, ID_TEXT zone, boolean at_now)
void load_up_all_module_category_permissions (MEMBER member, ?ID_TEXT module)
boolean has_category_access (MEMBER member, ID_TEXT module, ID_TEXT category)
?string _get_where_clause_groups (MEMBER member)
void enforce_personal_access (MEMBER member_id, ?ID_TEXT permission, ?ID_TEXT permission2, ?MEMBER member_viewing)
void check_specific_permission (ID_TEXT permission, ?array cats, ?MEMBER member_id)
boolean has_some_cat_specific_permission (MEMBER member, ID_TEXT permission, ?ID_TEXT page, ID_TEXT permission_module)
boolean has_specific_permission (MEMBER member, ID_TEXT permission, ?ID_TEXT page, ?array cats)
void check_submit_permission (string range, ?array cats, ?ID_TEXT page)
boolean has_submit_permission (string range, MEMBER member, IP ip, ?ID_TEXT page, ?array cats)
void check_some_edit_permission (string range, ?array cats)
void check_edit_permission (string range, ?MEMBER resource_owner, ?array cats, ?ID_TEXT page)
boolean has_edit_permission (string range, MEMBER member, ?MEMBER resource_owner, ?ID_TEXT page, ?array cats)
void check_delete_permission (string range, ?MEMBER resource_owner, ?array cats, ?ID_TEXT page)
boolean has_delete_permission (string range, MEMBER member, ?MEMBER resource_owner, ?ID_TEXT page, ?array cats)

void init__permissions()

Standard code module initialisation function.

Parameters…

(No return value)


Return to the function index for this class Expand: View the source code to this function

void handle_permission_check_logging(MEMBER member, ID_TEXT op, array params, boolean result)

Log permission checks to the permission_checks.log file, if it exists.

Parameters…

Name member
Description The user checking against
Type MEMBER

Name op
Description The function that was called to check a permission
Type ID_TEXT

Name params
Description Parameters to this permission-checking function
Type array

Name result
Description Whether the permission was held
Type boolean

(No return value)


Return to the function index for this class Expand: View the source code to this function

void access_denied(ID_TEXT class, string param, boolean force_login)

Show a helpful access-denied page. Has a login ability if it senses that logging in could curtail the error.

Parameters…

Name class
Description The class of error (e.g. SPECIFIC_PERMISSION)
Type ID_TEXT

Name param
Description The parameteter given to the error message
Default value
Type string

Name force_login
Description Force the user to login (even if perhaps they are logged in already)
Default value boolean-false
Type boolean

(No return value)


Return to the function index for this class Expand: View the source code to this function

boolean has_zone_access(MEMBER member, ID_TEXT zone)

Find if a member's has access to a specified zone

Parameters…

Name member
Description The member being checked whether to have the access
Type MEMBER

Name zone
Description The ID code for the zone being checked
Type ID_TEXT

Returns…

Description Whether the member has zone access
Type boolean

Return to the function index for this class Expand: View the source code to this function

boolean has_actual_page_access(?MEMBER member, ?ID_TEXT page, ?ID_TEXT zone, ?array cats, ?mixed sp)

Find if a member's has access to a specified page. Zone permissions are taken into account for wherever the page is found at. Also support for category access and privileges. No support for entry-point checks, which are only carried out as an extension of page permissions when actually at a page.

Parameters…

Name member
Description The member being checked whether to have the access (NULL: current member)
Default value
Type ?MEMBER

Name page
Description The ID code for the page being checked (NULL: current page)
Default value
Type ?ID_TEXT

Name zone
Description The ID code for the zone being checked (NULL: search)
Default value
Type ?ID_TEXT

Name cats
Description A list of cat details to require access to (c-type-1,c-id-1,c-type-2,c-d-2,...) (NULL: N/A)
Default value
Type ?array

Name sp
Description Either the ID code of a privilege, an array of alternatives that are acceptable (NULL: none required)
Default value
Type ?mixed

Returns…

Description Whether the member has zone and page access
Type boolean

Return to the function index for this class Expand: View the source code to this function

void load_up_all_self_page_permissions(MEMBER member)

For efficiency reasons, load up loads of page permissions.

Parameters…

Name member
Description The member being checked whether to have the access
Type MEMBER

(No return value)


Return to the function index for this class Expand: View the source code to this function

boolean has_page_access(MEMBER member, ID_TEXT page, ID_TEXT zone, boolean at_now)

Find if a member's has access to a specified page, in a specific zone. Note that page access does not imply zone access; you have access a page, but not the zone, so still couldn't see it.

Parameters…

Name member
Description The member being checked whether to have the access
Type MEMBER

Name page
Description The ID code for the page being checked
Type ID_TEXT

Name zone
Description The ID code for the zone being checked
Type ID_TEXT

Name at_now
Description Whether we want to check we have access to the CURRENT page, using any match tag permissions
Default value boolean-false
Type boolean

Returns…

Description Whether the member has page access
Type boolean

Return to the function index for this class Expand: View the source code to this function

void load_up_all_module_category_permissions(MEMBER member, ?ID_TEXT module)

For efficiency reasons, load up loads of category permissions.

Parameters…

Name member
Description The member being checked whether to have the access
Type MEMBER

Name module
Description The ID code for the module being checked for category access (NULL: all categories)
Default value
Type ?ID_TEXT

(No return value)


Return to the function index for this class Expand: View the source code to this function

boolean has_category_access(MEMBER member, ID_TEXT module, ID_TEXT category)

Find if a member's has access to a specified category

Parameters…

Name member
Description The member being checked whether to have the access
Type MEMBER

Name module
Description The ID code for the module being checked for category access
Type ID_TEXT

Name category
Description The ID code for the category being checked for access (often, a number cast to a string)
Type ID_TEXT

Returns…

Description Whether the member has category access
Type boolean

Return to the function index for this class Expand: View the source code to this function

?string _get_where_clause_groups(MEMBER member)

Get the SQL WHERE clause to select for any the given member is in (gets combined with some condition, to check against every).

Parameters…

Name member
Description The member who's usergroups will be OR'd
Type MEMBER

Returns…

Description The SQL query fragment (NULL: admin, so permission regardless)
Type ?string

Return to the function index for this class Expand: View the source code to this function

void enforce_personal_access(MEMBER member_id, ?ID_TEXT permission, ?ID_TEXT permission2, ?MEMBER member_viewing)

Only allow members here that are either the give member, admins, or have a privilege. All other members come up to an error message wall.

Parameters…

Name member_id
Description The member who typically (i.e. when it's not an administrative override) we want the current member to be.
Type MEMBER

Name permission
Description The override permission the current member must have (NULL: no general override).
Default value
Type ?ID_TEXT

Name permission2
Description An alternative permission to the 'assume_any_member' permission (NULL: no override).
Default value
Type ?ID_TEXT

Name member_viewing
Description The member who is doing the viewing (NULL: current member).
Default value
Type ?MEMBER

(No return value)


Return to the function index for this class Expand: View the source code to this function

void check_specific_permission(ID_TEXT permission, ?array cats, ?MEMBER member_id)

Require presence of a permission for the current member; otherwise exit.

Parameters…

Name permission
Description The permission to require
Type ID_TEXT

Name cats
Description A list of cat details to require access to (c-type-1,c-id-1,c-type-2,c-d-2,...) (NULL: N/A)
Default value
Type ?array

Name member_id
Description Member to check for (NULL: current user)
Default value
Type ?MEMBER

(No return value)


Return to the function index for this class Expand: View the source code to this function

boolean has_some_cat_specific_permission(MEMBER member, ID_TEXT permission, ?ID_TEXT page, ID_TEXT permission_module)

Find if a member has a specified permission in any category

Parameters…

Name member
Description The member being checked whether to have the permission
Type MEMBER

Name permission
Description The ID code for the permission being checked for
Type ID_TEXT

Name page
Description The ID code for the page being checked (NULL: current page)
Type ?ID_TEXT

Name permission_module
Description The ID code for the permission module being checked for
Type ID_TEXT

Returns…

Description Whether the member has the permission
Type boolean

Return to the function index for this class Expand: View the source code to this function

boolean has_specific_permission(MEMBER member, ID_TEXT permission, ?ID_TEXT page, ?array cats)

Find if a member has a specified permission

Parameters…

Name member
Description The member being checked whether to have the permission
Type MEMBER

Name permission
Description The ID code for the permission being checked for
Type ID_TEXT

Name page
Description The ID code for the page being checked (NULL: current page)
Default value
Type ?ID_TEXT

Name cats
Description A list of cat details to require access to (c-type-1,c-id-1,c-type-2,c-d-2,...) (NULL: N/A)
Default value
Type ?array

Returns…

Description Whether the member has the permission
Type boolean

Return to the function index for this class Expand: View the source code to this function

void check_submit_permission(string range, ?array cats, ?ID_TEXT page)

Check to see if a member's has permission to submit an item. If it doesn't, an error message is outputted.

Parameters…

Name range
Description The range of permission we are checking to see if they have; these ranges are like trust levels
Type string
Values restricted to low mid high cat_low cat_mid cat_high

Name cats
Description A list of cat details to require access to (c-type-1,c-id-1,c-type-2,c-d-2,...) (NULL: N/A)
Default value
Type ?array

Name page
Description The ID code for the page being checked (NULL: current page)
Default value
Type ?ID_TEXT

(No return value)


Return to the function index for this class Expand: View the source code to this function

boolean has_submit_permission(string range, MEMBER member, IP ip, ?ID_TEXT page, ?array cats)

Find if a member's has permission to submit

Parameters…

Name range
Description The range of permission we are checking to see if they have; these ranges are like trust levels
Type string
Values restricted to low mid high cat_low cat_mid cat_high

Name member
Description The member being checked whether to have the access
Type MEMBER

Name ip
Description The member's IP address
Type IP

Name page
Description The ID code for the page being checked (NULL: current page)
Type ?ID_TEXT

Name cats
Description A list of cat details to require access to (c-type-1,c-id-1,c-type-2,c-d-2,...) (NULL: N/A)
Default value
Type ?array

Returns…

Description Whether the member can submit in this range
Type boolean

Return to the function index for this class Expand: View the source code to this function

void check_some_edit_permission(string range, ?array cats)

Check to see if a member's has permission to edit an item. If it doesn't, an error message is outputted.

Parameters…

Name range
Description The range of permission we are checking to see if they have; these ranges are like trust levels
Type string
Values restricted to low mid high cat_low cat_mid cat_high

Name cats
Description A list of cat details to require access to (c-type-1,c-id-1,c-type-2,c-d-2,...) (NULL: N/A)
Default value
Type ?array

(No return value)


Return to the function index for this class Expand: View the source code to this function

void check_edit_permission(string range, ?MEMBER resource_owner, ?array cats, ?ID_TEXT page)

Check to see if a member's has permission to edit an item. If it doesn't, an error message is outputted.

Parameters…

Name range
Description The range of permission we are checking to see if they have; these ranges are like trust levels
Type string
Values restricted to low mid high cat_low cat_mid cat_high

Name resource_owner
Description The member that owns this resource (NULL: no-one)
Type ?MEMBER

Name cats
Description A list of cat details to require access to (c-type-1,c-id-1,c-type-2,c-d-2,...) (NULL: N/A)
Default value
Type ?array

Name page
Description The ID code for the page being checked (NULL: current page)
Default value
Type ?ID_TEXT

(No return value)


Return to the function index for this class Expand: View the source code to this function

boolean has_edit_permission(string range, MEMBER member, ?MEMBER resource_owner, ?ID_TEXT page, ?array cats)

Find if a member's has permission to edit

Parameters…

Name range
Description The range of permission we are checking to see if they have; these ranges are like trust levels
Type string
Values restricted to low mid high cat_low cat_mid cat_high

Name member
Description The member being checked for access
Type MEMBER

Name resource_owner
Description The member that owns this resource (NULL: no-one)
Type ?MEMBER

Name page
Description The ID code for the page being checked (NULL: current page)
Type ?ID_TEXT

Name cats
Description A list of cat details to require access to (c-type-1,c-id-1,c-type-2,c-d-2,...) (NULL: N/A)
Default value
Type ?array

Returns…

Description Whether the member may edit the resource
Type boolean

Return to the function index for this class Expand: View the source code to this function

void check_delete_permission(string range, ?MEMBER resource_owner, ?array cats, ?ID_TEXT page)

Check if a member's has permission to delete a specific resource. If it doesn't, an error message is outputted.

Parameters…

Name range
Description The range of permission we are checking to see if they have; these ranges are like trust levels
Type string
Values restricted to low mid high cat_low cat_mid cat_high

Name resource_owner
Description The member that owns this resource (NULL: no-one)
Type ?MEMBER

Name cats
Description A list of cat details to require access to (c-type-1,c-id-1,c-type-2,c-d-2,...) (NULL: N/A)
Default value
Type ?array

Name page
Description The ID code for the page being checked (NULL: current page)
Default value
Type ?ID_TEXT

(No return value)


Return to the function index for this class Expand: View the source code to this function

boolean has_delete_permission(string range, MEMBER member, ?MEMBER resource_owner, ?ID_TEXT page, ?array cats)

Check to see if a member's has permission to delete a specific resource

Parameters…

Name range
Description The range of permission we are checking to see if they have; these ranges are like trust levels
Type string
Values restricted to low mid high cat_low cat_mid cat_high

Name member
Description The member being checked for access
Type MEMBER

Name resource_owner
Description The member that owns this resource (NULL: no-one)
Type ?MEMBER

Name page
Description The ID code for the page being checked (NULL: current page)
Type ?ID_TEXT

Name cats
Description A list of cat details to require access to (c-type-1,c-id-1,c-type-2,c-d-2,...) (NULL: N/A)
Default value
Type ?array

Returns…

Description Whether the member may delete the resource
Type boolean

Return to the function index for this class Expand: View the source code to this function

Tutorial - Adding a Permission


Adding a permission is quite important if you want to stop some people from doing something…you will need a module, and something to protect.

1) In the install function for your module, add the following code to actually add the permission:

Code (php)

add_specific_permission('FOO_SECTION','allowed_access_foobar',false);

That code adds the permission 'allowed_access_foobar' to a section of options named 'FOO_SECTION', and sets it to false for every usergroup.

2) To check if someone's usergroup has this permission, use the following code:

Code (php)

if (has_specific_permission(get_member(),'allowed_access_foobar')) {

That code checks to see if the member has the permission. Things get more complex if the permission may be overrided by pages or categories.