Documentation

CRM_Core_Error extends PEAR_ErrorStack
in package

CRM

Class CRM_Core_Error

Constants

DUPLICATE_CONTACT = 8001
DUPLICATE_CONTRIBUTION = 8002
DUPLICATE_PARTICIPANT = 8003
FATAL_ERROR = 2: Status code of various types of errors.

Properties

$modeException : bool: If modeException == true, errors are raised as exception instead of returning civicrm_errors
$_log : object: The logger object for this application.
$_singleton : object: We only need one instance of this object. So we use the singleton pattern and cache the instance in this variable

Methods

__construct() : mixed: Constructor.
backtrace() : mixed
createAPIError() : array<string|int, mixed>
createDebugLogger() : Log_file: Obtain a reference to the error log.
createError() : object
debug() : string: Outputs pre-formatted debug information. Flushes the buffers so we can interrupt a potential POST/redirect
debug_log_message() : string: Display the error message on terminal and append it to the log file.
debug_query() : mixed: Append to the query log (if enabled)
debug_query_result() : mixed: Execute a query and log the results.
debug_var() : string: Similar to the function debug. Only difference is in the formatting of the output.
deprecatedFunctionWarning() : void: Output a deprecated function warning to log file.
deprecatedWarning() : mixed: Output a deprecated notice about a deprecated call path, rather than deprecating a whole function.
displaySessionError() : mixed: Status display function specific to payment processor errors.
exceptionHandler() : mixed: PEAR error-handler which converts errors to exceptions
fatal() : mixed: Display an error page with an error message describing what happened.
formatBacktrace() : string: Render a backtrace array as a string.
formatHtmlException() : string: Render an exception as HTML string.
formatTextException() : string: Write details of an exception to the log.
generateLogFileHash() : string: Generate a hash for the logfile.
generateLogFileName() : string: Generate the name of the logfile to use and store it as a static.
getErrorDetails() : array<string|int, mixed>: This function is used to return error details
getMessages() : array<string|int, mixed>|null|string
handle() : mixed: Create the main callback method. this method centralizes error processing.
handlePES() : int: Handle errors raised using the PEAR Error Stack.
handleUnhandledException() : mixed: Display an error page with an error message describing what happened.
isAPIError() : bool
movedSiteError() : mixed
nullHandler() : object: PEAR error-handler to quietly catch otherwise fatal errors. Intended for use with smtp transport.
parseBacktrace() : array<string|int, mixed>: Render a backtrace array as an array.
reset() : mixed: Reset the error stack.
simpleHandler() : mixed: this function is used to trap and print errors during system initialization time. Hence the error message is quite ugly
singleton() : CRM_Core_Error: Singleton function used to manage this object.
statusBounce() : mixed: Set a status message in the session, then bounce back to the referrer.
abend() : mixed: Terminate execution abnormally.
inpageExceptionDisplay() : mixed: Show in-page exception For situations where where calling abend will block the ability for a branded error screen

DUPLICATE_CONTACT


    public
        mixed
    DUPLICATE_CONTACT
    = 8001

DUPLICATE_CONTRIBUTION


    public
        mixed
    DUPLICATE_CONTRIBUTION
    = 8002

DUPLICATE_PARTICIPANT


    public
        mixed
    DUPLICATE_PARTICIPANT
    = 8003

FATAL_ERROR

Status code of various types of errors.


    public
        mixed
    FATAL_ERROR
    = 2

$modeException

If modeException == true, errors are raised as exception instead of returning civicrm_errors


    public
    static    bool
    $modeException
     = \NULL

$_log

The logger object for this application.


    private
    static    object
    $_log
     = \NULL

$_singleton

We only need one instance of this object. So we use the singleton pattern and cache the instance in this variable


    private
    static    object
    $_singleton
     = \NULL

__construct()

Constructor.


    public
                    __construct() : mixed

backtrace()


    public
            static        backtrace([string $msg = 'backTrace' ][, bool $log = FALSE ]) : mixed

Parameters

$msg : string = 'backTrace'
$log : bool = FALSE

createAPIError()


    public
            static    &    createAPIError(mixed $msg[, null $data = NULL ]) : array<string|int, mixed>

This function is no longer used by v3 api.

Parameters

$msg : mixed
$data : null = NULL

Return values

array<string|int, mixed>

createDebugLogger()

Obtain a reference to the error log.


    public
            static        createDebugLogger([string $prefix = '' ]) : Log_file

Parameters

$prefix : string = ''

Return values

Log_file

createError()


    public
            static        createError(mixed $message[, int $code = 8000 ][, string $level = 'Fatal' ][, array<string|int, mixed> $params = NULL ]) : object

Parameters

$message : mixed
$code : int = 8000
$level : string = 'Fatal'
$params : array<string|int, mixed> = NULL

Return values

object

debug()

Outputs pre-formatted debug information. Flushes the buffers so we can interrupt a potential POST/redirect


    public
            static        debug(string $name[, mixed $variable = NULL ][, bool $log = TRUE ][, bool $html = TRUE ][, bool $checkPermission = TRUE ]) : string

prefer Civi::log().

Parameters

$name : string

name of debug section

$variable : mixed = NULL

reference to variables that we need a trace of

$log : bool = TRUE

TRUE: log to error_log and echo one of: everything / a code / nothing, depending on permissions.
FALSE: only return the output as a string. Nothing to error_log or echo.

$html : bool = TRUE

whether to HTML-escape output (typically use TRUE unless you know your $variable is safe)

$checkPermission : bool = TRUE

should we check permissions before displaying output useful when we die during initialization and permissioning subsystem is not initialized - CRM-13765

Return values

string —

the generated output

debug_log_message()

Display the error message on terminal and append it to the log file.


    public
            static        debug_log_message(string $message[, bool $out = FALSE ][, string $prefix = '' ][, string $priority = NULL ]) : string

see https://docs.civicrm.org/dev/en/latest/framework/logging/

Use (e.g) Civi::log()->error() (priority dependent).

Provided the user has the 'view debug output' the output should be displayed. In all cases it should be logged.

Parameters

$message : string
$out : bool = FALSE: Should we log or return the output.
$prefix : string = '': Message prefix.
$priority : string = NULL

Return values

string —

Format of the backtrace

debug_query()

Append to the query log (if enabled)


    public
            static        debug_query(string $string) : mixed

Parameters

$string : string

debug_query_result()

Execute a query and log the results.


    public
            static        debug_query_result(string $query) : mixed

Parameters

$query : string

debug_var()

Similar to the function debug. Only difference is in the formatting of the output.


    public
            static        debug_var(string $variable_name, mixed $variable[, bool $print = TRUE ][, bool $log = TRUE ][, string $prefix = '' ][, int $priority = NULL ]) : string

Parameters

$variable_name : string: Variable name.
$variable : mixed: Variable value.
$print : bool = TRUE: Use print_r (if true) or var_dump (if false).
$log : bool = TRUE: Log or return the output?
$prefix : string = '': Prefix for output logfile.
$priority : int = NULL: The log priority level.

Return values

string —

The generated output

deprecatedFunctionWarning()

Output a deprecated function warning to log file.


    public
            static        deprecatedFunctionWarning(string $newMethod[, string|null $oldMethod = NULL ]) : void

Deprecated class:function is automatically generated from calling function.

Parameters

$newMethod : string: description of new method (eg. "buildOptions() method in the appropriate BAO object").
$oldMethod : string|null = NULL: optional description of old method (if not the calling method). eg. CRM_MyClass::myOldMethodToGetTheOptions()

deprecatedWarning()

Output a deprecated notice about a deprecated call path, rather than deprecating a whole function.


    public
            static        deprecatedWarning(string $message) : mixed

Parameters

$message : string

displaySessionError()

Status display function specific to payment processor errors.


    public
            static        displaySessionError(mixed &$error[, string $separator = '<br />' ]) : mixed

Parameters

$error : mixed
$separator : string = '<br />'

exceptionHandler()

PEAR error-handler which converts errors to exceptions


    public
            static        exceptionHandler(PEAR_Error $pearError) : mixed

Parameters

$pearError : PEAR_Error

fatal()

Display an error page with an error message describing what happened.


    public
            static        fatal([string $message = NULL ][, string $code = NULL ][, string $email = NULL ]) : mixed

This is a really annoying function. We ❤ exceptions. Be exceptional!

Parameters

$message : string = NULL: The error message.
$code : string = NULL: The error code if any.
$email : string = NULL: The email address to notify of this situation.

formatBacktrace()

Render a backtrace array as a string.


    public
            static        formatBacktrace(array<string|int, mixed> $backTrace[, bool $showArgs = TRUE ][, int $maxArgLen = 80 ]) : string

Parameters

$backTrace : array<string|int, mixed>: Array of stack frames.
$showArgs : bool = TRUE: TRUE if we should try to display content of function arguments (which could be sensitive); FALSE to display only the type of each function argument.
$maxArgLen : int = 80: Maximum number of characters to show from each argument string.

Return values

string —

printable plain-text

formatHtmlException()

Render an exception as HTML string.


    public
            static        formatHtmlException(Throwable $e) : string

Parameters

$e : Throwable

Return values

string —

printable HTML text

formatTextException()

Write details of an exception to the log.


    public
            static        formatTextException(Throwable $e) : string

Parameters

$e : Throwable

Return values

string —

printable plain text

generateLogFileHash()

Generate a hash for the logfile.


    public
            static        generateLogFileHash(CRM_Core_Config $config) : string

CRM-13640.

Parameters

$config : CRM_Core_Config

Return values

string

generateLogFileName()

Generate the name of the logfile to use and store it as a static.


    public
            static        generateLogFileName(string $prefix) : string

This function includes simplistic log rotation and a check as to whether the file exists.

Parameters

$prefix : string

Return values

string —

The full path to the file.

getErrorDetails()

This function is used to return error details


    public
            static        getErrorDetails(PEAR_Error $pearError) : array<string|int, mixed>

Parameters

$pearError : PEAR_Error

Return values

array<string|int, mixed> —

$error

getMessages()


    public
            static        getMessages(mixed &$error[, string $separator = '<br />' ]) : array<string|int, mixed>|null|string

Parameters

$error : mixed
$separator : string = '<br />'

Return values

array<string|int, mixed>|null|string

handle()

Create the main callback method. this method centralizes error processing.


    public
            static        handle(object $pearError) : mixed

the errors we expect are from the pear modules DB, DB_DataObject which currently use PEAR::raiseError to notify of error messages.

Parameters

$pearError : object: PEAR_Error

handlePES()

Handle errors raised using the PEAR Error Stack.


    public
            static        handlePES(mixed $pearError) : int

currently the handler just requests the PES framework to push the error to the stack (return value PEAR_ERRORSTACK_PUSH).

Note: we can do our own error handling here and return PEAR_ERRORSTACK_IGNORE.

Also, if we do not return any value the PEAR_ErrorStack::push() then does the action of PEAR_ERRORSTACK_PUSHANDLOG which displays the errors on the screen, since the logger set for this error stack is 'display' - see CRM_Core_Config::getLog();

Parameters

$pearError : mixed

Return values

int

handleUnhandledException()

Display an error page with an error message describing what happened.


    public
            static        handleUnhandledException(Exception $exception) : mixed

This function is evil -- it largely replicates fatal(). Hopefully the entire CRM_Core_Error system can be hollowed out and replaced with something that follows a cleaner separation of concerns.

Parameters

$exception : Exception

isAPIError()


    public
            static        isAPIError(array<string|int, mixed> $error[, int $type = CRM_Core_Error::FATAL_ERROR ]) : bool

Parameters

$error : array<string|int, mixed>
$type : int = CRM_Core_Error::FATAL_ERROR

Return values

bool

movedSiteError()


    public
            static        movedSiteError(mixed $file) : mixed

Parameters

$file : mixed

nullHandler()

PEAR error-handler to quietly catch otherwise fatal errors. Intended for use with smtp transport.


    public
            static        nullHandler(object $obj) : object

Parameters

$obj : object: The PEAR_ERROR object.

Return values

object —

$obj

parseBacktrace()

Render a backtrace array as an array.


    public
            static        parseBacktrace(array<string|int, mixed> $backTrace[, bool $showArgs = TRUE ][, int $maxArgLen = 80 ]) : array<string|int, mixed>

Parameters

$backTrace : array<string|int, mixed>: Array of stack frames.
$showArgs : bool = TRUE: TRUE if we should try to display content of function arguments (which could be sensitive); FALSE to display only the type of each function argument.
$maxArgLen : int = 80: Maximum number of characters to show from each argument string.

Return values

array<string|int, mixed>

reset()

Reset the error stack.


    public
            static        reset() : mixed

simpleHandler()

this function is used to trap and print errors during system initialization time. Hence the error message is quite ugly


    public
            static        simpleHandler(mixed $pearError) : mixed

Parameters

$pearError : mixed

singleton()

Singleton function used to manage this object.


    public
            static    &    singleton([null $package = NULL ][, bool $msgCallback = FALSE ][, bool $contextCallback = FALSE ][, bool $throwPEAR_Error = FALSE ][, string $stackClass = 'PEAR_ErrorStack' ]) : CRM_Core_Error

Parameters

$package : null = NULL
$msgCallback : bool = FALSE
$contextCallback : bool = FALSE
$throwPEAR_Error : bool = FALSE
$stackClass : string = 'PEAR_ErrorStack'

Return values

CRM_Core_Error

statusBounce()

Set a status message in the session, then bounce back to the referrer.


    public
            static        statusBounce(string $status[, string|null $redirect = NULL ][, string|null $title = NULL ]) : mixed

Parameters

$status : string: The status message to set.
$redirect : string|null = NULL
$title : string|null = NULL

abend()

Terminate execution abnormally.


    protected
            static        abend(int $code) : mixed

Parameters

$code : int

inpageExceptionDisplay()

Show in-page exception For situations where where calling abend will block the ability for a branded error screen


    protected
            static        inpageExceptionDisplay(string $code) : mixed

Although the host page will run past this point, CiviCRM should not, therefore we trigger the civi.exit events

Parameters

$code : string

CRM_Core_Error extends PEAR_ErrorStack in package CRM

Table of Contents

Constants

Properties

Methods

Constants

DUPLICATE_CONTACT

DUPLICATE_CONTRIBUTION

DUPLICATE_PARTICIPANT

FATAL_ERROR

Properties

$modeException

$_log

$_singleton

Methods

__construct()

backtrace()

Parameters

createAPIError()

Parameters

Tags

Return values

createDebugLogger()

Parameters

Return values

createError()

Parameters

Return values

debug()

Parameters

Tags

Return values

debug_log_message()

Parameters

Return values

debug_query()

Parameters

debug_query_result()

Parameters

debug_var()

Parameters

Tags

Return values

deprecatedFunctionWarning()

Parameters

deprecatedWarning()

Parameters

displaySessionError()

Parameters

exceptionHandler()

Parameters

Tags

fatal()

Parameters

Tags

formatBacktrace()

Parameters

Return values

formatHtmlException()

Parameters

Return values

formatTextException()

Parameters

Return values

generateLogFileHash()

Parameters

Return values

generateLogFileName()

Parameters

Return values

getErrorDetails()

Parameters

Return values

getMessages()

Parameters

Return values

handle()

Parameters

handlePES()

Parameters

CRM_Core_Error extends PEAR_ErrorStack
in package

CRM