Errors and Logging These are functions dealing with error handling and logging. They allow you to define your own error handling rules, as well as modify the way the errors can be logged. This allows you to change and enhance error reporting to suit your needs. With the logging functions, you can send messages directly to other machines, to an email (or email to pager gateway!), to system logs, etc., so you can selectively log and monitor the most important parts of your applications and websites. The error reporting functions allow you to customize what level and kind of error feedback is given, ranging from simple notices to customized functions returned during errors. error_log send an error message somewhere int error_log string message int message_type string destination string extra_headers Sends an error message to the web server's error log, a TCP port or to a file. The first parameter, message, is the error message that should be logged. The second parameter, message_type says where the message should go: 0 message is sent to PHP's system logger, using the Operating System's system logging mechanism or a file, depending on what the error_log configuration directive is set to. 1 message is sent by email to the address in the destination parameter. This is the only message type where the fourth parameter, extra_headers is used. This message type uses the same internal function as Mail does. 2 message is sent through the PHP debugging connection. This option is only available if remote debugging has been enabled. In this case, the destination parameter specifies the host name or IP address and optionally, port number, of the socket receiving the debug information. 3 message is appended to the file destination. Remote debugging via TCP/IP is a PHP 3 feature that is not available in PHP 4. // Send notification through the server log if we can not // connect to the database. if (!Ora_Logon ($username, $password)) { error_log ("Oracle database not available!", 0); } // Notify administrator by email if we run out of FOO if (!($foo = allocate_new_foo()) { error_log ("Big trouble, we're all out of FOOs!", 1, "operator@mydomain.com"); } // other ways of calling error_log(): error_log ("You messed up!", 2, "127.0.0.1:7000"); error_log ("You messed up!", 2, "loghost"); error_log ("You messed up!", 3, "/var/tmp/my-errors.log"); error_reporting set which PHP errors are reported int error_reporting int level Sets PHP's error reporting level and returns the old level. The error reporting level is either a bitmask, or named constant. Using named constants is strongly encouraged to ensure compatibility for future versions. As error levels are added, the range of integers increases, so older integer-based error levels will not always behave as expected. error_reporting (55); // PHP 3 equivalent to E_ALL ^ E_NOTICE /* ...in PHP 4, '55' would mean (E_ERROR | E_WARNING | E_PARSE | E_CORE_ERROR | E_CORE_WARNING) */ error_reporting (2039); // PHP 4 equivalent to E_ALL ^ E_NOTICE error_reporting (E_ALL ^ E_NOTICE); // The same in both PHP 3 and 4 Follow the links for the internal values to get their meanings: constant value 1 E_ERROR 2 E_WARNING 4 E_PARSE 8 E_NOTICE 16 E_CORE_ERROR 32 E_CORE_WARNING 64 E_COMPILE_ERROR 128 E_COMPILE_WARNING 256 E_USER_ERROR 512 E_USER_WARNING 1024 E_USER_NOTICE error_reporting(0); /* Turn off all reporting */ error_reporting (7); // Old syntax, PHP 2/3 error_reporting (E_ERROR | E_WARNING | E_PARSE); // New syntax for PHP 3/4 /* Good to use for simple running errors */ error_reporting (15); // Old syntax, PHP 2/3 error_reporting (E_ERROR | E_WARNING | E_PARSE | E_NOTICE); // New syntax for PHP 3/4 /* good for code authoring to report uninitialized or (possibly mis-spelled) variables */ error_reporting (63); // Old syntax, PHP 2/3 error_reporting (E_ALL); // New syntax for PHP 3/4 /* report all PHP errors */ restore_error_handler Restores the previous error handler function void restore_error_handler Used after changing the error handler function using set_error_handler, to revert to the previous error handler (which could be the built-in or a user defined function) See also error_reporting, set_error_handler, trigger_error, user_error set_error_handler Sets a user-defined error handler function. string set_error_handler string error_handler Sets a user function (error_handler) to handle errors in a script. Returns the previously defined error handler (if any), or false on error. This function can be used for defining your own way of handling errors during runtime, for example in applications in which you need to do cleanup of data/files when a critical error happens, or when you need to trigger an error under certain conditions (using trigger_error) The user function needs to accept 2 parameters: the error code, and a string describing the error. From PHP 4.0.2, an additional 3 optional parameters are supplied: the filename in which the error occured, the line number in which the error occured, and the context in which the error occured (an array that points to the active symbol table at the point the error occurred). The example below shows the handling of internal execptions by triggering errors and handling them with a user defined function: <?php // redefine the user error constants - PHP 4 only define (FATAL,E_USER_ERROR); define (ERROR,E_USER_WARNING); define (WARNING,E_USER_NOTICE); // set the error reporting level for this script error_reporting (FATAL | ERROR | WARNING); // error handler function function myErrorHandler ($errno, $errstr, $errfile, $errline) { switch ($errno) { case FATAL: echo "<b>FATAL</b> [$errno] $errstr<br>\n"; echo " Fatal error in line ".$errline." of file ".$errfile; echo ", PHP ".PHP_VERSION." (".PHP_OS.")<br>\n"; echo "Aborting...<br>\n"; exit -1; break; case ERROR: echo "<b>ERROR</b> [$errno] $errstr<br>\n"; break; case WARNING: echo "<b>WARNING</b> [$errno] $errstr<br>\n"; break; default: echo "Unkown error type: [$errno] $errstr<br>\n"; break; } } // function to test the error handling function scale_by_log ($vect, $scale) { if ( !is_numeric($scale) || $scale <= 0 ) trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale", FATAL); if (!is_array($vect)) { trigger_error("Incorrect input vector, array of values expected", ERROR); return null; } for ($i=0; $i<count($vect); $i++) { if (!is_numeric($vect[$i])) trigger_error("Value at position $i is not a number, using 0 (zero)", WARNING); $temp[$i] = log($scale) * $vect[$i]; } return $temp; } // set to the user defined error handler $old_error_handler = set_error_handler("myErrorHandler"); // trigger some errors, first define a mixed array with a non-numeric item echo "vector a\n"; $a = array(2,3,"foo",5.5,43.3,21.11); print_r($a); // now generate second array, generating a warning echo "----\nvector b - a warning (b = log(PI) * a)\n"; $b = scale_by_log($a, M_PI); print_r($b); // this is trouble, we pass a string instead of an array echo "----\nvector c - an error\n"; $c = scale_by_log("not array",2.3); var_dump($c); // this is a critical error, log of zero or negative number is undefined echo "----\nvector d - fatal error\n"; $d = scale_by_log($a, -2.5); ?> And when you run this sample script, the output will be vector a Array ( [0] => 2 [1] => 3 [2] => foo [3] => 5.5 [4] => 43.3 [5] => 21.11 ) ---- vector b - a warning (b = log(PI) * a) <b>WARNING</b> [1024] Value at position 2 is not a number, using 0 (zero)<br> Array ( [0] => 2.2894597716988 [1] => 3.4341896575482 [2] => 0 [3] => 6.2960143721717 [4] => 49.566804057279 [5] => 24.165247890281 ) ---- vector c - an error <b>ERROR</b> [512] Incorrect input vector, array of values expected<br> NULL ---- vector d - fatal error <b>FATAL</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br> Fatal error in line 36 of file trigger_error.php, PHP 4.0.2 (Linux)<br> Aborting...<br> It is important to remember that the standard PHP error handler is completely bypassed. error_reporting settings will have no effect and your error handler will be called regardless - however you are still able to read the current value of error_reporting and act appropriately. Of particular note is that this value will be 0 if the statement that caused the error was prepended by the @ error-control operator. Also note that it is your responsibility to die if necessary. If the error-handler function returns, script execution will continue with the next statement after the one that caused an error. See also error_reporting, restore_error_handler, trigger_error, user_error trigger_error Generates a user-level error/warning/notice message void trigger_error string error_msg int error_type Used to trigger a user error condition, it can be used by in conjunction with the built-in error handler, or with a user defined function that has been set as the new error handler (set_error_handler). It only works with the E_USER family of constants, and will default to E_USER_NOTICE. This function is useful when you need to generate a particular response to an exception at runtime. For example: if (assert ($divisor == 0)) trigger_error ("Cannot divide by zero", E_USER_ERROR); See set_error_handler for a more extensive example. See also error_reporting, set_error_handler, restore_error_handler, user_error user_error Generates a user-level error/warning/notice message void user_error string error_msg int error_type This is an alias for the function trigger_error. See also error_reporting, set_error_handler, restore_error_handler, and trigger_error