zAuthBase

This is the base class of zoglair “authorities”, commonly known as session handlers. One reason for subclassing this, is for having zoglair authenticate against a hosted or 3rd party environment.

These are the requirements expected from descendants:

1. Implement the stubs (they can also override methods as needed, ie login)
2. Save their info under the 'z_row' key. Expected and used fields are:
   - 'captcha'  string for the currently expected response
   - 'runAs'    active security level
   - 'udf'      array holding user defined session variables
   - 'user'     array holding the user record (must remap their own user columns according to zoglair's table)

A descendant of this class is instantiated as the globally available $zAuth object, based on the relevant authority setting.

Parent Class

zObject

Public Methods ⁽²⁰⁾

__construct, authenticate, can_user, captcha, generate_captcha_text, get_cookie_domain, get_udf, get_user, get_user_id, get_user_row, get_user_sevel, get_user_tzo, is_super_user, is_user, login, logout, run_as, save_session, set_udf, set_user

Protected Methods

none

void __construct(array $INFO)‎ ⇧

Descendants should initialize session, here. At the time this is called $zDbms (global database manager) is already instantiated.

Parameters

Initial object properties (see zObject's constructor)

Returns

void

boolean authenticate()‎ ⇧

HTTP authenticates a session, according to the relevant authority settings.

Parameters

none

Returns

TRUE for success, FALSE for failure

boolean can_user(string $action, array $ROW=NULL, object $Table=NULL)‎ ⇧

A vital function for checking various, system-wide user privileges. If you want to know whether a user is allowed to do something, this is the place to ask.

Parameters

• The action/privilege to check for

• If the action is an access right to a table, this is a particular ROW to be checked against (optional)

• If the action is an access right to a table, this is the table instance to be queried

Returns

TRUE if user has the requested privilege, FALSE if not

mixed captcha(string $what, string $value='')‎ ⇧

Generates and validates captchas, according to the relevant authority settings.

Parameters

• One of the following actions:

• 'init'   initializes the captcha engine (must be called every time a captcha is used)
• 'prompt' returns the appropriate captcha prompt
• 'imgx'   returns the image captcha extension chosen (if applicable)
• 'answer' returns the correct answer
• 'check'  checks the passed $value against the correct answer

• The user's answer to be checked against the generated captcha

Returns

TRUE for 'init', TRUE/FALSE for 'check', a string for the rest of the supported actions

string generate_captcha_text(integer $len, string $chrs)‎static ⇧

Generates a random string of a given length and character set.

Parameters

• The required string length

• The character set

Returns

The string requested

mixed get_cookie_domain()‎static ⇧

Returns the domain argument of a cookie value. If localhost, then FALSE is returned, otherwise subdomain is stripped (ie no 'www.').

Parameters

none

Returns

FALSE (for localhost) or 'domain.tld'

mixed get_udf(string $info='', mixed $default='')‎ ⇧

A zObject::get_info() wrapper, to return user defined session variables, saved under the 'z_row/udf' key, as mentioned in the class description.

Parameters

• The name of the requested variable

• A default value for unset variables

Returns

The value of the variable requested

See also set_udf().

mixed get_user(string $info='', mixed $default='')‎ ⇧

A zObject::get_info() wrapper, to return column values from the active user record, saved under the 'z_row/user' key, as mentioned in the class description.

Parameters

• The name of the requested column value, eg: “name”, “email”, etc. A special (fabricated) column is supported, for returning the active user name and run_as() level, named “name+runas”.

• A default value for unset columns

Returns

The value of the column requested

See also set_user().

integer get_user_id()‎ ⇧

A shortcut for $zAuth->get_user('id').

Parameters

none

Returns

The active (logged in) user's id

array get_user_row(mixed $mixed=NULL)‎static ⇧

Loads a row (~record) from the User table and returns it as a map.

Parameters

NULL (to get an empty user row), integer (user id), string (user name) or map (user row)

Returns

The requested row (if found), or zDbmsBase::Z_ERROR

integer get_user_sevel(boolean $real=FALSE)‎ ⇧

A wrapper of $zAuth->get_user('sevel'). It is HIGHLY recommended to use this function, instead of a direct access, because it takes care of properly adjusting for system maintenance and the user's run_as() level.

Parameters

Set to TRUE to get the real security level, instead of the active one (the default)

Returns

The active (logged in) user's sevel, real or active, depending on $real

integer get_user_tzo(boolean $secs=TRUE)‎ ⇧

A wrapper of $zAuth->get_user('tzo'). It is highly recommended to use this function, instead of a direct access, because it takes care of properly adjusting for negative TZOs.

Parameters

Set to FALSE to get the TZO in minutes, instead of seconds (the default)

Returns

The active (logged in) user's TZO, in minutes or seconds, depending on $secs

boolean is_super_user()‎ ⇧

Checks whether the active session belongs to the super user (the webmaster of the default domain).

Parameters

none

Returns

TRUE if the active visitor is a super user, FALSE if not

boolean is_user()‎ ⇧

Checks whether the active session belongs to a user or a guest.

Parameters

none

Returns

TRUE if the active visitor is a registered (and logged in) user, FALSE if not (he is a guest)

boolean login(array $INFO)‎ ⇧

Attempts to login a user by first finding an account with matching credentials, and then ensuring that the account is activated and not banned.

Parameters

A map with the following keys:

• 'name' the user name
• 'hash' the user password hash or clear text

Returns

TRUE if login was successful, FALSE if not

void logout()‎ ⇧

Clears the active session, effectively logging the user out.

Parameters

none

Returns

void

void run_as(integer $sevel)‎ ⇧

Changes the security level of the active user. This is an invaluable tool for staff members that allows them to test various site features under the context of a less privileged user account.

Notice: The new security level stays in effect until changed or the user session is invalidated.

Parameters

The new security level under which the active user will run (it cannot be higher than the real one)

Returns

void

void save_session(string $reason='')‎ ⇧

This is called from zoglair.php, just before output. Descendants should store any changes (ie user preferences and selections) or simply update their timestamp, for keeping up with online status and session timeouts.

Notice: This is a stub

Parameters

Active content's title

Returns

void

void set_udf(string $info, mixed $value)‎ ⇧

A zObject::set_info() wrapper, to set user defined session variables, saved under the 'z_row/udf' key, as mentioned in the class description.

Parameters

• The name of the variable to be set

• The variables's value

Returns

void

See also get_udf().

void set_user(string $info, mixed $value)‎ ⇧

A zObject::set_info() wrapper, to set column values in the active user record, saved under the 'z_row/user' key, as mentioned in the class description.

Parameters

• The name of the column to be set, eg: “name”, “email”, etc.

• The column's value

Returns

void

See also get_user().