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