diff --git a/pear/pear.xml b/pear/pear.xml index e096371a1d..0caf8f3269 100644 --- a/pear/pear.xml +++ b/pear/pear.xml @@ -1,5 +1,5 @@ - + PEAR Reference Manual PEAR @@ -38,52 +38,71 @@ - - PEAR "destructors" - - If you inherit PEAR in a class called - ClassName, you can define a method in - it called called _ClassName (the - class name with an underscore prepended) that will be invoked - when the request is over. This is not a destructor in the sense - that you can "delete" an object and have the destructor called, - but in the sense that PHP gives you a callback in the object - when it is done executing. See the example below. - - - - PEAR Error Handling - - PEAR's base class also provides a way of passing around more - complex errors than a &true;/false value or a numeric code. A - PEAR error is an object that is either an instance of the class - PEAR_Error, or some class inheriting - PEAR_Error. - - - One of the design criteria of PEAR's errors is that it should - not force a particular type of output on the user, it should be - possible to handle errors without any output at all if that is - desireable. This makes it possible to handle errors gracefully, - also when your output format is different from HTML (for example - WML or some other XML format). - - - The error object can be configured to do a number of things when - it is created, such as printing an error message, printing the - message and exiting, raising an error with PHP's - trigger_error function, invoke a callback, - or none of the above. This is typically specified in - PEAR_Error's constructor, but all of the - parameters are optional, and you can set up defaults for errors - generated from each object based on the - PEAR class. See the PEAR error examples for how - to use it and the PEAR_Error reference - for the full details. - - + + + PEAR "destructors" + + If you inherit PEAR in a class called + ClassName, you can define a method in + it called called _ClassName (the + class name with an underscore prepended) that will be invoked + when the request is over. This is not a destructor in the sense + that you can "delete" an object and have the destructor called, + but in the sense that PHP gives you a callback in the object + when PHP is done executing. See the example below. + + + + Important! + + In order for destructors to work properly, you must + instantiate your class with the "=& new" operator like + this: + +$obj =& new MyClass(); + + + + If you only use "= new", the object registered in PEAR's + shutdown list will be a copy of the object at the time the + constructor is called, and it will this copy's "destructor" + that will be called upon request shutdown. + + + + + + PEAR Error Handling + + PEAR's base class also provides a way of passing around more + complex errors than a true/false value or a numeric code. A + PEAR error is an object that is either an instance of the class + PEAR_Error, or some class inheriting + PEAR_Error. + + + One of the design criteria of PEAR's errors is that it should not + force a particular type of output on the user, it should be + possible to handle errors without any output at all if that is + desirable. This makes it possible to handle errors gracefully, + also when your output format is different from HTML (for example + WML or some other XML format). + + + The error object can be configured to do a number of things when + it is created, such as printing an error message, printing the + message and exiting, raising an error with PHP's + trigger_error function, invoke a callback, + or none of the above. This is typically specified in + PEAR_Error's constructor, but all of the + parameters are optional, and you can set up defaults for errors + generated from each object based on the + PEAR class. See the PEAR error examples for how + to use it and the PEAR_Error reference + for the full details. + Examples @@ -137,7 +156,7 @@ class FileContainer extends PEAR } } -$fileobj = new FileContainer("testfile"); +$fileobj =& new FileContainer("testfile"); $fileobj->append("this ends up at the end of the file\n"); // When the request is done and PHP shuts down, $fileobj's @@ -153,6 +172,11 @@ $fileobj->append("this ends up at the end of the file\n"); server. So anything printed in a "destructor" gets lost except when PHP is used in command-line mode. Bummer. + + Also, see the warning about how to + instantiate objects if you want to use the destructor. + @@ -231,6 +255,149 @@ print "still alive<BR>\n"; fsockopen fails. + + Global Variables Used + + The PEAR class uses some global variables to register global + defaults, and an object list used by the "destructors". All of + the global variables associated with the PEAR class have a + _PEAR_ name prefix. + + + + + $_PEAR_default_error_mode + + + If no default error mode is set in an object, this mode will + be used. Must be one of + PEAR_ERROR_RETURN, + PEAR_ERROR_PRINT, + PEAR_ERROR_TRIGGER, + PEAR_ERROR_DIE or + PEAR_ERROR_CALLBACK. + + + Don't set this variable directly, call + PEAR::setErrorHandling as a static + method like this: + + +PEAR::setErrorHandling(PEAR_ERROR_DIE); + + + + + + + $_PEAR_default_error_options + + + If the error mode is PEAR_ERROR_TRIGGER, + this is the error level (one of + E_USER_NOTICE, + E_USER_WARNING or + E_USER_ERROR). + + + Don't set this variable directly, call + PEAR::setErrorHandling as a static + method like this: + + +PEAR::setErrorHandling(PEAR_ERROR_TRIGGER, E_USER_ERROR); + + + + + + + $_PEAR_default_error_callback + + + If no options parameter is used + when an error is raised and the error mode is + PEAR_ERROR_CALLBACK, the value of this + variable is used as the callback. This means that you can + switch the error mode temporarily and return to callback mode + without specifying the callback function again. A string + value represents a function, a two-element array with an + object at index 0 and a string at index 1 represents a + method. + + + Again, don't set this variable directly, call + PEAR::setErrorHandling as a static + method like this: + + +PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, "my_error_handler"); + + + + + Here is an example of how you can switch back and forth + without specifying the callback function again: + + +PEAR::setErrorMode(PEAR_ERROR_CALLBACK, "my_function_handler"); +do_some_stuff(); +PEAR::setErrorMode(PEAR_ERROR_DIE); +do_some_critical_stuff(); +PEAR::setErrorMode(PEAR_ERROR_CALLBACK); +// now we're back to using my_function_handler again + + + + + + + + + + Methods + + PEAR::PEAR + + + PEAR() + + + + + This is the PEAR class constructor. Call it from the + constructor of every class inheriting the PEAR class. + + PEAR Class Constructor Example + +class MyClass extends PEAR +{ + var $foo, $bar; + function MyClass($foo, $bar) + { + $this->PEAR(); + $this->foo = $foo; + $this->bar = $bar; + } +} + + + + + + PEAR::_PEAR + + + _PEAR() + + + + + This is the PEAR class destructor. It is called during request + shutdown. + + + diff --git a/pear/standards.xml b/pear/standards.xml index d7bdb16c95..2ec839c091 100644 --- a/pear/standards.xml +++ b/pear/standards.xml @@ -1,4 +1,4 @@ - + PEAR Coding Standards @@ -108,7 +108,7 @@ $long_variable = foo($baz); Function Definitions - Function declaractions follow the "one &true; brace" convention: + Function declaractions follow the "one true brace" convention: function fooFunction($arg1, $arg2 = '') { @@ -239,12 +239,16 @@ function connect(&$dsn, $persistent = false) - - CVS Tags + + Using CVS + + This section applies only to packages using CVS at cvs.php.net. + - Include the $Id$ CVS vendor tag in each file. As each file + Include the $Id$ CVS keyword in each file. As each file is edited, add this tag if it's not yet present (or replace existing forms such as "Last Modified:", etc.). + + + + The rest of this section assumes that you have basic knowledge + about CVS tags and branches. + + + CVS tags are used to label which revisions of the files in your + package belong to a given release. Below is a list of the + required and suggested CVS tags: + + + + RELEASE_n_n + + + (required) Used for tagging a release. If you don't use it, + there's no way to go back and retrieve your package from the + CVS server in the state it was in at the time of the release. + + + + + QA_n_n + + + (branch, optional) If you feel you need to roll out a + release candidate before releasing, it's a good idea to make a + branch for it so you can isolate the release and apply only + those critical fixes before the actual release. Meanwhile, + normal development may continue on the main trunk. + + + + + MAINT_n_n + + + (branch, optional) If you need to make "micro-releases" (for + example 1.2.1 and so on after 1.2, you can use a branch for + that too, if your main trunk is very active and you want only + minor changes between your micro-releases. + + + + + Only the RELEASE tag is required, the rest are recommended for + your convenience. + + + Below is an example of how to tag the 1.2 release of the + "Money_Fast" package: + + $ cd pear/Money_Fast +$ cvs tag RELEASE_1_2 +T Fast.php +T README +T package.xml + + + + By doing this you make it possible for the PEAR web site to take + you through the rest of your release process. + + + Here's an example of how to create a QA branch: + + $ cvs tag QA_2_0_BP +... +$ cvs rtag -b -r QA_2_0_BP QA_2_0 +$ cvs update -r QA_2_0 +$ cvs tag RELEASE_2_0RC1 +...and then the actual release, from the same branch: +$ cvs tag RELEASE_2_0 + + + The "QA_2_0_BP" tag is a "branch point" tag, which is the start + point of the tag. It's always a good idea to start a CVS branch + from such branch points. MAINT branches may use the RELEASE tag + as their branch point. @@ -266,14 +350,14 @@ function connect(&$dsn, $persistent = false) Naming Constants - Constants should always be uppercase, with underscores to seperate + Constants should always be all-uppercase, with underscores to seperate words. Prefix constant names with the name of the class/package they are used in. For example, the constants used by the DB:: package all begin with "DB_". - +