mirror of
https://github.com/php/php-src.git
synced 2024-09-24 11:27:28 +00:00
84 lines
3.7 KiB
Plaintext
84 lines
3.7 KiB
Plaintext
The intl extension has particular conventions regarding error reporting.
|
|
These conventions are enumerated in this document.
|
|
|
|
:: The last error is always stored globally.
|
|
|
|
The global error code can be obtained in userland with intl_get_error_code().
|
|
This is a U_* error code defined by ICU, but it does not have necessarily to be
|
|
returned obtained after a call to an ICU function. That is to say, the internal
|
|
PHP wrapper functions can set these error codes when appropriate. For instance,
|
|
in response to bad arguments (e.g. zend_parse_parameters() failure), the PHP
|
|
wrapper function should set the global error code to U_ILLEGAL_ARGUMENT_ERROR).
|
|
|
|
The error code (an integer) can be converter to the corresponding enum name
|
|
string in userland with intl_error_name().
|
|
|
|
The associated message can be obtained with intl_get_error_message(). This is a
|
|
message set by the PHP wrapping code, not by ICU. The message should include the
|
|
name of the function that failed in order to make debugging easier (though if
|
|
you activate warnings with intl.error_level or exceptions with
|
|
intl.use_exceptions you get more fine-grained information about where the
|
|
error ocurred).
|
|
|
|
The internal PHP code can set the global last error with:
|
|
void intl_error_set_code(intl_error* err, UErrorCode err_code TSRMLS_DC);
|
|
void intl_error_set_custom_msg(intl_error* err, char* msg, int copyMsg TSRMLS_DC);
|
|
void intl_error_set(intl_error* err, UErrorCode code, char* msg, int copyMsg TSRMLS_DC);
|
|
|
|
and by passing NULL as the first parameter. The last function is a combination
|
|
of the first two. If the message is not a static buffer, copyMsg should be 1.
|
|
This makes the message string be copied and freed when no longer needed. There's
|
|
no way to pass ownership of the string without it being copied.
|
|
|
|
|
|
:: The last is ALSO stored in the object whose method call triggered the error,
|
|
unless the error is due to bad arguments, in which case only the global error
|
|
should be set
|
|
|
|
Objects store an intl_error structed in their private data. For instance:
|
|
typedef struct {
|
|
zend_object zo;
|
|
intl_error err;
|
|
Calendar* ucal;
|
|
} Calendar_object;
|
|
|
|
The global error and the object error can be SIMULTANEOUSLY set with these
|
|
functions:
|
|
void intl_errors_set_custom_msg(intl_error* err, char* msg, int copyMsg TSRMLS_DC);
|
|
void intl_errors_set_code(intl_error* err, UErrorCode err_code TSRMLS_DC);
|
|
void intl_errors_set(intl_error* err, UErrorCode code, char* msg, int copyMsg TSRMLS_DC);
|
|
|
|
by passing a pointer to the object's intl_error structed as the first parameter.
|
|
Node the extra 's' in the functions' names ('errors', not 'error').
|
|
|
|
Static methods should only set the global error.
|
|
|
|
|
|
:: Intl classes that can be instantiated should provide ::getErrorCode() and
|
|
getErrorMessage() methods
|
|
|
|
These methods are used to retrieve the error codes stored in the object's
|
|
private intl_error structured and mirror the global intl_get_error_code() and
|
|
intl_get_error_message().
|
|
|
|
|
|
:: Intl methods and functions should return FALSE on error (even argument
|
|
parsing errors), not NULL. Constructors and factory methods are the
|
|
exception; these should return NULL, not FALSE.
|
|
|
|
Not that constructors in Intl generally (always?) don't throws exceptions.
|
|
They instead destroy the object to that the result of new IntlClass() can
|
|
be NULL. This may be surprising.
|
|
|
|
|
|
:: Intl functions and methods should reset the global error before doing
|
|
anything else (even parse the arguments); instance methods should also reset
|
|
the object's private error
|
|
|
|
Errors should be lost after a function call. This is different from the way
|
|
ICU operates, where functions return immediately if an error is set.
|
|
|
|
Error resetting can be done with:
|
|
void intl_error_reset(NULL TSRMLS_DC); /* reset global error */
|
|
void intl_errors_reset(intl_error* err TSRMLS_DC ); /* reset global and object error */
|