Proposal for CODING_STANDARDS
cvs -z3 -q diff CODING_STANDARDS main\main.c (in directory S:\php4\)
Index: CODING_STANDARDS
===================================================================
RCS file: /repository/php4/CODING_STANDARDS,v
retrieving revision 1.14
diff -u -r1.14 CODING_STANDARDS
--- CODING_STANDARDS 8 Aug 2002 11:22:18 -0000 1.14
+++ CODING_STANDARDS 8 Aug 2002 22:27:03 -0000
@@ -46,7 +46,8 @@
doing so, should return that new length, so it doesn't have to be
recalculated with strlen() (e.g. php_addslashes())
-[5] Use php_error() to report any errors/warnings during code execution.
+[5] Use php_error_docref() group of functions to report any errors/warnings
+ during code execution.
Use descriptive error messages, and try to avoid using identical
error strings for different stages of an error. For example,
if in order to obtain a URL you have to parse the URL, connect,
@@ -60,7 +61,21 @@
name of the current function if applicable:
php_error(E_WHATEVER, "%s(): Desc.", get_active_function_name(TSRMLS_C));
+
+ This can be done automaticall with the use of php_error_docref. Where the
+ docref parameter is either NULL or a manual reference describing the
+ error in detail. This must be an external url started by "http://"; or
+ the name of a manual page without the file extension but with an optional
+ target anchor. In case of NULL the reference is generated from the
+ function being executed:
+
+ php_error_docref("function.name#error" TSRMLS_CC, E_WHATEVER, "Desc.");
+
+ You may use php_error_docref1/2 to display the executed functionname
+ followed by one or two important parameters. For example file base
+ functions should display the name of the file opened:
+
+ php_error_docref1("function.fopen", filename TSRMLS_CC, E_WHATEVER,
"Desc.");
+ php_error_docref2("function.copy", file_source, file_dest, param2
TSRMLS_CC, E_WHATEVER, "Desc.");
+
Fixing ("unifying") existing php_error() message is a good thing [tm].
[6] NEVER USE strncat(). If you're absolutely sure you know what you're
doing,
At 21:36 08.08.2002, Marcus Börger wrote:
>O.k. here it comes:
>
>First thanks to Wez for another great idea.
>
>The order of parameters and the function names have changed. The
>order is now docref TSRM, optional parameters and starting from type
>the original parameters of php_error. This order makes it easier to change
>php_error calls into php_error_docref calls.
>
>There are three versions and one define php_error_docref<n> as functions
>and php_error_docref as a define pointing to php_error_docref0.
>
>The docref parameter can either be any link that can be found under
>docref_root (see below). If this parameter is NULL the functionname will be
>used as docref.
>
>We have two new ini settings (hopefully Yasuo does like them) which
>are not required to be changed:
>docref_root = "http://www.php.net/";
>docref_ext = ""
>This will cause some additional traffic on php.net....
>But you can change them to match your local .html PHP Manual.
>For me that is:
>docref_root = "http:// ... /phpManual/"
>docref_ext = ".html"
>
>If we can find a consensus here i will also add a notice in CODING_STANDARDS
>to encourage use of the new functions and hopefully i will find a place
>to document the two new ini settings (and some time to do it all).
>
>marcus
>
>At 21:12 08.08.2002, you wrote:
>>helly Thu Aug 8 15:12:27 2002 EDT
>>
>> Modified files:
>> /php4/main main.c php.h php_globals.h
>> Log:
>> rename php_error_func<n> to php_error_docref and support Wez idea
>> that solves ToDo requirement to point to PHP Manual in error messages.
>>
>>
>>Index: php4/main/main.c
>>diff -u php4/main/main.c:1.471 php4/main/main.c:1.472
>>--- php4/main/main.c:1.471 Wed Aug 7 14:29:35 2002
>>+++ php4/main/main.c Thu Aug 8 15:12:27 2002
>>@@ -18,7 +18,7 @@
>> +----------------------------------------------------------------------+
>> */
>>
>>-/* $Id: main.c,v 1.471 2002/08/07 18:29:35 helly Exp $ */
>>+/* $Id: main.c,v 1.472 2002/08/08 19:12:27 helly Exp $ */
>>
>> /* {{{ includes
>> */
>>@@ -234,6 +234,8 @@
>> STD_PHP_INI_BOOLEAN("display_startup_errors", "0",
>> PHP_INI_ALL, OnUpdateBool, display_startup_errors,
>> php_core_globals, core_globals)
>> STD_PHP_INI_BOOLEAN("enable_dl", "1",
>> PHP_INI_SYSTEM, OnUpdateBool, enable_dl,
>> php_core_globals, core_globals)
>> STD_PHP_INI_BOOLEAN("expose_php", "1",
>> PHP_INI_SYSTEM, OnUpdateBool,
>> expose_php, php_core_globals, core_globals)
>>+ STD_PHP_INI_ENTRY("docref_root", "http://www.php.net/";,
>>PHP_INI_ALL, OnUpdateString, docref_root,
>> php_core_globals, core_globals)
>>+ STD_PHP_INI_ENTRY("docref_ext", "",
>> PHP_INI_ALL, OnUpdateString,
>>docref_ext, php_core_globals, core_globals)
>> STD_PHP_INI_BOOLEAN("html_errors", "1",
>> PHP_INI_SYSTEM, OnUpdateBool,
>> html_errors, php_core_globals, core_globals)
>> STD_PHP_INI_BOOLEAN("xmlrpc_errors", "0",
>> PHP_INI_SYSTEM, OnUpdateBool, xmlrpc_errors,
>> php_core_globals, core_globals)
>> STD_PHP_INI_ENTRY("xmlrpc_error_number", "0",
>> PHP_INI_ALL, OnUpdateInt,
>> xmlrpc_error_number, php_core_globals, core_globals)
>>@@ -386,63 +388,71 @@
>> /* }}} */
>>
>> /* {{{ php_verror */
>>-PHPAPI void php_verror(int type, const char *format, va_list args TSRMLS_DC)
>>+PHPAPI void php_verror(const char *docref, const char *params, int type,
>>const char *format, va_list args TSRMLS_DC)
>> {
>>- char *buffer = NULL;
>>+ char *buffer = NULL, *docref_buf = NULL, *p;
>>
>>- if (format)
>>- vspprintf(&buffer, 0, format, args);
>>+ vspprintf(&buffer, 0, format, args);
>> if (buffer) {
>>- php_error(type, "%s", buffer);
>>+ if (!docref) {
>>+ spprintf(&docref_buf, 0, "function.%s%s",
>>get_active_function_name(TSRMLS_C), PG(docref_ext));
>>+ if (docref_buf) {
>>+ while((p=strchr(docref_buf, '_'))!=NULL)
>>*p = '-';
>>+ docref = docref_buf;
>>+ }
>>+ }
>>+ if (docref) {
>>+ if (PG(html_errors) && PG(docref_ext)) {
>>+ php_error(type, "%s(%s) [<a
>>href='%s%s'>%s</a>]: %s", get_active_function_name(TSRMLS_C), params,
>>PG(docref_root), docref, docref, buffer);
>>+ } else {
>>+ php_error(type, "%s(%s) [%s%s]: %s",
>>get_active_function_name(TSRMLS_C), params, PG(docref_root), docref, buffer);
>>+ }
>>+ } else {
>>+ php_error(type, "%s(%s): %s",
>>get_active_function_name(TSRMLS_C), params, buffer);
>>+ }
>> efree(buffer);
>>+ if (docref_buf)
>>+ efree(docref_buf);
>> } else {
>>- php_error(E_ERROR, "%s(): Out of memory",
>>get_active_function_name(TSRMLS_C));
>>+ php_error(E_ERROR, "%s(%s): Out of memory",
>>get_active_function_name(TSRMLS_C), params);
>> }
>> }
>> /* }}} */
>>
>>-/* {{{ php_error_func0 */
>>-PHPAPI void php_error_func0(int type TSRMLS_DC, const char *format, ...)
>>+/* {{{ php_error_docref */
>>+PHPAPI void php_error_docref(const char *docref TSRMLS_DC, int type,
>>const char *format, ...)
>> {
>>- char *message;
>> va_list args;
>>
>>- spprintf(&message, 0, "%s(): %s",
>>get_active_function_name(TSRMLS_C), format);
>> va_start(args, format);
>>- php_verror(type, message, args TSRMLS_CC);
>>+ php_verror(docref, "", type, format, args TSRMLS_CC);
>> va_end(args);
>>- if (message)
>>- efree(message);
>> }
>> /* }}} */
>>
>>-/* {{{ php_error_func1 */
>>-PHPAPI void php_error_func1(int type, const char *param1 TSRMLS_DC,
>>const char *format, ...)
>>+/* {{{ php_error_docref1 */
>>+PHPAPI void php_error_docref1(const char *docref TSRMLS_DC, const char
>>*param1, int type, const char *format, ...)
>> {
>>- char *message;
>> va_list args;
>>
>>- spprintf(&message, 0, "%s(%s): %s",
>>get_active_function_name(TSRMLS_C), param1, format);
>> va_start(args, format);
>>- php_verror(type, message, args TSRMLS_CC);
>>+ php_verror(docref, param1, type, format, args TSRMLS_CC);
>> va_end(args);
>>- if (message)
>>- efree(message);
>> }
>> /* }}} */
>>
>>-/* {{{ php_error_func2 */
>>-PHPAPI void php_error_func2(int type, const char *param1, const char
>>*param2 TSRMLS_DC, const char *format, ...)
>>+/* {{{ php_error_docref2 */
>>+PHPAPI void php_error_docref2(const char *docref TSRMLS_DC, const char
>>*param1, const char *param2, int type, const char *format, ...)
>> {
>>- char *message;
>>+ char *params;
>> va_list args;
>>
>>- spprintf(&message, 0, "%s(%s,%s): %s",
>>get_active_function_name(TSRMLS_C), param1, param2, format);
>>+ spprintf(¶ms, 0, "%s,%s", param1, param2);
>> va_start(args, format);
>>- php_verror(type, message, args TSRMLS_CC);
>>+ php_verror(docref, params ? params : "...", type, format, args
>>TSRMLS_CC);
>> va_end(args);
>>- if (message)
>>- efree(message);
>>+ if (params)
>>+ efree(params);
>> }
>> /* }}} */
>>
>>Index: php4/main/php.h
>>diff -u php4/main/php.h:1.172 php4/main/php.h:1.173
>>--- php4/main/php.h:1.172 Wed Aug 7 14:29:36 2002
>>+++ php4/main/php.h Thu Aug 8 15:12:27 2002
>>@@ -17,7 +17,7 @@
>> +----------------------------------------------------------------------+
>> */
>>
>>-/* $Id: php.h,v 1.172 2002/08/07 18:29:36 helly Exp $ */
>>+/* $Id: php.h,v 1.173 2002/08/08 19:12:27 helly Exp $ */
>>
>> #ifndef PHP_H
>> #define PHP_H
>>@@ -256,9 +256,11 @@
>> #define php_error zend_error
>>
>> /* PHPAPI void php_error(int type, const char *format, ...); */
>>-PHPAPI void php_error_func0(int type TSRMLS_DC, const char *format, ...);
>>-PHPAPI void php_error_func1(int type, const char *param1 TSRMLS_DC,
>>const char *format, ...);
>>-PHPAPI void php_error_func2(int type, const char *param1, const char
>>*param2 TSRMLS_DC, const char *format, ...);
>>+PHPAPI void php_error_docref0(const char *docref TSRMLS_DC, int type,
>>const char *format, ...);
>>+PHPAPI void php_error_docref1(const char *docref TSRMLS_DC, const char
>>*param1, int type, const char *format, ...);
>>+PHPAPI void php_error_docref2(const char *docref TSRMLS_DC, const char
>>*param1, const char *param2, int type, const char *format, ...);
>>+
>>+#define php_error_docref php_error_docref0
>>
>> #define zenderror phperror
>> #define zendlex phplex
>>Index: php4/main/php_globals.h
>>diff -u php4/main/php_globals.h:1.78 php4/main/php_globals.h:1.79
>>--- php4/main/php_globals.h:1.78 Wed Jun 26 15:43:46 2002
>>+++ php4/main/php_globals.h Thu Aug 8 15:12:27 2002
>>@@ -120,6 +120,9 @@
>>
>> zend_bool y2k_compliance;
>>
>>+ char *docref_root;
>>+ char *docref_ext;
>>+
>> zend_bool html_errors;
>> zend_bool xmlrpc_errors;
>>
>>
>>
>>
>>--
>>PHP CVS Mailing List (http://www.php.net/)
>>To unsubscribe, visit: http://www.php.net/unsub.php
>
>
>--
>PHP Development Mailing List <http://www.php.net/>
>To unsubscribe, visit: http://www.php.net/unsub.php
