Team LiB
Previous Section Next Section

The Default Error Handler

PHP's default error handler relies on several php.ini options to instruct it on what to do when an error is raised. These options include the following:

error_reporting

A bit mask of the E_ERRORLEVEL constants previously listed, which will be processed by the internal error handler.

display_errors

Errors whose severity is included in error_reporting (except startup errors) will be output to the screen or browser.

display_startup_errors

When this and display_errors are set to on, errors that occur during startup will be output as well.

log_errors

Errors whose severity is included in error_reporting (including startup errors) will be written to a log file specified by error_log.

log_errors_max_len

Specifies the maximum length, in characters, to write to error_log for any given error message.

ignore_repreated_errors

Any error message which is raised multiple times in a row is output or logged only once.

ignore_repeated_source

Similar to ignore_repeated_errors, this setting will ignore multiple errors generated from the same source file and line number, regardless of message content.

TRack_errors

The most recently reported error will be populated into the $php_errmsg variable in the local scope.

html_errors

When this and display_errors are set to on, but xmlrpc_errors is not, error messages will be marked up with HTML tags for display in a Web browser.

xmlrpc_errors

When this and display_errors are set to on, error messages will be marked up in XMLRPC error-response format.

docref_root

URL to the base of a website containing PHP documentation. When set, and display_errors is on, a link referring to the function that reported the error will be output.

docref_ext

Filename extension to append to links generated when docref_root is also used.

error_prepend_string

An arbitrary string to add to the beginning of errors output by display_errors.

error_append_string

Counterpart to error_prepend_string, will be output at the end of errors output by display_errors.


If ignore_repeated_errors is enabled, the first thing PHP's error handler does is to check whether the current error message is a repeat of the last one. If it is, or if the origin (file and line) of the error is the same and ignore_repeated_source is also enabled, PHP does exactly as the ini option suggests it would: It ignores the error and continues processing, or halts execution if the error was fatal.

Next, the default error handler checks whether track_errors is enabled and, if so, sets the variable $php_errmsg in the local scope to the text of the error message just raised.

Further handling of the error depends on the setting error_reporting, which tells PHP which errors should be handled and which should be ignored outright. The error_reporting directive is a bit mask made up of zero or more of the error levels mentioned earlier joined together using the bitwise operations. Note, however, that core errors (E_CORE_WARNING and E_CORE_ERROR) cannot be ignored using this setting. PHP's internal error handler will always continue handling them.

error_reporting=E_ERROR | E_CORE_ERROR | E_COMPILE_ERROR | E_PARSE | E_USER_ERROR

The setting above tells PHP's default error handler to deal only with fatal errors and to ignore everything else. We could have left E_CORE_ERROR out of the preceding list because it's never ignored, but it's best to be explicit where possible to avoid any unexpected behavior down the road. Informational and actionable errors will have no effect.

error_reporting = E_ALL

The E_ALL constant is a special value that represents every error level except E_STRICT. With this line in your php.ini, all error conditions except E_STRICT messages will be handled by the default error handler.

error_reporting = E_ALL & ~E_NOTICE

The default php.ini settings for error reporting include all error types except E_STRICT and E_NOTICE using the preceding syntax. The symbols given translate in human speak to "E_ALL and not E_NOTICE," or "Everything that's normally part of E_ALL except for E_NOTICE." Because E_ALL already excludes E_STRICT, this gives us all fatal and actionable errors, plus the user-generated informational error E_USER_NOTICE.

After it has decided whether to handle a particular error, PHP needs to know what to do with it. The settings display_errors and log_errors can be enabled to output a formatted message and/or write a message to an error_log, respectively. display_errors will not, by itself, display errors that occur during startup. To show startup errors, you must enable both display_errors and display_startup_errors. However, many administrators prefer to find startup errors in the error_log.

Errors can be output by display_errors in one of three formats: plain text, HTML, and XML. By default, PHP scripts run from the command line will output in plain text, whereas scripts run via a Web server will output in HTML.

When xmlrpc_errors is enabled, a typical error message might look like this:

<?xml version="1.0"?>
<methodResponse>
 <fault>
 <value>
  <struct>
  <member>
   <name>faultCode</name>
   <value><int>2</int></value>
  </member>
  <member>
   <name>faultString</name>
   <value>
   <string>Warning: Unable to open myfile.txt for reading in /home/
jdoe/public_html/myscript.php on line 42</string>
   </value>
  </member>
  </struct>
 </value>
 </fault>
</methodResponse>

Otherwise, PHP checks the value of html_errors. If enabled, the output would look like the following:

<br />
<b>Warning</b>: Unable to open myfile.txt for reading in <b>/home/jdoe/public_html/
myscript.php</b> on line <b>42</b><br />

If html_errors is not enabled, the same message is output, but without the markup tags. The plain text and HTML versions will also add the contents of error_prepend_string and error_append_string to the beginning and end of the message output respectively.

Next, if log_errors is enabled, PHP will construct an error message similar to the plain-text version, but not including the error_prepend_string or error_append_string values, and append it to the end of the file specified by error_log. If error_log is empty, PHP will ask your Web server to handle it, or output it to stderr when using the CLI or CGI versions of PHP. If error_log is set to syslog and your system supports the concept of a syslog, it will be used; otherwise, PHP will attempt to open the filename provided and append the error string to its contents.

You may also write information to the error log, taking advantage of the same mechanism used by PHP through the use of the error_log() function whose prototype is as follows:

bool error_log(string $message[, int $message_type[,
 string $destination[, string $extra_headers]]])

When none of the optional parameters are specified, or when 0 is given for message_type, error_log() sends its message to the same error log used by PHP's internal error handler (as described previously and depending on the value of the php.ini option error_log). error_log() may also be used to send email or append to an alternative log file. See the online manual for more information on the usage of error_log().

    Team LiB
    Previous Section Next Section