Developer Area/Pagetop Constants

Mahara uses a diverse range of PHP constants defined at the beginning of the script, to define the script's behavior or provide metadata. This page attempts to be a comprehensive list of these constants and what they do.

Note: By all means make use of the existing set of page-top constants, but please avoid creating new ones whenever possible. They're a form of global variable, and as such they bring all the associated problems with them. They also tend not to be well-documented, because there's no central place in the code where they have to be used.

General purpose

INTERNAL

This backwards-named constant tells Mahara that it's okay to access this page externally.

Every Mahara script that is meant to be addressed directly by a web browser (or other HTTP client) should define it as its very first PHP statement, even before including init.php.

define('INTERNAL', 1);

Conversely, every "library" script which is not meant to be addressed directly by a web browser, should begin with this:

defined('INTERNAL') || die();

Admin pages

These constants control who can access the page. If any of them is set, the logged-in user will be checked for appropriate access control in the auth_setup() method called by init.php. If they lack appropriate credentials, they'll see a warning message.

Note that you can only set one of these values on any page. If more than one is defined, only the most restrictive one will have effect and the others will be ignored. (See the auth_check_admin_section() method for the actual implementatoin.)

Setting any of these constants also tells the Mahara main_nav() method that you are in Mahara's "admin section", and it will then show you the appropriate admin menu depending on whether you are a site admin, site staff, institution admin, or institution staff. It also sets a smarty flag with the same name as the constant, which can be used to style the admin section differently than normal pages.

ADMIN

define('ADMIN', 1);

Indicates that this page should only be accessible to Site Administrators.

STAFF

define('STAFF', 1);

Indicates that this page should only be accessible to Site Staff (and Site Admins).

INSTITUTIONALADMIN

define('INSTITUTIONALADMIN', 1);

Indicates that this page should only be accessible to Institution Admins (and Site Admins).

INSTITUTIONALSTAFF

define('INSTITUTIONALSTAFF', 1);

Indicates that this page should be accessible to Institution Staff (and Site Admins, Site Staff, and Institutional Admins).

Script type

PUBLIC

define('PUBLIC', 1);

Indicates that this page may be accessible to non-logged-in users. If this flag is not set, then any non-logged-in user will be sent to the transient login page when they try to access it.

A page that might sometimes be visible to the public (for instance, view/view.php, which shows a single portfolio page) should set this flag and manually throw an AccessDeniedException if it turns out the particular data requested is not publicly visible.

CRON

define('CRON', 1);

This flag should only be set by the main Mahara cron job. Its presence indicates that the method is being called by the Mahara cron job. This causes authentication checks to be bypassed and some display measures to be avoided.

INSTALLER

define('INSTALLER', 1);

Indicates that this page is part of the Mahara installation process. Causes some parts of the normal page-load to be skipped, because the data for them will not yet be present.

CLI

define('CLI', 1);

Indicates that this script is meant to be executed as a command-line script. This causes Mahara to skip authentication checks and other things incompatible with the command-line interface.

JSON

define('JSON', 1);

Indicates that this script is meant to be called by a web service, and its only output should be well-formatted JSON. This prevents certain automated responses from being printed to the HTTP output, as that would break the JSON.

NOSESSKEY

define('NOSESSKEY', 1);

A flag to use in conjunction with the JSON flag. Most JSON requests require a "sesskey" variable to passed along with them. This is a unique key used in Mahara forms and other operations that cause data to be changed, and is used in order to prevent attacks based on sending a user to a URL.

For JSON operations that are not changing data (for instance, displaying Help pop-ups), this flag should be set so that the sesskey will not be checked for.

XMLRPC

define('XMLRPC', 1);

Indicates that this script is meant to be called by a web service using XMLRPC, and its output should consist entirely of well-formatted XMLRPC.

TESTSRUNNING

define ('TESTSRUNNING', 1);

Indicates that this script is a PHPUnit test, allowing for different behavior to support unit tests.

Layout / Headings

TITLE

define ('TITLE', 1);

Indicates both the title of the page (what appears in the titlebar of the browser) and the page's <h1> heading. The <h1> heading can be overwritten by defining $smarty->assign('PAGEHEADING', get_string('somenewheading', 'mahara'));

All PHP pages that call $smarty->display() should have a TITLE defined.

SUBSECTIONHEADING

define ('SUBSECTIONHEADING', 1);

Indicates a subtitle of the page (where appropiate) for the page's <h1> heading. For example the pages list page for "Group 1" would have the SUBSECTIONHEADING and TITLE pairing of "Pages | Group 1".

And more...

This list is incomplete and is a work in progress. Please feel free to document other pagetop constants here as well. There are also some used for navigation and help files, for instance.