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
PEAR "destructors"
If you inherit PEAR in a class called
ClassName, you can define a method in
it 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:
$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 be 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
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:
require_once "PEAR.php";
class FileContainer extends PEAR
{
var $file = '';
var $contents = '';
var $modified = 0;
function FileContainer($file)
{
$this->PEAR(); // this calls the parent class constructor
$fp = fopen($file, "r");
if (!is_resource($fp)) {
return;
}
$this->file = $file;
while ($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.
Note:
PEAR "destructors" use PHP's shutdown callbacks
(register_shutdown_function()), and
in PHP < 4.1, 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. In PHP 4.1 and higher, output can
be also generated in the destructor.
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.
function mysockopen($host = "localhost", $port = 8090)
{
$fp = fsockopen($host, $port, $errno, $errstr);
if (!is_resource($fp)) {
return new PEAR_Error($errstr, $errno);
}
return $fp;
}
$sock = mysockopen();
if (PEAR::isError($sock)) {
print "mysockopen error: ".$sock->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:
class TCP_Socket extends PEAR
{
var $sock;
function TCP_Socket()
{
$this->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.
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:
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::setErrorHandling(PEAR_ERROR_CALLBACK, "my_function_handler");
do_some_stuff();
PEAR::setErrorHandling(PEAR_ERROR_DIE);
do_some_critical_stuff();
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK);
// now we're back to using my_function_handler again
