+++ /dev/null
-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 occurred).
-
-The internal PHP code can set the global last error with:
-void intl_error_set_code(intl_error* err, UErrorCode err_code);
-void intl_error_set_custom_msg(intl_error* err, char* msg, int copyMsg);
-void intl_error_set(intl_error* err, UErrorCode code, char* msg, int copyMsg);
-
-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);
-void intl_errors_set_code(intl_error* err, UErrorCode err_code);
-void intl_errors_set(intl_error* err, UErrorCode code, char* msg, int copyMsg);
-
-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); /* reset global error */
-void intl_errors_reset(intl_error* err); /* reset global and object error */
-
-In practice, intl_errors_reset() is not used because most classes have also
-plain functions mapped to the same internal functions as their instance methods.
-Fetching of the object is done with zend_parse_method_parameters() instead of
-directly using getThis(). Therefore, no reference to object is obtained until
-the arguments are fully parsed. Without a reference to the object, there's no
-way to reset the object's internal error code. Instead, resetting of the
-object's internal error code is done upon fetching the object from its zval.
-
-Example:
-U_CFUNC PHP_FUNCTION(breakiter_set_text)
-{
- /* ... variable declations ... */
- BREAKITER_METHOD_INIT_VARS; /* macro also resets global error */
- object = getThis();
-
- if (zend_parse_parameters(ZEND_NUM_ARGS(), "s",
- &text, &text_len) == FAILURE) {
- intl_error_set(NULL, U_ILLEGAL_ARGUMENT_ERROR,
- "breakiter_set_text: bad arguments", 0);
- RETURN_FALSE;
- }
-
- /* ... */
-
- BREAKITER_METHOD_FETCH_OBJECT; /* macro also resets object's error */
-
- /* ... */
-}
-
-Implementations of ::getErrorCode() and ::getErrorMessage() should not reset the
-object's error code.
--- /dev/null
+# Intl extension error conventions
+
+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 occurred).
+
+The internal PHP code can set the global last error with:
+
+```c
+void intl_error_set_code(intl_error* err, UErrorCode err_code);
+void intl_error_set_custom_msg(intl_error* err, char* msg, int copyMsg);
+void intl_error_set(intl_error* err, UErrorCode code, char* msg, int copyMsg);
+```
+
+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:
+
+```c
+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:
+
+```c
+void intl_errors_set_custom_msg(intl_error* err, char* msg, int copyMsg);
+void intl_errors_set_code(intl_error* err, UErrorCode err_code);
+void intl_errors_set(intl_error* err, UErrorCode code, char* msg, int copyMsg);
+```
+
+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:
+
+```c
+void intl_error_reset(NULL); /* reset global error */
+void intl_errors_reset(intl_error* err); /* reset global and object error */
+```
+
+In practice, `intl_errors_reset()` is not used because most classes have also
+plain functions mapped to the same internal functions as their instance methods.
+Fetching of the object is done with `zend_parse_method_parameters()` instead of
+directly using `getThis()`. Therefore, no reference to object is obtained until
+the arguments are fully parsed. Without a reference to the object, there's no
+way to reset the object's internal error code. Instead, resetting of the
+object's internal error code is done upon fetching the object from its zval.
+
+Example:
+
+```c
+U_CFUNC PHP_FUNCTION(breakiter_set_text)
+{
+ /* ... variable declations ... */
+ BREAKITER_METHOD_INIT_VARS; /* macro also resets global error */
+ object = getThis();
+
+ if (zend_parse_parameters(ZEND_NUM_ARGS(), "s",
+ &text, &text_len) == FAILURE) {
+ intl_error_set(NULL, U_ILLEGAL_ARGUMENT_ERROR,
+ "breakiter_set_text: bad arguments", 0);
+ RETURN_FALSE;
+ }
+
+ /* ... */
+
+ BREAKITER_METHOD_FETCH_OBJECT; /* macro also resets object's error */
+
+ /* ... */
+}
+```
+
+Implementations of `::getErrorCode()` and `::getErrorMessage()` should not reset
+the object's error code.
projects / php / commitdiff