extlib/PEAR.php

   1 <?php
   2 /**
   3  * PEAR, the PHP Extension and Application Repository
   4  *
   5  * PEAR class and PEAR_Error class
   6  *
   7  * PHP versions 4 and 5
   8  *
   9  * LICENSE: This source file is subject to version 3.0 of the PHP license
  10  * that is available through the world-wide-web at the following URI:
  11  * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
  12  * the PHP License and are unable to obtain it through the web, please
  13  * send a note to license@php.net so we can mail you a copy immediately.
  14  *
  15  * @category   pear
  16  * @package    PEAR
  17  * @author     Sterling Hughes <sterling@php.net>
  18  * @author     Stig Bakken <ssb@php.net>
  19  * @author     Tomas V.V.Cox <cox@idecnet.com>
  20  * @author     Greg Beaver <cellog@php.net>
  21  * @copyright  1997-2008 The PHP Group
  22  * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
  23  * @version    CVS: $Id: PEAR.php,v 1.104 2008/01/03 20:26:34 cellog Exp $
  24  * @link       http://pear.php.net/package/PEAR
  25  * @since      File available since Release 0.1
  26  */
  27
  28 /**#@+
  29  * ERROR constants
  30  */
  31 define('PEAR_ERROR_RETURN',     1);
  32 define('PEAR_ERROR_PRINT',      2);
  33 define('PEAR_ERROR_TRIGGER',    4);
  34 define('PEAR_ERROR_DIE',        8);
  35 define('PEAR_ERROR_CALLBACK',  16);
  36 /**
  37  * WARNING: obsolete
  38  * @deprecated
  39  */
  40 define('PEAR_ERROR_EXCEPTION', 32);
  41 /**#@-*/
  42 define('PEAR_ZE2', (function_exists('version_compare') &&
  43                     version_compare(zend_version(), "2-dev", "ge")));
  44
  45 if (substr(PHP_OS, 0, 3) == 'WIN') {
  46     define('OS_WINDOWS', true);
  47     define('OS_UNIX',    false);
  48     define('PEAR_OS',    'Windows');
  49 } else {
  50     define('OS_WINDOWS', false);
  51     define('OS_UNIX',    true);
  52     define('PEAR_OS',    'Unix'); // blatant assumption
  53 }
  54
  55 // instant backwards compatibility
  56 if (!defined('PATH_SEPARATOR')) {
  57     if (OS_WINDOWS) {
  58         define('PATH_SEPARATOR', ';');
  59     } else {
  60         define('PATH_SEPARATOR', ':');
  61     }
  62 }
  63
  64 $GLOBALS['_PEAR_default_error_mode']     = PEAR_ERROR_RETURN;
  65 $GLOBALS['_PEAR_default_error_options']  = E_USER_NOTICE;
  66 $GLOBALS['_PEAR_destructor_object_list'] = array();
  67 $GLOBALS['_PEAR_shutdown_funcs']         = array();
  68 $GLOBALS['_PEAR_error_handler_stack']    = array();
  69
  70 @ini_set('track_errors', true);
  71
  72 /**
  73  * Base class for other PEAR classes.  Provides rudimentary
  74  * emulation of destructors.
  75  *
  76  * If you want a destructor in your class, inherit PEAR and make a
  77  * destructor method called _yourclassname (same name as the
  78  * constructor, but with a "_" prefix).  Also, in your constructor you
  79  * have to call the PEAR constructor: $this->PEAR();.
  80  * The destructor method will be called without parameters.  Note that
  81  * at in some SAPI implementations (such as Apache), any output during
  82  * the request shutdown (in which destructors are called) seems to be
  83  * discarded.  If you need to get any debug information from your
  84  * destructor, use error_log(), syslog() or something similar.
  85  *
  86  * IMPORTANT! To use the emulated destructors you need to create the
  87  * objects by reference: $obj =& new PEAR_child;
  88  *
  89  * @category   pear
  90  * @package    PEAR
  91  * @author     Stig Bakken <ssb@php.net>
  92  * @author     Tomas V.V. Cox <cox@idecnet.com>
  93  * @author     Greg Beaver <cellog@php.net>
  94  * @copyright  1997-2006 The PHP Group
  95  * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
  96  * @version    Release: 1.7.2
  97  * @link       http://pear.php.net/package/PEAR
  98  * @see        PEAR_Error
  99  * @since      Class available since PHP 4.0.2
 100  * @link        http://pear.php.net/manual/en/core.pear.php#core.pear.pear
 101  */
 102 class PEAR
 103 {
 104     // {{{ properties
 105
 106     /**
 107      * Whether to enable internal debug messages.
 108      *
 109      * @var     bool
 110      * @access  private
 111      */
 112     var $_debug = false;
 113
 114     /**
 115      * Default error mode for this object.
 116      *
 117      * @var     int
 118      * @access  private
 119      */
 120     var $_default_error_mode = null;
 121
 122     /**
 123      * Default error options used for this object when error mode
 124      * is PEAR_ERROR_TRIGGER.
 125      *
 126      * @var     int
 127      * @access  private
 128      */
 129     var $_default_error_options = null;
 130
 131     /**
 132      * Default error handler (callback) for this object, if error mode is
 133      * PEAR_ERROR_CALLBACK.
 134      *
 135      * @var     string
 136      * @access  private
 137      */
 138     var $_default_error_handler = '';
 139
 140     /**
 141      * Which class to use for error objects.
 142      *
 143      * @var     string
 144      * @access  private
 145      */
 146     var $_error_class = 'PEAR_Error';
 147
 148     /**
 149      * An array of expected errors.
 150      *
 151      * @var     array
 152      * @access  private
 153      */
 154     var $_expected_errors = array();
 155
 156     // }}}
 157
 158     // {{{ constructor
 159
 160     /**
 161      * Constructor.  Registers this object in
 162      * $_PEAR_destructor_object_list for destructor emulation if a
 163      * destructor object exists.
 164      *
 165      * @param string $error_class  (optional) which class to use for
 166      *        error objects, defaults to PEAR_Error.
 167      * @access public
 168      * @return void
 169      */
 170     function PEAR($error_class = null)
 171     {
 172         $classname = strtolower(get_class($this));
 173         if ($this->_debug) {
 174             print "PEAR constructor called, class=$classname\n";
 175         }
 176         if ($error_class !== null) {
 177             $this->_error_class = $error_class;
 178         }
 179         while ($classname && strcasecmp($classname, "pear")) {
 180             $destructor = "_$classname";
 181             if (method_exists($this, $destructor)) {
 182                 global $_PEAR_destructor_object_list;
 183                 $_PEAR_destructor_object_list[] = &$this;
 184                 if (!isset($GLOBALS['_PEAR_SHUTDOWN_REGISTERED'])) {
 185                     register_shutdown_function("_PEAR_call_destructors");
 186                     $GLOBALS['_PEAR_SHUTDOWN_REGISTERED'] = true;
 187                 }
 188                 break;
 189             } else {
 190                 $classname = get_parent_class($classname);
 191             }
 192         }
 193     }
 194
 195     // }}}
 196     // {{{ destructor
 197
 198     /**
 199      * Destructor (the emulated type of...).  Does nothing right now,
 200      * but is included for forward compatibility, so subclass
 201      * destructors should always call it.
 202      *
 203      * See the note in the class desciption about output from
 204      * destructors.
 205      *
 206      * @access public
 207      * @return void
 208      */
 209     function _PEAR() {
 210         if ($this->_debug) {
 211             printf("PEAR destructor called, class=%s\n", strtolower(get_class($this)));
 212         }
 213     }
 214
 215     // }}}
 216     // {{{ getStaticProperty()
 217
 218     /**
 219     * If you have a class that's mostly/entirely static, and you need static
 220     * properties, you can use this method to simulate them. Eg. in your method(s)
 221     * do this: $myVar = &PEAR::getStaticProperty('myclass', 'myVar');
 222     * You MUST use a reference, or they will not persist!
 223     *
 224     * @access public
 225     * @param  string $class  The calling classname, to prevent clashes
 226     * @param  string $var    The variable to retrieve.
 227     * @return mixed   A reference to the variable. If not set it will be
 228     *                 auto initialised to NULL.
 229     */
 230     function &getStaticProperty($class, $var)
 231     {
 232         static $properties;
 233         if (!isset($properties[$class])) {
 234             $properties[$class] = array();
 235         }
 236         if (!array_key_exists($var, $properties[$class])) {
 237             $properties[$class][$var] = null;
 238         }
 239         return $properties[$class][$var];
 240     }
 241
 242     // }}}
 243     // {{{ registerShutdownFunc()
 244
 245     /**
 246     * Use this function to register a shutdown method for static
 247     * classes.
 248     *
 249     * @access public
 250     * @param  mixed $func  The function name (or array of class/method) to call
 251     * @param  mixed $args  The arguments to pass to the function
 252     * @return void
 253     */
 254     function registerShutdownFunc($func, $args = array())
 255     {
 256         // if we are called statically, there is a potential
 257         // that no shutdown func is registered.  Bug #6445
 258         if (!isset($GLOBALS['_PEAR_SHUTDOWN_REGISTERED'])) {
 259             register_shutdown_function("_PEAR_call_destructors");
 260             $GLOBALS['_PEAR_SHUTDOWN_REGISTERED'] = true;
 261         }
 262         $GLOBALS['_PEAR_shutdown_funcs'][] = array($func, $args);
 263     }
 264
 265     // }}}
 266     // {{{ isError()
 267
 268     /**
 269      * Tell whether a value is a PEAR error.
 270      *
 271      * @param   mixed $data   the value to test
 272      * @param   int   $code   if $data is an error object, return true
 273      *                        only if $code is a string and
 274      *                        $obj->getMessage() == $code or
 275      *                        $code is an integer and $obj->getCode() == $code
 276      * @access  public
 277      * @return  bool    true if parameter is an error
 278      */
 279     function isError($data, $code = null)
 280     {
 281         if (is_a($data, 'PEAR_Error')) {
 282             if (is_null($code)) {
 283                 return true;
 284             } elseif (is_string($code)) {
 285                 return $data->getMessage() == $code;
 286             } else {
 287                 return $data->getCode() == $code;
 288             }
 289         }
 290         return false;
 291     }
 292
 293     // }}}
 294     // {{{ setErrorHandling()
 295
 296     /**
 297      * Sets how errors generated by this object should be handled.
 298      * Can be invoked both in objects and statically.  If called
 299      * statically, setErrorHandling sets the default behaviour for all
 300      * PEAR objects.  If called in an object, setErrorHandling sets
 301      * the default behaviour for that object.
 302      *
 303      * @param int $mode
 304      *        One of PEAR_ERROR_RETURN, PEAR_ERROR_PRINT,
 305      *        PEAR_ERROR_TRIGGER, PEAR_ERROR_DIE,
 306      *        PEAR_ERROR_CALLBACK or PEAR_ERROR_EXCEPTION.
 307      *
 308      * @param mixed $options
 309      *        When $mode is PEAR_ERROR_TRIGGER, this is the error level (one
 310      *        of E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR).
 311      *
 312      *        When $mode is PEAR_ERROR_CALLBACK, this parameter is expected
 313      *        to be the callback function or method.  A callback
 314      *        function is a string with the name of the function, a
 315      *        callback method is an array of two elements: the element
 316      *        at index 0 is the object, and the element at index 1 is
 317      *        the name of the method to call in the object.
 318      *
 319      *        When $mode is PEAR_ERROR_PRINT or PEAR_ERROR_DIE, this is
 320      *        a printf format string used when printing the error
 321      *        message.
 322      *
 323      * @access public
 324      * @return void
 325      * @see PEAR_ERROR_RETURN
 326      * @see PEAR_ERROR_PRINT
 327      * @see PEAR_ERROR_TRIGGER
 328      * @see PEAR_ERROR_DIE
 329      * @see PEAR_ERROR_CALLBACK
 330      * @see PEAR_ERROR_EXCEPTION
 331      *
 332      * @since PHP 4.0.5
 333      */
 334
 335     function setErrorHandling($mode = null, $options = null)
 336     {
 337         if (isset($this) && is_a($this, 'PEAR')) {
 338             $setmode     = &$this->_default_error_mode;
 339             $setoptions  = &$this->_default_error_options;
 340         } else {
 341             $setmode     = &$GLOBALS['_PEAR_default_error_mode'];
 342             $setoptions  = &$GLOBALS['_PEAR_default_error_options'];
 343         }
 344
 345         switch ($mode) {
 346             case PEAR_ERROR_EXCEPTION:
 347             case PEAR_ERROR_RETURN:
 348             case PEAR_ERROR_PRINT:
 349             case PEAR_ERROR_TRIGGER:
 350             case PEAR_ERROR_DIE:
 351             case null:
 352                 $setmode = $mode;
 353                 $setoptions = $options;
 354                 break;
 355
 356             case PEAR_ERROR_CALLBACK:
 357                 $setmode = $mode;
 358                 // class/object method callback
 359                 if (is_callable($options)) {
 360                     $setoptions = $options;
 361                 } else {
 362                     trigger_error("invalid error callback", E_USER_WARNING);
 363                 }
 364                 break;
 365
 366             default:
 367                 trigger_error("invalid error mode", E_USER_WARNING);
 368                 break;
 369         }
 370     }
 371
 372     // }}}
 373     // {{{ expectError()
 374
 375     /**
 376      * This method is used to tell which errors you expect to get.
 377      * Expected errors are always returned with error mode
 378      * PEAR_ERROR_RETURN.  Expected error codes are stored in a stack,
 379      * and this method pushes a new element onto it.  The list of
 380      * expected errors are in effect until they are popped off the
 381      * stack with the popExpect() method.
 382      *
 383      * Note that this method can not be called statically
 384      *
 385      * @param mixed $code a single error code or an array of error codes to expect
 386      *
 387      * @return int     the new depth of the "expected errors" stack
 388      * @access public
 389      */
 390     function expectError($code = '*')
 391     {
 392         if (is_array($code)) {
 393             array_push($this->_expected_errors, $code);
 394         } else {
 395             array_push($this->_expected_errors, array($code));
 396         }
 397         return sizeof($this->_expected_errors);
 398     }
 399
 400     // }}}
 401     // {{{ popExpect()
 402
 403     /**
 404      * This method pops one element off the expected error codes
 405      * stack.
 406      *
 407      * @return array   the list of error codes that were popped
 408      */
 409     function popExpect()
 410     {
 411         return array_pop($this->_expected_errors);
 412     }
 413
 414     // }}}
 415     // {{{ _checkDelExpect()
 416
 417     /**
 418      * This method checks unsets an error code if available
 419      *
 420      * @param mixed error code
 421      * @return bool true if the error code was unset, false otherwise
 422      * @access private
 423      * @since PHP 4.3.0
 424      */
 425     function _checkDelExpect($error_code)
 426     {
 427         $deleted = false;
 428
 429         foreach ($this->_expected_errors AS $key => $error_array) {
 430             if (in_array($error_code, $error_array)) {
 431                 unset($this->_expected_errors[$key][array_search($error_code, $error_array)]);
 432                 $deleted = true;
 433             }
 434
 435             // clean up empty arrays
 436             if (0 == count($this->_expected_errors[$key])) {
 437                 unset($this->_expected_errors[$key]);
 438             }
 439         }
 440         return $deleted;
 441     }
 442
 443     // }}}
 444     // {{{ delExpect()
 445
 446     /**
 447      * This method deletes all occurences of the specified element from
 448      * the expected error codes stack.
 449      *
 450      * @param  mixed $error_code error code that should be deleted
 451      * @return mixed list of error codes that were deleted or error
 452      * @access public
 453      * @since PHP 4.3.0
 454      */
 455     function delExpect($error_code)
 456     {
 457         $deleted = false;
 458
 459         if ((is_array($error_code) && (0 != count($error_code)))) {
 460             // $error_code is a non-empty array here;
 461             // we walk through it trying to unset all
 462             // values
 463             foreach($error_code as $key => $error) {
 464                 if ($this->_checkDelExpect($error)) {
 465                     $deleted =  true;
 466                 } else {
 467                     $deleted = false;
 468                 }
 469             }
 470             return $deleted ? true : PEAR::raiseError("The expected error you submitted does not exist"); // IMPROVE ME
 471         } elseif (!empty($error_code)) {
 472             // $error_code comes alone, trying to unset it
 473             if ($this->_checkDelExpect($error_code)) {
 474                 return true;
 475             } else {
 476                 return PEAR::raiseError("The expected error you submitted does not exist"); // IMPROVE ME
 477             }
 478         } else {
 479             // $error_code is empty
 480             return PEAR::raiseError("The expected error you submitted is empty"); // IMPROVE ME
 481         }
 482     }
 483
 484     // }}}
 485     // {{{ raiseError()
 486
 487     /**
 488      * This method is a wrapper that returns an instance of the
 489      * configured error class with this object's default error
 490      * handling applied.  If the $mode and $options parameters are not
 491      * specified, the object's defaults are used.
 492      *
 493      * @param mixed $message a text error message or a PEAR error object
 494      *
 495      * @param int $code      a numeric error code (it is up to your class
 496      *                  to define these if you want to use codes)
 497      *
 498      * @param int $mode      One of PEAR_ERROR_RETURN, PEAR_ERROR_PRINT,
 499      *                  PEAR_ERROR_TRIGGER, PEAR_ERROR_DIE,
 500      *                  PEAR_ERROR_CALLBACK, PEAR_ERROR_EXCEPTION.
 501      *
 502      * @param mixed $options If $mode is PEAR_ERROR_TRIGGER, this parameter
 503      *                  specifies the PHP-internal error level (one of
 504      *                  E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR).
 505      *                  If $mode is PEAR_ERROR_CALLBACK, this
 506      *                  parameter specifies the callback function or
 507      *                  method.  In other error modes this parameter
 508      *                  is ignored.
 509      *
 510      * @param string $userinfo If you need to pass along for example debug
 511      *                  information, this parameter is meant for that.
 512      *
 513      * @param string $error_class The returned error object will be
 514      *                  instantiated from this class, if specified.
 515      *
 516      * @param bool $skipmsg If true, raiseError will only pass error codes,
 517      *                  the error message parameter will be dropped.
 518      *
 519      * @access public
 520      * @return object   a PEAR error object
 521      * @see PEAR::setErrorHandling
 522      * @since PHP 4.0.5
 523      */
 524     function &raiseError($message = null,
 525                          $code = null,
 526                          $mode = null,
 527                          $options = null,
 528                          $userinfo = null,
 529                          $error_class = null,
 530                          $skipmsg = false)
 531     {
 532         // The error is yet a PEAR error object
 533         if (is_object($message)) {
 534             $code        = $message->getCode();
 535             $userinfo    = $message->getUserInfo();
 536             $error_class = $message->getType();
 537             $message->error_message_prefix = '';
 538             $message     = $message->getMessage();
 539         }
 540
 541         if (isset($this) && isset($this->_expected_errors) && sizeof($this->_expected_errors) > 0 && sizeof($exp = end($this->_expected_errors))) {
 542             if ($exp[0] == "*" ||
 543                 (is_int(reset($exp)) && in_array($code, $exp)) ||
 544                 (is_string(reset($exp)) && in_array($message, $exp))) {
 545                 $mode = PEAR_ERROR_RETURN;
 546             }
 547         }
 548         // No mode given, try global ones
 549         if ($mode === null) {
 550             // Class error handler
 551             if (isset($this) && isset($this->_default_error_mode)) {
 552                 $mode    = $this->_default_error_mode;
 553                 $options = $this->_default_error_options;
 554             // Global error handler
 555             } elseif (isset($GLOBALS['_PEAR_default_error_mode'])) {
 556                 $mode    = $GLOBALS['_PEAR_default_error_mode'];
 557                 $options = $GLOBALS['_PEAR_default_error_options'];
 558             }
 559         }
 560
 561         if ($error_class !== null) {
 562             $ec = $error_class;
 563         } elseif (isset($this) && isset($this->_error_class)) {
 564             $ec = $this->_error_class;
 565         } else {
 566             $ec = 'PEAR_Error';
 567         }
 568         if (intval(PHP_VERSION) < 5) {
 569             // little non-eval hack to fix bug #12147
 570             include 'PEAR/FixPHP5PEARWarnings.php';
 571             return $a;
 572         }
 573         if ($skipmsg) {
 574             $a = new $ec($code, $mode, $options, $userinfo);
 575         } else {
 576             $a = new $ec($message, $code, $mode, $options, $userinfo);
 577         }
 578         return $a;
 579     }
 580
 581     // }}}
 582     // {{{ throwError()
 583
 584     /**
 585      * Simpler form of raiseError with fewer options.  In most cases
 586      * message, code and userinfo are enough.
 587      *
 588      * @param string $message
 589      *
 590      */
 591     function &throwError($message = null,
 592                          $code = null,
 593                          $userinfo = null)
 594     {
 595         if (isset($this) && is_a($this, 'PEAR')) {
 596             $a = &$this->raiseError($message, $code, null, null, $userinfo);
 597             return $a;
 598         } else {
 599             $a = &PEAR::raiseError($message, $code, null, null, $userinfo);
 600             return $a;
 601         }
 602     }
 603
 604     // }}}
 605     function staticPushErrorHandling($mode, $options = null)
 606     {
 607         $stack = &$GLOBALS['_PEAR_error_handler_stack'];
 608         $def_mode    = &$GLOBALS['_PEAR_default_error_mode'];
 609         $def_options = &$GLOBALS['_PEAR_default_error_options'];
 610         $stack[] = array($def_mode, $def_options);
 611         switch ($mode) {
 612             case PEAR_ERROR_EXCEPTION:
 613             case PEAR_ERROR_RETURN:
 614             case PEAR_ERROR_PRINT:
 615             case PEAR_ERROR_TRIGGER:
 616             case PEAR_ERROR_DIE:
 617             case null:
 618                 $def_mode = $mode;
 619                 $def_options = $options;
 620                 break;
 621
 622             case PEAR_ERROR_CALLBACK:
 623                 $def_mode = $mode;
 624                 // class/object method callback
 625                 if (is_callable($options)) {
 626                     $def_options = $options;
 627                 } else {
 628                     trigger_error("invalid error callback", E_USER_WARNING);
 629                 }
 630                 break;
 631
 632             default:
 633                 trigger_error("invalid error mode", E_USER_WARNING);
 634                 break;
 635         }
 636         $stack[] = array($mode, $options);
 637         return true;
 638     }
 639
 640     function staticPopErrorHandling()
 641     {
 642         $stack = &$GLOBALS['_PEAR_error_handler_stack'];
 643         $setmode     = &$GLOBALS['_PEAR_default_error_mode'];
 644         $setoptions  = &$GLOBALS['_PEAR_default_error_options'];
 645         array_pop($stack);
 646         list($mode, $options) = $stack[sizeof($stack) - 1];
 647         array_pop($stack);
 648         switch ($mode) {
 649             case PEAR_ERROR_EXCEPTION:
 650             case PEAR_ERROR_RETURN:
 651             case PEAR_ERROR_PRINT:
 652             case PEAR_ERROR_TRIGGER:
 653             case PEAR_ERROR_DIE:
 654             case null:
 655                 $setmode = $mode;
 656                 $setoptions = $options;
 657                 break;
 658
 659             case PEAR_ERROR_CALLBACK:
 660                 $setmode = $mode;
 661                 // class/object method callback
 662                 if (is_callable($options)) {
 663                     $setoptions = $options;
 664                 } else {
 665                     trigger_error("invalid error callback", E_USER_WARNING);
 666                 }
 667                 break;
 668
 669             default:
 670                 trigger_error("invalid error mode", E_USER_WARNING);
 671                 break;
 672         }
 673         return true;
 674     }
 675
 676     // {{{ pushErrorHandling()
 677
 678     /**
 679      * Push a new error handler on top of the error handler options stack. With this
 680      * you can easily override the actual error handler for some code and restore
 681      * it later with popErrorHandling.
 682      *
 683      * @param mixed $mode (same as setErrorHandling)
 684      * @param mixed $options (same as setErrorHandling)
 685      *
 686      * @return bool Always true
 687      *
 688      * @see PEAR::setErrorHandling
 689      */
 690     function pushErrorHandling($mode, $options = null)
 691     {
 692         $stack = &$GLOBALS['_PEAR_error_handler_stack'];
 693         if (isset($this) && is_a($this, 'PEAR')) {
 694             $def_mode    = &$this->_default_error_mode;
 695             $def_options = &$this->_default_error_options;
 696         } else {
 697             $def_mode    = &$GLOBALS['_PEAR_default_error_mode'];
 698             $def_options = &$GLOBALS['_PEAR_default_error_options'];
 699         }
 700         $stack[] = array($def_mode, $def_options);
 701
 702         if (isset($this) && is_a($this, 'PEAR')) {
 703             $this->setErrorHandling($mode, $options);
 704         } else {
 705             PEAR::setErrorHandling($mode, $options);
 706         }
 707         $stack[] = array($mode, $options);
 708         return true;
 709     }
 710
 711     // }}}
 712     // {{{ popErrorHandling()
 713
 714     /**
 715     * Pop the last error handler used
 716     *
 717     * @return bool Always true
 718     *
 719     * @see PEAR::pushErrorHandling
 720     */
 721     function popErrorHandling()
 722     {
 723         $stack = &$GLOBALS['_PEAR_error_handler_stack'];
 724         array_pop($stack);
 725         list($mode, $options) = $stack[sizeof($stack) - 1];
 726         array_pop($stack);
 727         if (isset($this) && is_a($this, 'PEAR')) {
 728             $this->setErrorHandling($mode, $options);
 729         } else {
 730             PEAR::setErrorHandling($mode, $options);
 731         }
 732         return true;
 733     }
 734
 735     // }}}
 736     // {{{ loadExtension()
 737
 738     /**
 739     * OS independant PHP extension load. Remember to take care
 740     * on the correct extension name for case sensitive OSes.
 741     *
 742     * @param string $ext The extension name
 743     * @return bool Success or not on the dl() call
 744     */
 745     function loadExtension($ext)
 746     {
 747         if (!extension_loaded($ext)) {
 748             // if either returns true dl() will produce a FATAL error, stop that
 749             if ((ini_get('enable_dl') != 1) || (ini_get('safe_mode') == 1) || !function_exists('dl')) {
 750                 return false;
 751             }
 752             if (OS_WINDOWS) {
 753                 $suffix = '.dll';
 754             } elseif (PHP_OS == 'HP-UX') {
 755                 $suffix = '.sl';
 756             } elseif (PHP_OS == 'AIX') {
 757                 $suffix = '.a';
 758             } elseif (PHP_OS == 'OSX') {
 759                 $suffix = '.bundle';
 760             } else {
 761                 $suffix = '.so';
 762             }
 763             return @dl('php_'.$ext.$suffix) || @dl($ext.$suffix);
 764         }
 765         return true;
 766     }
 767
 768     // }}}
 769 }
 770
 771 // {{{ _PEAR_call_destructors()
 772
 773 function _PEAR_call_destructors()
 774 {
 775     global $_PEAR_destructor_object_list;
 776     if (is_array($_PEAR_destructor_object_list) &&
 777         sizeof($_PEAR_destructor_object_list))
 778     {
 779         reset($_PEAR_destructor_object_list);
 780         if (PEAR::getStaticProperty('PEAR', 'destructlifo')) {
 781             $_PEAR_destructor_object_list = array_reverse($_PEAR_destructor_object_list);
 782         }
 783         while (list($k, $objref) = each($_PEAR_destructor_object_list)) {
 784             $classname = get_class($objref);
 785             while ($classname) {
 786                 $destructor = "_$classname";
 787                 if (method_exists($objref, $destructor)) {
 788                     $objref->$destructor();
 789                     break;
 790                 } else {
 791                     $classname = get_parent_class($classname);
 792                 }
 793             }
 794         }
 795         // Empty the object list to ensure that destructors are
 796         // not called more than once.
 797         $_PEAR_destructor_object_list = array();
 798     }
 799
 800     // Now call the shutdown functions
 801     if (is_array($GLOBALS['_PEAR_shutdown_funcs']) AND !empty($GLOBALS['_PEAR_shutdown_funcs'])) {
 802         foreach ($GLOBALS['_PEAR_shutdown_funcs'] as $value) {
 803             call_user_func_array($value[0], $value[1]);
 804         }
 805     }
 806 }
 807
 808 // }}}
 809 /**
 810  * Standard PEAR error class for PHP 4
 811  *
 812  * This class is supserseded by {@link PEAR_Exception} in PHP 5
 813  *
 814  * @category   pear
 815  * @package    PEAR
 816  * @author     Stig Bakken <ssb@php.net>
 817  * @author     Tomas V.V. Cox <cox@idecnet.com>
 818  * @author     Gregory Beaver <cellog@php.net>
 819  * @copyright  1997-2006 The PHP Group
 820  * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 821  * @version    Release: 1.7.2
 822  * @link       http://pear.php.net/manual/en/core.pear.pear-error.php
 823  * @see        PEAR::raiseError(), PEAR::throwError()
 824  * @since      Class available since PHP 4.0.2
 825  */
 826 class PEAR_Error
 827 {
 828     // {{{ properties
 829
 830     var $error_message_prefix = '';
 831     var $mode                 = PEAR_ERROR_RETURN;
 832     var $level                = E_USER_NOTICE;
 833     var $code                 = -1;
 834     var $message              = '';
 835     var $userinfo             = '';
 836     var $backtrace            = null;
 837
 838     // }}}
 839     // {{{ constructor
 840
 841     /**
 842      * PEAR_Error constructor
 843      *
 844      * @param string $message  message
 845      *
 846      * @param int $code     (optional) error code
 847      *
 848      * @param int $mode     (optional) error mode, one of: PEAR_ERROR_RETURN,
 849      * PEAR_ERROR_PRINT, PEAR_ERROR_DIE, PEAR_ERROR_TRIGGER,
 850      * PEAR_ERROR_CALLBACK or PEAR_ERROR_EXCEPTION
 851      *
 852      * @param mixed $options   (optional) error level, _OR_ in the case of
 853      * PEAR_ERROR_CALLBACK, the callback function or object/method
 854      * tuple.
 855      *
 856      * @param string $userinfo (optional) additional user/debug info
 857      *
 858      * @access public
 859      *
 860      */
 861     function PEAR_Error($message = 'unknown error', $code = null,
 862                         $mode = null, $options = null, $userinfo = null)
 863     {
 864         if ($mode === null) {
 865             $mode = PEAR_ERROR_RETURN;
 866         }
 867         $this->message   = $message;
 868         $this->code      = $code;
 869         $this->mode      = $mode;
 870         $this->userinfo  = $userinfo;
 871         if (!PEAR::getStaticProperty('PEAR_Error', 'skiptrace')) {
 872             $this->backtrace = debug_backtrace();
 873             if (isset($this->backtrace[0]) && isset($this->backtrace[0]['object'])) {
 874                 unset($this->backtrace[0]['object']);
 875             }
 876         }
 877         if ($mode & PEAR_ERROR_CALLBACK) {
 878             $this->level = E_USER_NOTICE;
 879             $this->callback = $options;
 880         } else {
 881             if ($options === null) {
 882                 $options = E_USER_NOTICE;
 883             }
 884             $this->level = $options;
 885             $this->callback = null;
 886         }
 887         if ($this->mode & PEAR_ERROR_PRINT) {
 888             if (is_null($options) || is_int($options)) {
 889                 $format = "%s";
 890             } else {
 891                 $format = $options;
 892             }
 893             printf($format, $this->getMessage());
 894         }
 895         if ($this->mode & PEAR_ERROR_TRIGGER) {
 896             trigger_error($this->getMessage(), $this->level);
 897         }
 898         if ($this->mode & PEAR_ERROR_DIE) {
 899             $msg = $this->getMessage();
 900             if (is_null($options) || is_int($options)) {
 901                 $format = "%s";
 902                 if (substr($msg, -1) != "\n") {
 903                     $msg .= "\n";
 904                 }
 905             } else {
 906                 $format = $options;
 907             }
 908             die(sprintf($format, $msg));
 909         }
 910         if ($this->mode & PEAR_ERROR_CALLBACK) {
 911             if (is_callable($this->callback)) {
 912                 call_user_func($this->callback, $this);
 913             }
 914         }
 915         if ($this->mode & PEAR_ERROR_EXCEPTION) {
 916             trigger_error("PEAR_ERROR_EXCEPTION is obsolete, use class PEAR_Exception for exceptions", E_USER_WARNING);
 917             eval('$e = new Exception($this->message, $this->code);throw($e);');
 918         }
 919     }
 920
 921     // }}}
 922     // {{{ getMode()
 923
 924     /**
 925      * Get the error mode from an error object.
 926      *
 927      * @return int error mode
 928      * @access public
 929      */
 930     function getMode() {
 931         return $this->mode;
 932     }
 933
 934     // }}}
 935     // {{{ getCallback()
 936
 937     /**
 938      * Get the callback function/method from an error object.
 939      *
 940      * @return mixed callback function or object/method array
 941      * @access public
 942      */
 943     function getCallback() {
 944         return $this->callback;
 945     }
 946
 947     // }}}
 948     // {{{ getMessage()
 949
 950
 951     /**
 952      * Get the error message from an error object.
 953      *
 954      * @return  string  full error message
 955      * @access public
 956      */
 957     function getMessage()
 958     {
 959         return ($this->error_message_prefix . $this->message);
 960     }
 961
 962
 963     // }}}
 964     // {{{ getCode()
 965
 966     /**
 967      * Get error code from an error object
 968      *
 969      * @return int error code
 970      * @access public
 971      */
 972      function getCode()
 973      {
 974         return $this->code;
 975      }
 976
 977     // }}}
 978     // {{{ getType()
 979
 980     /**
 981      * Get the name of this error/exception.
 982      *
 983      * @return string error/exception name (type)
 984      * @access public
 985      */
 986     function getType()
 987     {
 988         return get_class($this);
 989     }
 990
 991     // }}}
 992     // {{{ getUserInfo()
 993
 994     /**
 995      * Get additional user-supplied information.
 996      *
 997      * @return string user-supplied information
 998      * @access public
 999      */
1000     function getUserInfo()
1001     {
1002         return $this->userinfo;
1003     }
1004
1005     // }}}
1006     // {{{ getDebugInfo()
1007
1008     /**
1009      * Get additional debug information supplied by the application.
1010      *
1011      * @return string debug information
1012      * @access public
1013      */
1014     function getDebugInfo()
1015     {
1016         return $this->getUserInfo();
1017     }
1018
1019     // }}}
1020     // {{{ getBacktrace()
1021
1022     /**
1023      * Get the call backtrace from where the error was generated.
1024      * Supported with PHP 4.3.0 or newer.
1025      *
1026      * @param int $frame (optional) what frame to fetch
1027      * @return array Backtrace, or NULL if not available.
1028      * @access public
1029      */
1030     function getBacktrace($frame = null)
1031     {
1032         if (defined('PEAR_IGNORE_BACKTRACE')) {
1033             return null;
1034         }
1035         if ($frame === null) {
1036             return $this->backtrace;
1037         }
1038         return $this->backtrace[$frame];
1039     }
1040
1041     // }}}
1042     // {{{ addUserInfo()
1043
1044     function addUserInfo($info)
1045     {
1046         if (empty($this->userinfo)) {
1047             $this->userinfo = $info;
1048         } else {
1049             $this->userinfo .= " ** $info";
1050         }
1051     }
1052
1053     // }}}
1054     // {{{ toString()
1055     function __toString()
1056     {
1057         return $this->getMessage();
1058     }
1059     // }}}
1060     // {{{ toString()
1061
1062     /**
1063      * Make a string representation of this object.
1064      *
1065      * @return string a string with an object summary
1066      * @access public
1067      */
1068     function toString() {
1069         $modes = array();
1070         $levels = array(E_USER_NOTICE  => 'notice',
1071                         E_USER_WARNING => 'warning',
1072                         E_USER_ERROR   => 'error');
1073         if ($this->mode & PEAR_ERROR_CALLBACK) {
1074             if (is_array($this->callback)) {
1075                 $callback = (is_object($this->callback[0]) ?
1076                     strtolower(get_class($this->callback[0])) :
1077                     $this->callback[0]) . '::' .
1078                     $this->callback[1];
1079             } else {
1080                 $callback = $this->callback;
1081             }
1082             return sprintf('[%s: message="%s" code=%d mode=callback '.
1083                            'callback=%s prefix="%s" info="%s"]',
1084                            strtolower(get_class($this)), $this->message, $this->code,
1085                            $callback, $this->error_message_prefix,
1086                            $this->userinfo);
1087         }
1088         if ($this->mode & PEAR_ERROR_PRINT) {
1089             $modes[] = 'print';
1090         }
1091         if ($this->mode & PEAR_ERROR_TRIGGER) {
1092             $modes[] = 'trigger';
1093         }
1094         if ($this->mode & PEAR_ERROR_DIE) {
1095             $modes[] = 'die';
1096         }
1097         if ($this->mode & PEAR_ERROR_RETURN) {
1098             $modes[] = 'return';
1099         }
1100         return sprintf('[%s: message="%s" code=%d mode=%s level=%s '.
1101                        'prefix="%s" info="%s"]',
1102                        strtolower(get_class($this)), $this->message, $this->code,
1103                        implode("|", $modes), $levels[$this->level],
1104                        $this->error_message_prefix,
1105                        $this->userinfo);
1106     }
1107
1108     // }}}
1109 }
1110
1111 /*
1112  * Local Variables:
1113  * mode: php
1114  * tab-width: 4
1115  * c-basic-offset: 4
1116  * End:
1117  */
1118 ?>