From 267173c6c0c3d9b72e5f87eded0b877ce0e54209 Mon Sep 17 00:00:00 2001 From: Philip Olson Date: Sun, 24 Apr 2005 15:36:00 +0000 Subject: [PATCH] WS, preparation for the new doc style git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@184982 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../errorfunc/functions/debug-backtrace.xml | 224 ++++++----- reference/errorfunc/functions/error-log.xml | 178 ++++----- .../errorfunc/functions/error-reporting.xml | 296 +++++++------- .../functions/restore-error-handler.xml | 94 ++--- .../functions/restore-exception-handler.xml | 58 +-- .../errorfunc/functions/set-error-handler.xml | 364 +++++++++--------- .../errorfunc/functions/trigger-error.xml | 106 ++--- reference/errorfunc/functions/user-error.xml | 26 +- 8 files changed, 671 insertions(+), 675 deletions(-) diff --git a/reference/errorfunc/functions/debug-backtrace.xml b/reference/errorfunc/functions/debug-backtrace.xml index c212ddf564..21945280cc 100755 --- a/reference/errorfunc/functions/debug-backtrace.xml +++ b/reference/errorfunc/functions/debug-backtrace.xml @@ -1,101 +1,99 @@ - - - - debug_backtrace - - Generates a backtrace - - - - &reftitle.description; - - arraydebug_backtrace - - - - debug_backtrace generates a PHP backtrace - and returns this information as an associative array. The - possible returned elements are listed in the following table: - - - - Possible returned elements from <function>debug_backtrace</function> - - - - Name - Type - Description - - - - - function - string - - The current function name. See also - __FUNCTION__. - - - - line - integer - - The current line number. See also - __LINE__. - - - - file - string - - The current file name. See also - __FILE__. - - - - class - string - - The current class name. See also - __CLASS__ - - - - type - string - - The current call type. If a method call, "->" is returned. If a static - method call, "::" is returned. If a function call, nothing is returned. - - - - args - array - - If inside a function, this lists the functions arguments. If - inside an included file, this lists the included file name(s). - - - - -
- - - The following is a simple example. - - - - - <function>debug_backtrace</function> example - - + + + + debug_backtrace + Generates a backtrace + + + &reftitle.description; + + arraydebug_backtrace + + + + debug_backtrace generates a PHP backtrace + and returns this information as an associative array. The + possible returned elements are listed in the following table: + + + + Possible returned elements from <function>debug_backtrace</function> + + + + Name + Type + Description + + + + + function + string + + The current function name. See also + __FUNCTION__. + + + + line + integer + + The current line number. See also + __LINE__. + + + + file + string + + The current file name. See also + __FILE__. + + + + class + string + + The current class name. See also + __CLASS__ + + + + type + string + + The current call type. If a method call, "->" is returned. If a static + method call, "::" is returned. If a function call, nothing is returned. + + + + args + array + + If inside a function, this lists the functions arguments. If + inside an included file, this lists the included file name(s). + + + + +
+ + + The following is a simple example. + + + + + <function>debug_backtrace</function> example + + ]]> - - - Results when executing /tmp/b.php: - - + + + Results when executing /tmp/b.php: + + - array(4) { +[0]=> +array(4) { ["file"] => string(10) "/tmp/a.php" ["line"] => int(10) ["function"] => string(6) "a_test" @@ -126,12 +124,12 @@ array(2) { array(1) { [0] => &string(6) "friend" } - } - [1]=> - array(4) { +} +[1]=> +array(4) { ["file"] => string(10) "/tmp/b.php" ["line"] => int(2) - ["args"] => + ["args"] => array(1) { [0] => string(10) "/tmp/a.php" } @@ -139,15 +137,15 @@ array(2) { } } ]]> - - - - - See also trigger_error and - debug_print_backtrace. - - - + + + + + See also trigger_error and + debug_print_backtrace. + + + + - - - error_log - Send an error message somewhere - - - &reftitle.description; - - interror_log - stringmessage - intmessage_type - stringdestination - stringextra_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: - - <function>error_log</function> log types - - - - 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. This is the default option. - - - - 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. - - - - -
- - - - When explicitly specifying the message_type as - 3, a newline is not automatically added to the end of - the message string. - - - - - Remote debugging via TCP/IP is a PHP 3 feature that is - not available in PHP 4. - - - - - <function>error_log</function> examples - + + + error_log + Send an error message somewhere + + + &reftitle.description; + + interror_log + stringmessage + intmessage_type + stringdestination + stringextra_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: + + <function>error_log</function> log types + + + + 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. This is the default option. + + + + 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. + + + + +
+ + + + When explicitly specifying the message_type as + 3, a newline is not automatically added to the end of + the message string. + + + + + Remote debugging via TCP/IP is a PHP 3 feature that is + not available in PHP 4. + + + + + <function>error_log</function> examples + ]]> - - - - - + + + + + + - - - error_reporting - Sets which PHP errors are reported - - - &reftitle.description; - - interror_reporting - intlevel - - - The error_reporting function sets the - error_reporting - directive at runtime. PHP has many levels of errors, using - this function sets that level for the duration (runtime) of - your script. - - - error_reporting sets PHP's error reporting level, - and returns the old level. The level parameter - takes on either a bitmask, or named constants. 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. - - - - <function>error_reporting</function> examples - + + + error_reporting + Sets which PHP errors are reported + + + &reftitle.description; + + interror_reporting + intlevel + + + The error_reporting function sets the + error_reporting + directive at runtime. PHP has many levels of errors, using + this function sets that level for the duration (runtime) of + your script. + + + error_reporting sets PHP's error reporting level, + and returns the old level. The level parameter + takes on either a bitmask, or named constants. 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. + + + + <function>error_reporting</function> examples + ]]> - - - - - The available error level constants are listed below. The actual - meanings of these error levels are described in the - predefined constants. - - <function>error_reporting</function> level constants and bit values - - - - value - constant - - - - - 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 - - - - 2047 - - E_ALL - - - - 2048 - - E_STRICT - - - - -
- - - - With PHP > 5.0.0 E_STRICT with value 2048 is - available. E_ALL does NOT - include error level E_STRICT. - Most of E_STRICT errors are evaluated at the - compile time thus such errors are not reported in the file where - error_reporting is enhanced - to include E_STRICT errors. - - - - See also the display_errors - directive and ini_set. - - - + + + + + The available error level constants are listed below. The actual + meanings of these error levels are described in the + predefined constants. + + <function>error_reporting</function> level constants and bit values + + + + value + constant + + + + + 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 + + + + 2047 + + E_ALL + + + + 2048 + + E_STRICT + + + + +
+ + + + With PHP > 5.0.0 E_STRICT with value 2048 is + available. E_ALL does NOT + include error level E_STRICT. + Most of E_STRICT errors are evaluated at the + compile time thus such errors are not reported in the file where + error_reporting is enhanced + to include E_STRICT errors. + + + + See also the display_errors + directive and ini_set. + + + + - - - restore_error_handler - - Restores the previous error handler function - - - - &reftitle.description; - - boolrestore_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). This - function always returns &true;. - - - - Calling restore_error_handler from the - error_handler function is ignored. - - - - See also error_reporting, - set_error_handler, - restore_exception_handler, - trigger_error. - - - - - Decide if <function>unserialize</function> caused an error, then - restore the original error handler. - - + + + restore_error_handler + + Restores the previous error handler function + + + + &reftitle.description; + + boolrestore_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). This + function always returns &true;. + + + + Calling restore_error_handler from the + error_handler function is ignored. + + + + See also error_reporting, + set_error_handler, + restore_exception_handler, + trigger_error. + + + + + Decide if <function>unserialize</function> caused an error, then + restore the original error handler. + + ]]> - - &example.outputs; - + + &example.outputs; + - - - - - + + + + + - - - restore_exception_handler - - Restores the previously defined exception handler function - - - - &reftitle.description; - - boolrestore_exception_handler - - - - Used after changing the exception handler function using - set_exception_handler, to revert to the previous - exception handler (which could be the built-in or a user defined - function). This function always returns &true;. - - - See also - set_exception_handler, - set_error_handler, - restore_error_handler - error_reporting - - - + + + + restore_exception_handler + + Restores the previously defined exception handler function + + + + &reftitle.description; + + boolrestore_exception_handler + + + + Used after changing the exception handler function using + set_exception_handler, to revert to the previous + exception handler (which could be the built-in or a user defined + function). This function always returns &true;. + + + See also + set_exception_handler, + set_error_handler, + restore_error_handler + error_reporting + + + + - - - set_error_handler - - Sets a user-defined error handler function - - - - &reftitle.description; - - mixedset_error_handler - callbackerror_handler - interror_types - - - Sets a user function (error_handler) to handle - errors in a script. Returns a string containing the previously defined - error handler (if any), or &false; on error. If the previous handler - was a class method, this function will return an indexed array with - the class and the method name. - - - 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 second parameter error_types was introduced in - PHP 5 and can be used to mask the triggering of the - error_handler function just like the error_reporting ini setting controls - which errors are shown. Without this mask set the - error_handler will be called for every error - regardless to the setting of the error_reporting setting. - - - The user function needs to accept two parameters: the error code, and a - string describing the error. From PHP 4.0.2, three optional - parameters are supplied: the filename in which the error occurred, the - line number in which the error occurred, and the context in which the - error occurred (an array that points to the active symbol table at the - point the error occurred). The function can be shown as: - - handler - interrno - stringerrstr - stringerrfile - interrline - arrayerrcontext - - - - errno - - - The first parameter, errno, contains the - level of the error raised, as an integer. - - - - - errstr - - - The second parameter, errstr, contains the - error message, as a string. - - - - - errfile - - - The third parameter is optional, errfile, - which contains the filename that the error was raised in, as a string. - - - - - errline - - - The fourth parameter is optional, errline, - which contains the line number the error was raised at, as an integer. - - - - - errcontext - - - The fifth parameter is optional, errcontext, - which is an array that points to the active symbol table at the point - the error occurred. In other words, errcontext - will contain an array of every variable that existed in the scope the - error was triggered in. - - - - - - - - Instead of a function name, an array containing an object reference and - a method name can also be supplied. (Since PHP 4.3.0) - - - - - The following error types cannot be handled with a user defined - function: E_ERROR, E_PARSE, - E_CORE_ERROR, E_CORE_WARNING, - E_COMPILE_ERROR, - E_COMPILE_WARNING, and - most of E_STRICT raised in the file where - set_error_handler is called. - - - - The example below shows the handling of internal exceptions by - triggering errors and handling them with a user defined function: - - - Error handling with <function>set_error_handler</function> and - <function>trigger_error</function> - - + + + set_error_handler + + Sets a user-defined error handler function + + + + &reftitle.description; + + mixedset_error_handler + callbackerror_handler + interror_types + + + Sets a user function (error_handler) to handle + errors in a script. Returns a string containing the previously defined + error handler (if any), or &false; on error. If the previous handler + was a class method, this function will return an indexed array with + the class and the method name. + + + 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 second parameter error_types was introduced in + PHP 5 and can be used to mask the triggering of the + error_handler function just like the error_reporting ini setting controls + which errors are shown. Without this mask set the + error_handler will be called for every error + regardless to the setting of the error_reporting setting. + + + The user function needs to accept two parameters: the error code, and a + string describing the error. From PHP 4.0.2, three optional + parameters are supplied: the filename in which the error occurred, the + line number in which the error occurred, and the context in which the + error occurred (an array that points to the active symbol table at the + point the error occurred). The function can be shown as: + + handler + interrno + stringerrstr + stringerrfile + interrline + arrayerrcontext + + + + errno + + + The first parameter, errno, contains the + level of the error raised, as an integer. + + + + + errstr + + + The second parameter, errstr, contains the + error message, as a string. + + + + + errfile + + + The third parameter is optional, errfile, + which contains the filename that the error was raised in, as a string. + + + + + errline + + + The fourth parameter is optional, errline, + which contains the line number the error was raised at, as an integer. + + + + + errcontext + + + The fifth parameter is optional, errcontext, + which is an array that points to the active symbol table at the point + the error occurred. In other words, errcontext + will contain an array of every variable that existed in the scope the + error was triggered in. + + + + + + + + Instead of a function name, an array containing an object reference and + a method name can also be supplied. (Since PHP 4.3.0) + + + + + The following error types cannot be handled with a user defined + function: E_ERROR, E_PARSE, + E_CORE_ERROR, E_CORE_WARNING, + E_COMPILE_ERROR, + E_COMPILE_WARNING, and + most of E_STRICT raised in the file where + set_error_handler is called. + + + + The example below shows the handling of internal exceptions by + triggering errors and handling them with a user defined function: + + + Error handling with <function>set_error_handler</function> and + <function>trigger_error</function> + + ]]> - - &example.outputs; - + + &example.outputs; + FATAL [256] log(x) for x <= 0 is undefined, you used: scale = -2.5
- Fatal error in line 36 of file trigger_error.php, PHP 4.0.2 (Linux)
+Fatal error in line 36 of file trigger_error.php, PHP 4.0.2 (Linux)
Aborting...
]]> - - - - - 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. - - - - If errors occur before the script is executed (e.g. on file uploads) the custom - error handler cannot be called since it is not registered at that time. - - - - - The second parameter error_types was introduced - in PHP 5. - - - - See also error_reporting, - restore_error_handler, - trigger_error, - error level constants, - &listendand; &seealso.callback;. - - - + + + + + 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. + + + + If errors occur before the script is executed (e.g. on file uploads) the custom + error handler cannot be called since it is not registered at that time. + + + + + The second parameter error_types was introduced + in PHP 5. + + + + See also error_reporting, + restore_error_handler, + trigger_error, + error level constants, + &listendand; &seealso.callback;. + + + + - - - trigger_error - - Generates a user-level error/warning/notice message - - - - &reftitle.description; - - booltrigger_error - stringerror_msg - interror_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 returns &false; if wrong error_type is - specified, &true; otherwise. - - - This function is useful when - you need to generate a particular response to an exception at runtime. - For example: - - + + + trigger_error + + Generates a user-level error/warning/notice message + + + + &reftitle.description; + + booltrigger_error + stringerror_msg + interror_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 returns &false; if wrong error_type is + specified, &true; otherwise. + + + This function is useful when + you need to generate a particular response to an exception at runtime. + For example: + + ]]> - - - - - See set_error_handler for a more extensive example. - - - - - error_msg is limited to 1024 characters in length. - Any additional characters beyond 1024 will be truncated. - - - + + + - See also error_reporting, - set_error_handler, - restore_error_handler, and - error level constants. + See set_error_handler for a more extensive example. - - + + + + error_msg is limited to 1024 characters in length. + Any additional characters beyond 1024 will be truncated. + + + + + See also error_reporting, + set_error_handler, + restore_error_handler, and + error level constants. + + + + - - - user_error - Alias of trigger_error - - - &reftitle.description; - - This function is an alias of trigger_error. - - - + + + user_error + Alias of trigger_error + + + &reftitle.description; + + This function is an alias of trigger_error. + + +