phpBB

Development Wiki

Function.trigger error

From phpBB Development Wiki

Revision as of 18:39, 9 September 2008 by Mtrs (Talk | contribs)

trigger_error –– Generates a user-level error/warning/notice message or page.

Description

bool trigger_error ( string $error_msg [, int $error_type ] ) Used to trigger a user error condition and exiting the script. This function is useful when you need to generate a particular response to an exception at runtime. trigger_error() utilises the template: message_body.html in phpBB3.

Parameters

error_msg
The designated error message for this error. You can specify this message as simply the language key of a language variable, or a combination of text or language variables.

error_type
The designated error type for this error. It only works with the E_USER family of constants, and will default to E_USER_NOTICE. There are three error types that can be used: E_USER_NOTICE, E_USER_WARNING, and E_USER_ERROR.

E_USER_NOTICE (the default setting) is an "information" page. It's used for situations such as the message you receive upon completion of a post or logging in to phpBB3. In the ACP, E_USER_NOTICE displays a green information box.
E_USER_WARNING is used for warnings. On user-facing pages in the default phpBB3 styles, there is no visible difference between E_USER_NOTICE and E_USER_WARNING. In the ACP, E_USER_WARNING displays as a red “Error” box.
E_USER_ERROR should only be used for very severe errors, for example if sessions are unavailable. E_USER_ERROR is used for SQL Errors as an example. E_USER_ERROR displays a hard-coded error page for both user facing pages and within the ACP.

A simple overview

The trigger_error() function article on phpbbmodders


Trigger_error() is a function that can be used to stop everything in a php page or script and display a message. The "Information" message shown after adding a forum in the ACP is an example of trigger_error()

The general syntax for trigger_error() is the following.

trigger_error($message[, error_type])


$message is the error message you would like to be displayed. As phpBB 3.0 is multilingual it is possible to just specify the language key for $user->lang. If you need to connect messages though, you need to supply the full $user->lang variable (with key).

For example:

trigger_error('NO_MESSAGE');
trigger_error($user->lang['NO_MESSAGE'] . adm_back_link($this->u_action));


There are three error types that can be used: E_USER_NOTICE, E_USER_WARNING, and E_USER_ERROR. If none is specified, E_USER_NOTICE is used. They are used for differen't things. E_USER_NOTICE is a "information" page. It's used for things like the message you get after creating a post or logging in. E_USER_WARNING is for errors. On normal pages it doesn't really make a difference, but in the ACP it creates a pink message box instead of a green one. The third is E_USER_ERROR, this should only be used for very bad errors, for example if sessions are unavaillable. It is used for things like SQL errors, most MODs will not need it.

Examples

Example #1: Single language key example

if (!$result)
{
    
trigger_error('NO_RESULTS');
}

Example #2: Combined message and specified error type

$switch ($mode)
{
    
// [..]
    
default:
        
trigger_error($user->lang['NO_MODE'] . adm_back_link($this->u_action), E_USER_ERROR);
    break;
}



See Also