PEAR This chapter contains reference documentation for PEAR components that are distributed with PHP. It is assumed that you are already familiar with objects and classes. PEAR PEAR base class require_once "PEAR.php"; class classname extends PEAR { ... } The PEAR base class provides standard functionality that is used by most PEAR classes. Normally you never make an instance of the PEAR class directly, you use it by subclassing it. Its key features are: request-shutdown object "destructors" error handling 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. In order for destructors to work properly, you must instantiate your class with the "=& new" operator like this: 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'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. The example below shows how to use the PEAR's "poor man's kinda emulated destructors" to implement a simple class that holds the contents of a file, lets you append data to the object and flushes the data back to the file at the end of the request: PEAR(); // this calls the parent class constructor $fp = fopen($file, "r"); if (!is_resource($fp)) { return; } while (!empty($data = fread($fp, 2048))) { $this->contents .= $data; } fclose($fp); } function append($str) { $this->contents .= $str; $this->modified++; } // The "destructor" is named like the constructor // but with an underscore in front. function _FileContainer() { if ($this->modified) { $fp = fopen($this->file, "w"); if (!is_resource($fp)) { return; } fwrite($fp, $this->contents); fclose($fp); } } } $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 // "destructor" is called and updates the file on disk. ]]> PEAR "destructors" use PHP's shutdown callbacks (register_shutdown_function), and you can't output anything from these when PHP is running in a web 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. The next examples illustrate different ways of using PEAR's error handling mechanism. getMessage()."
\n" } ]]> This example shows a wrapper to fsockopen that delivers the error code and message (if any) returned by fsockopen in a PEAR error object. Notice that PEAR::isError is used to detect whether a value is a PEAR error. PEAR_Error's mode of operation in this example is simply returning the error object and leaving the rest to the user (programmer). This is the default error mode. In the next example we're showing how to use default error modes: PEAR(); } function connect($host, $port) { $sock = fsockopen($host, $port, $errno, $errstr); if (!is_resource($sock)) { return $this->raiseError($errstr, $errno); } } } $sock = new TCP_Socket; $sock->setErrorHandling(PEAR_ERROR_DIE); $sock->connect("localhost", 8090); print "still alive
\n"; ]]> Here, we set the default error mode to PEAR_ERROR_DIE, and since we don't specify any error mode in the raiseError call (that'd be the third parameter), raiseError uses the default error mode and exits if fsockopen fails. 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_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_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: Here is an example of how you can switch back and forth without specifying the callback function again: PEAR() This is the PEAR class constructor. Call it from the constructor of every class inheriting the PEAR class. PEAR(); $this->foo = $foo; $this->bar = $bar; } } ]]> _PEAR() This is the PEAR class destructor. It is called during request shutdown. PEAR_Error PEAR error mechanism base class $err = new PEAR_Error($msg); An error object has a mode of operation that can be set with one of the following constants: PEAR_ERROR_RETURN Just return the object, don't do anything special in PEAR_Error's constructor. PEAR_ERROR_PRINT Print the error message in the constructor. The execution is not interrupted. PEAR_ERROR_TRIGGER Use PHP's trigger_error function to raise an internal error in PHP. The execution is aborted if you have defined your own PHP error handler or if you set the error severity to E_USER_ERROR. PEAR_ERROR_DIE Print the error message and exit. Execution is of course aborted. PEAR_ERROR_CALLBACK Use a callback function or method to handle errors. Execution is aborted. PEAR_Error::PEAR_Error message code mode options userinfo PEAR_Error constructor. Parameters: message error message, defaults to "unknown error" code error code (optional) mode Mode of operation. See the error modes section for details. options If the mode of can have any options specified, use this parameter. Currently the "trigger" and "callback" modes are the only using the options parameter. For trigger mode, this parameter is one of E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR. For callback mode, this parameter should contain either the callback function name (string), or a two-element (object, string) array representing an object and a method name.