[Summary view] [Print] [Text view]

   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-2006 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.98 2006/01/23 05:38:05 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.4.11
  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          return $properties[$class][$var];
 234      }
 235  
 236      // }}}
 237      // {{{ registerShutdownFunc()
 238  
 239      /**
 240      * Use this function to register a shutdown method for static
 241      * classes.
 242      *
 243      * @access public
 244      * @param  mixed $func  The function name (or array of class/method) to call
 245      * @param  mixed $args  The arguments to pass to the function
 246      * @return void
 247      */
 248      function registerShutdownFunc($func, $args = array())
 249      {
 250          // if we are called statically, there is a potential
 251          // that no shutdown func is registered.  Bug #6445
 252          if (!isset($GLOBALS['_PEAR_SHUTDOWN_REGISTERED'])) {
 253              register_shutdown_function("_PEAR_call_destructors");
 254              $GLOBALS['_PEAR_SHUTDOWN_REGISTERED'] = true;
 255          }
 256          $GLOBALS['_PEAR_shutdown_funcs'][] = array($func, $args);
 257      }
 258  
 259      // }}}
 260      // {{{ isError()
 261  
 262      /**
 263       * Tell whether a value is a PEAR error.
 264       *
 265       * @param   mixed $data   the value to test
 266       * @param   int   $code   if $data is an error object, return true
 267       *                        only if $code is a string and
 268       *                        $obj->getMessage() == $code or
 269       *                        $code is an integer and $obj->getCode() == $code
 270       * @access  public
 271       * @return  bool    true if parameter is an error
 272       */
 273      function isError($data, $code = null)
 274      {
 275          if (is_a($data, 'PEAR_Error')) {
 276              if (is_null($code)) {
 277                  return true;
 278              } elseif (is_string($code)) {
 279                  return $data->getMessage() == $code;
 280              } else {
 281                  return $data->getCode() == $code;
 282              }
 283          }
 284          return false;
 285      }
 286  
 287      // }}}
 288      // {{{ setErrorHandling()
 289  
 290      /**
 291       * Sets how errors generated by this object should be handled.
 292       * Can be invoked both in objects and statically.  If called
 293       * statically, setErrorHandling sets the default behaviour for all
 294       * PEAR objects.  If called in an object, setErrorHandling sets
 295       * the default behaviour for that object.
 296       *
 297       * @param int $mode
 298       *        One of PEAR_ERROR_RETURN, PEAR_ERROR_PRINT,
 299       *        PEAR_ERROR_TRIGGER, PEAR_ERROR_DIE,
 300       *        PEAR_ERROR_CALLBACK or PEAR_ERROR_EXCEPTION.
 301       *
 302       * @param mixed $options
 303       *        When $mode is PEAR_ERROR_TRIGGER, this is the error level (one
 304       *        of E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR).
 305       *
 306       *        When $mode is PEAR_ERROR_CALLBACK, this parameter is expected
 307       *        to be the callback function or method.  A callback
 308       *        function is a string with the name of the function, a
 309       *        callback method is an array of two elements: the element
 310       *        at index 0 is the object, and the element at index 1 is
 311       *        the name of the method to call in the object.
 312       *
 313       *        When $mode is PEAR_ERROR_PRINT or PEAR_ERROR_DIE, this is
 314       *        a printf format string used when printing the error
 315       *        message.
 316       *
 317       * @access public
 318       * @return void
 319       * @see PEAR_ERROR_RETURN
 320       * @see PEAR_ERROR_PRINT
 321       * @see PEAR_ERROR_TRIGGER
 322       * @see PEAR_ERROR_DIE
 323       * @see PEAR_ERROR_CALLBACK
 324       * @see PEAR_ERROR_EXCEPTION
 325       *
 326       * @since PHP 4.0.5
 327       */
 328  
 329      function setErrorHandling($mode = null, $options = null)
 330      {
 331          if (isset($this) && is_a($this, 'PEAR')) {
 332              $setmode     = &$this->_default_error_mode;
 333              $setoptions  = &$this->_default_error_options;
 334          } else {
 335              $setmode     = &$GLOBALS['_PEAR_default_error_mode'];
 336              $setoptions  = &$GLOBALS['_PEAR_default_error_options'];
 337          }
 338  
 339          switch ($mode) {
 340              case PEAR_ERROR_EXCEPTION:
 341              case PEAR_ERROR_RETURN:
 342              case PEAR_ERROR_PRINT:
 343              case PEAR_ERROR_TRIGGER:
 344              case PEAR_ERROR_DIE:
 345              case null:
 346                  $setmode = $mode;
 347                  $setoptions = $options;
 348                  break;
 349  
 350              case PEAR_ERROR_CALLBACK:
 351                  $setmode = $mode;
 352                  // class/object method callback
 353                  if (is_callable($options)) {
 354                      $setoptions = $options;
 355                  } else {
 356                      trigger_error("invalid error callback", E_USER_WARNING);
 357                  }
 358                  break;
 359  
 360              default:
 361                  trigger_error("invalid error mode", E_USER_WARNING);
 362                  break;
 363          }
 364      }
 365  
 366      // }}}
 367      // {{{ expectError()
 368  
 369      /**
 370       * This method is used to tell which errors you expect to get.
 371       * Expected errors are always returned with error mode
 372       * PEAR_ERROR_RETURN.  Expected error codes are stored in a stack,
 373       * and this method pushes a new element onto it.  The list of
 374       * expected errors are in effect until they are popped off the
 375       * stack with the popExpect() method.
 376       *
 377       * Note that this method can not be called statically
 378       *
 379       * @param mixed $code a single error code or an array of error codes to expect
 380       *
 381       * @return int     the new depth of the "expected errors" stack
 382       * @access public
 383       */
 384      function expectError($code = '*')
 385      {
 386          if (is_array($code)) {
 387              array_push($this->_expected_errors, $code);
 388          } else {
 389              array_push($this->_expected_errors, array($code));
 390          }
 391          return sizeof($this->_expected_errors);
 392      }
 393  
 394      // }}}
 395      // {{{ popExpect()
 396  
 397      /**
 398       * This method pops one element off the expected error codes
 399       * stack.
 400       *
 401       * @return array   the list of error codes that were popped
 402       */
 403      function popExpect()
 404      {
 405          return array_pop($this->_expected_errors);
 406      }
 407  
 408      // }}}
 409      // {{{ _checkDelExpect()
 410  
 411      /**
 412       * This method checks unsets an error code if available
 413       *
 414       * @param mixed error code
 415       * @return bool true if the error code was unset, false otherwise
 416       * @access private
 417       * @since PHP 4.3.0
 418       */
 419      function _checkDelExpect($error_code)
 420      {
 421          $deleted = false;
 422  
 423          foreach ($this->_expected_errors AS $key => $error_array) {
 424              if (in_array($error_code, $error_array)) {
 425                  unset($this->_expected_errors[$key][array_search($error_code, $error_array)]);
 426                  $deleted = true;
 427              }
 428  
 429              // clean up empty arrays
 430              if (0 == count($this->_expected_errors[$key])) {
 431                  unset($this->_expected_errors[$key]);
 432              }
 433          }
 434          return $deleted;
 435      }
 436  
 437      // }}}
 438      // {{{ delExpect()
 439  
 440      /**
 441       * This method deletes all occurences of the specified element from
 442       * the expected error codes stack.
 443       *
 444       * @param  mixed $error_code error code that should be deleted
 445       * @return mixed list of error codes that were deleted or error
 446       * @access public
 447       * @since PHP 4.3.0
 448       */
 449      function delExpect($error_code)
 450      {
 451          $deleted = false;
 452  
 453          if ((is_array($error_code) && (0 != count($error_code)))) {
 454              // $error_code is a non-empty array here;
 455              // we walk through it trying to unset all
 456              // values
 457              foreach($error_code as $key => $error) {
 458                  if ($this->_checkDelExpect($error)) {
 459                      $deleted =  true;
 460                  } else {
 461                      $deleted = false;
 462                  }
 463              }
 464              return $deleted ? true : PEAR::raiseError("The expected error you submitted does not exist"); // IMPROVE ME
 465          } elseif (!empty($error_code)) {
 466              // $error_code comes alone, trying to unset it
 467              if ($this->_checkDelExpect($error_code)) {
 468                  return true;
 469              } else {
 470                  return PEAR::raiseError("The expected error you submitted does not exist"); // IMPROVE ME
 471              }
 472          } else {
 473              // $error_code is empty
 474              return PEAR::raiseError("The expected error you submitted is empty"); // IMPROVE ME
 475          }
 476      }
 477  
 478      // }}}
 479      // {{{ raiseError()
 480  
 481      /**
 482       * This method is a wrapper that returns an instance of the
 483       * configured error class with this object's default error
 484       * handling applied.  If the $mode and $options parameters are not
 485       * specified, the object's defaults are used.
 486       *
 487       * @param mixed $message a text error message or a PEAR error object
 488       *
 489       * @param int $code      a numeric error code (it is up to your class
 490       *                  to define these if you want to use codes)
 491       *
 492       * @param int $mode      One of PEAR_ERROR_RETURN, PEAR_ERROR_PRINT,
 493       *                  PEAR_ERROR_TRIGGER, PEAR_ERROR_DIE,
 494       *                  PEAR_ERROR_CALLBACK, PEAR_ERROR_EXCEPTION.
 495       *
 496       * @param mixed $options If $mode is PEAR_ERROR_TRIGGER, this parameter
 497       *                  specifies the PHP-internal error level (one of
 498       *                  E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR).
 499       *                  If $mode is PEAR_ERROR_CALLBACK, this
 500       *                  parameter specifies the callback function or
 501       *                  method.  In other error modes this parameter
 502       *                  is ignored.
 503       *
 504       * @param string $userinfo If you need to pass along for example debug
 505       *                  information, this parameter is meant for that.
 506       *
 507       * @param string $error_class The returned error object will be
 508       *                  instantiated from this class, if specified.
 509       *
 510       * @param bool $skipmsg If true, raiseError will only pass error codes,
 511       *                  the error message parameter will be dropped.
 512       *
 513       * @access public
 514       * @return object   a PEAR error object
 515       * @see PEAR::setErrorHandling
 516       * @since PHP 4.0.5
 517       */
 518      function &raiseError($message = null,
 519                           $code = null,
 520                           $mode = null,
 521                           $options = null,
 522                           $userinfo = null,
 523                           $error_class = null,
 524                           $skipmsg = false)
 525      {
 526          // The error is yet a PEAR error object
 527          if (is_object($message)) {
 528              $code        = $message->getCode();
 529              $userinfo    = $message->getUserInfo();
 530              $error_class = $message->getType();
 531              $message->error_message_prefix = '';
 532              $message     = $message->getMessage();
 533          }
 534  
 535          if (isset($this) && isset($this->_expected_errors) && sizeof($this->_expected_errors) > 0 && sizeof($exp = end($this->_expected_errors))) {
 536              if ($exp[0] == "*" ||
 537                  (is_int(reset($exp)) && in_array($code, $exp)) ||
 538                  (is_string(reset($exp)) && in_array($message, $exp))) {
 539                  $mode = PEAR_ERROR_RETURN;
 540              }
 541          }
 542          // No mode given, try global ones
 543          if ($mode === null) {
 544              // Class error handler
 545              if (isset($this) && isset($this->_default_error_mode)) {
 546                  $mode    = $this->_default_error_mode;
 547                  $options = $this->_default_error_options;
 548              // Global error handler
 549              } elseif (isset($GLOBALS['_PEAR_default_error_mode'])) {
 550                  $mode    = $GLOBALS['_PEAR_default_error_mode'];
 551                  $options = $GLOBALS['_PEAR_default_error_options'];
 552              }
 553          }
 554  
 555          if ($error_class !== null) {
 556              $ec = $error_class;
 557          } elseif (isset($this) && isset($this->_error_class)) {
 558              $ec = $this->_error_class;
 559          } else {
 560              $ec = 'PEAR_Error';
 561          }
 562          if ($skipmsg) {
 563              $a = &new $ec($code, $mode, $options, $userinfo);
 564              return $a;
 565          } else {
 566              $a = &new $ec($message, $code, $mode, $options, $userinfo);
 567              return $a;
 568          }
 569      }
 570  
 571      // }}}
 572      // {{{ throwError()
 573  
 574      /**
 575       * Simpler form of raiseError with fewer options.  In most cases
 576       * message, code and userinfo are enough.
 577       *
 578       * @param string $message
 579       *
 580       */
 581      function &throwError($message = null,
 582                           $code = null,
 583                           $userinfo = null)
 584      {
 585          if (isset($this) && is_a($this, 'PEAR')) {
 586              $a = &$this->raiseError($message, $code, null, null, $userinfo);
 587              return $a;
 588          } else {
 589              $a = &PEAR::raiseError($message, $code, null, null, $userinfo);
 590              return $a;
 591          }
 592      }
 593  
 594      // }}}
 595      function staticPushErrorHandling($mode, $options = null)
 596      {
 597          $stack = &$GLOBALS['_PEAR_error_handler_stack'];
 598          $def_mode    = &$GLOBALS['_PEAR_default_error_mode'];
 599          $def_options = &$GLOBALS['_PEAR_default_error_options'];
 600          $stack[] = array($def_mode, $def_options);
 601          switch ($mode) {
 602              case PEAR_ERROR_EXCEPTION:
 603              case PEAR_ERROR_RETURN:
 604              case PEAR_ERROR_PRINT:
 605              case PEAR_ERROR_TRIGGER:
 606              case PEAR_ERROR_DIE:
 607              case null:
 608                  $def_mode = $mode;
 609                  $def_options = $options;
 610                  break;
 611  
 612              case PEAR_ERROR_CALLBACK:
 613                  $def_mode = $mode;
 614                  // class/object method callback
 615                  if (is_callable($options)) {
 616                      $def_options = $options;
 617                  } else {
 618                      trigger_error("invalid error callback", E_USER_WARNING);
 619                  }
 620                  break;
 621  
 622              default:
 623                  trigger_error("invalid error mode", E_USER_WARNING);
 624                  break;
 625          }
 626          $stack[] = array($mode, $options);
 627          return true;
 628      }
 629  
 630      function staticPopErrorHandling()
 631      {
 632          $stack = &$GLOBALS['_PEAR_error_handler_stack'];
 633          $setmode     = &$GLOBALS['_PEAR_default_error_mode'];
 634          $setoptions  = &$GLOBALS['_PEAR_default_error_options'];
 635          array_pop($stack);
 636          list($mode, $options) = $stack[sizeof($stack) - 1];
 637          array_pop($stack);
 638          switch ($mode) {
 639              case PEAR_ERROR_EXCEPTION:
 640              case PEAR_ERROR_RETURN:
 641              case PEAR_ERROR_PRINT:
 642              case PEAR_ERROR_TRIGGER:
 643              case PEAR_ERROR_DIE:
 644              case null:
 645                  $setmode = $mode;
 646                  $setoptions = $options;
 647                  break;
 648  
 649              case PEAR_ERROR_CALLBACK:
 650                  $setmode = $mode;
 651                  // class/object method callback
 652                  if (is_callable($options)) {
 653                      $setoptions = $options;
 654                  } else {
 655                      trigger_error("invalid error callback", E_USER_WARNING);
 656                  }
 657                  break;
 658  
 659              default:
 660                  trigger_error("invalid error mode", E_USER_WARNING);
 661                  break;
 662          }
 663          return true;
 664      }
 665  
 666      // {{{ pushErrorHandling()
 667  
 668      /**
 669       * Push a new error handler on top of the error handler options stack. With this
 670       * you can easily override the actual error handler for some code and restore
 671       * it later with popErrorHandling.
 672       *
 673       * @param mixed $mode (same as setErrorHandling)
 674       * @param mixed $options (same as setErrorHandling)
 675       *
 676       * @return bool Always true
 677       *
 678       * @see PEAR::setErrorHandling
 679       */
 680      function pushErrorHandling($mode, $options = null)
 681      {
 682          $stack = &$GLOBALS['_PEAR_error_handler_stack'];
 683          if (isset($this) && is_a($this, 'PEAR')) {
 684              $def_mode    = &$this->_default_error_mode;
 685              $def_options = &$this->_default_error_options;
 686          } else {
 687              $def_mode    = &$GLOBALS['_PEAR_default_error_mode'];
 688              $def_options = &$GLOBALS['_PEAR_default_error_options'];
 689          }
 690          $stack[] = array($def_mode, $def_options);
 691  
 692          if (isset($this) && is_a($this, 'PEAR')) {
 693              $this->setErrorHandling($mode, $options);
 694          } else {
 695              PEAR::setErrorHandling($mode, $options);
 696          }
 697          $stack[] = array($mode, $options);
 698          return true;
 699      }
 700  
 701      // }}}
 702      // {{{ popErrorHandling()
 703  
 704      /**
 705      * Pop the last error handler used
 706      *
 707      * @return bool Always true
 708      *
 709      * @see PEAR::pushErrorHandling
 710      */
 711      function popErrorHandling()
 712      {
 713          $stack = &$GLOBALS['_PEAR_error_handler_stack'];
 714          array_pop($stack);
 715          list($mode, $options) = $stack[sizeof($stack) - 1];
 716          array_pop($stack);
 717          if (isset($this) && is_a($this, 'PEAR')) {
 718              $this->setErrorHandling($mode, $options);
 719          } else {
 720              PEAR::setErrorHandling($mode, $options);
 721          }
 722          return true;
 723      }
 724  
 725      // }}}
 726      // {{{ loadExtension()
 727  
 728      /**
 729      * OS independant PHP extension load. Remember to take care
 730      * on the correct extension name for case sensitive OSes.
 731      *
 732      * @param string $ext The extension name
 733      * @return bool Success or not on the dl() call
 734      */
 735      function loadExtension($ext)
 736      {
 737          if (!extension_loaded($ext)) {
 738              // if either returns true dl() will produce a FATAL error, stop that
 739              if ((ini_get('enable_dl') != 1) || (ini_get('safe_mode') == 1)) {
 740                  return false;
 741              }
 742              if (OS_WINDOWS) {
 743                  $suffix = '.dll';
 744              } elseif (PHP_OS == 'HP-UX') {
 745                  $suffix = '.sl';
 746              } elseif (PHP_OS == 'AIX') {
 747                  $suffix = '.a';
 748              } elseif (PHP_OS == 'OSX') {
 749                  $suffix = '.bundle';
 750              } else {
 751                  $suffix = '.so';
 752              }
 753              return @dl('php_'.$ext.$suffix) || @dl($ext.$suffix);
 754          }
 755          return true;
 756      }
 757  
 758      // }}}
 759  }
 760  
 761  // {{{ _PEAR_call_destructors()
 762  
 763  function _PEAR_call_destructors()
 764  {
 765      global $_PEAR_destructor_object_list;
 766      if (is_array($_PEAR_destructor_object_list) &&
 767          sizeof($_PEAR_destructor_object_list))
 768      {
 769          reset($_PEAR_destructor_object_list);
 770          if (@PEAR::getStaticProperty('PEAR', 'destructlifo')) {
 771              $_PEAR_destructor_object_list = array_reverse($_PEAR_destructor_object_list);
 772          }
 773          while (list($k, $objref) = each($_PEAR_destructor_object_list)) {
 774              $classname = get_class($objref);
 775              while ($classname) {
 776                  $destructor = "_$classname";
 777                  if (method_exists($objref, $destructor)) {
 778                      $objref->$destructor();
 779                      break;
 780                  } else {
 781                      $classname = get_parent_class($classname);
 782                  }
 783              }
 784          }
 785          // Empty the object list to ensure that destructors are
 786          // not called more than once.
 787          $_PEAR_destructor_object_list = array();
 788      }
 789  
 790      // Now call the shutdown functions
 791      if (is_array($GLOBALS['_PEAR_shutdown_funcs']) AND !empty($GLOBALS['_PEAR_shutdown_funcs'])) {
 792          foreach ($GLOBALS['_PEAR_shutdown_funcs'] as $value) {
 793              call_user_func_array($value[0], $value[1]);
 794          }
 795      }
 796  }
 797  
 798  // }}}
 799  /**
 800   * Standard PEAR error class for PHP 4
 801   *
 802   * This class is supserseded by {@link PEAR_Exception} in PHP 5
 803   *
 804   * @category   pear
 805   * @package    PEAR
 806   * @author     Stig Bakken <ssb@php.net>
 807   * @author     Tomas V.V. Cox <cox@idecnet.com>
 808   * @author     Gregory Beaver <cellog@php.net>
 809   * @copyright  1997-2006 The PHP Group
 810   * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 811   * @version    Release: 1.4.11
 812   * @link       http://pear.php.net/manual/en/core.pear.pear-error.php
 813   * @see        PEAR::raiseError(), PEAR::throwError()
 814   * @since      Class available since PHP 4.0.2
 815   */
 816  class PEAR_Error
 817  {
 818      // {{{ properties
 819  
 820      var $error_message_prefix = '';
 821      var $mode                 = PEAR_ERROR_RETURN;
 822      var $level                = E_USER_NOTICE;
 823      var $code                 = -1;
 824      var $message              = '';
 825      var $userinfo             = '';
 826      var $backtrace            = null;
 827  
 828      // }}}
 829      // {{{ constructor
 830  
 831      /**
 832       * PEAR_Error constructor
 833       *
 834       * @param string $message  message
 835       *
 836       * @param int $code     (optional) error code
 837       *
 838       * @param int $mode     (optional) error mode, one of: PEAR_ERROR_RETURN,
 839       * PEAR_ERROR_PRINT, PEAR_ERROR_DIE, PEAR_ERROR_TRIGGER,
 840       * PEAR_ERROR_CALLBACK or PEAR_ERROR_EXCEPTION
 841       *
 842       * @param mixed $options   (optional) error level, _OR_ in the case of
 843       * PEAR_ERROR_CALLBACK, the callback function or object/method
 844       * tuple.
 845       *
 846       * @param string $userinfo (optional) additional user/debug info
 847       *
 848       * @access public
 849       *
 850       */
 851      function PEAR_Error($message = 'unknown error', $code = null,
 852                          $mode = null, $options = null, $userinfo = null)
 853      {
 854          if ($mode === null) {
 855              $mode = PEAR_ERROR_RETURN;
 856          }
 857          $this->message   = $message;
 858          $this->code      = $code;
 859          $this->mode      = $mode;
 860          $this->userinfo  = $userinfo;
 861          if (function_exists("debug_backtrace")) {
 862              if (@!PEAR::getStaticProperty('PEAR_Error', 'skiptrace')) {
 863                  $this->backtrace = debug_backtrace();
 864              }
 865          }
 866          if ($mode & PEAR_ERROR_CALLBACK) {
 867              $this->level = E_USER_NOTICE;
 868              $this->callback = $options;
 869          } else {
 870              if ($options === null) {
 871                  $options = E_USER_NOTICE;
 872              }
 873              $this->level = $options;
 874              $this->callback = null;
 875          }
 876          if ($this->mode & PEAR_ERROR_PRINT) {
 877              if (is_null($options) || is_int($options)) {
 878                  $format = "%s";
 879              } else {
 880                  $format = $options;
 881              }
 882              printf($format, $this->getMessage());
 883          }
 884          if ($this->mode & PEAR_ERROR_TRIGGER) {
 885              trigger_error($this->getMessage(), $this->level);
 886          }
 887          if ($this->mode & PEAR_ERROR_DIE) {
 888              $msg = $this->getMessage();
 889              if (is_null($options) || is_int($options)) {
 890                  $format = "%s";
 891                  if (substr($msg, -1) != "\n") {
 892                      $msg .= "\n";
 893                  }
 894              } else {
 895                  $format = $options;
 896              }
 897              die(sprintf($format, $msg));
 898          }
 899          if ($this->mode & PEAR_ERROR_CALLBACK) {
 900              if (is_callable($this->callback)) {
 901                  call_user_func($this->callback, $this);
 902              }
 903          }
 904          if ($this->mode & PEAR_ERROR_EXCEPTION) {
 905              trigger_error("PEAR_ERROR_EXCEPTION is obsolete, use class PEAR_Exception for exceptions", E_USER_WARNING);
 906              eval('$e = new Exception($this->message, $this->code);throw($e);');
 907          }
 908      }
 909  
 910      // }}}
 911      // {{{ getMode()
 912  
 913      /**
 914       * Get the error mode from an error object.
 915       *
 916       * @return int error mode
 917       * @access public
 918       */
 919      function getMode() {
 920          return $this->mode;
 921      }
 922  
 923      // }}}
 924      // {{{ getCallback()
 925  
 926      /**
 927       * Get the callback function/method from an error object.
 928       *
 929       * @return mixed callback function or object/method array
 930       * @access public
 931       */
 932      function getCallback() {
 933          return $this->callback;
 934      }
 935  
 936      // }}}
 937      // {{{ getMessage()
 938  
 939  
 940      /**
 941       * Get the error message from an error object.
 942       *
 943       * @return  string  full error message
 944       * @access public
 945       */
 946      function getMessage()
 947      {
 948          return ($this->error_message_prefix . $this->message);
 949      }
 950  
 951  
 952      // }}}
 953      // {{{ getCode()
 954  
 955      /**
 956       * Get error code from an error object
 957       *
 958       * @return int error code
 959       * @access public
 960       */
 961       function getCode()
 962       {
 963          return $this->code;
 964       }
 965  
 966      // }}}
 967      // {{{ getType()
 968  
 969      /**
 970       * Get the name of this error/exception.
 971       *
 972       * @return string error/exception name (type)
 973       * @access public
 974       */
 975      function getType()
 976      {
 977          return get_class($this);
 978      }
 979  
 980      // }}}
 981      // {{{ getUserInfo()
 982  
 983      /**
 984       * Get additional user-supplied information.
 985       *
 986       * @return string user-supplied information
 987       * @access public
 988       */
 989      function getUserInfo()
 990      {
 991          return $this->userinfo;
 992      }
 993  
 994      // }}}
 995      // {{{ getDebugInfo()
 996  
 997      /**
 998       * Get additional debug information supplied by the application.
 999       *
1000       * @return string debug information
1001       * @access public
1002       */
1003      function getDebugInfo()
1004      {
1005          return $this->getUserInfo();
1006      }
1007  
1008      // }}}
1009      // {{{ getBacktrace()
1010  
1011      /**
1012       * Get the call backtrace from where the error was generated.
1013       * Supported with PHP 4.3.0 or newer.
1014       *
1015       * @param int $frame (optional) what frame to fetch
1016       * @return array Backtrace, or NULL if not available.
1017       * @access public
1018       */
1019      function getBacktrace($frame = null)
1020      {
1021          if (defined('PEAR_IGNORE_BACKTRACE')) {
1022              return null;
1023          }
1024          if ($frame === null) {
1025              return $this->backtrace;
1026          }
1027          return $this->backtrace[$frame];
1028      }
1029  
1030      // }}}
1031      // {{{ addUserInfo()
1032  
1033      function addUserInfo($info)
1034      {
1035          if (empty($this->userinfo)) {
1036              $this->userinfo = $info;
1037          } else {
1038              $this->userinfo .= " ** $info";
1039          }
1040      }
1041  
1042      // }}}
1043      // {{{ toString()
1044  
1045      /**
1046       * Make a string representation of this object.
1047       *
1048       * @return string a string with an object summary
1049       * @access public
1050       */
1051      function toString() {
1052          $modes = array();
1053          $levels = array(E_USER_NOTICE  => 'notice',
1054                          E_USER_WARNING => 'warning',
1055                          E_USER_ERROR   => 'error');
1056          if ($this->mode & PEAR_ERROR_CALLBACK) {
1057              if (is_array($this->callback)) {
1058                  $callback = (is_object($this->callback[0]) ?
1059                      strtolower(get_class($this->callback[0])) :
1060                      $this->callback[0]) . '::' .
1061                      $this->callback[1];
1062              } else {
1063                  $callback = $this->callback;
1064              }
1065              return sprintf('[%s: message="%s" code=%d mode=callback '.
1066                             'callback=%s prefix="%s" info="%s"]',
1067                             strtolower(get_class($this)), $this->message, $this->code,
1068                             $callback, $this->error_message_prefix,
1069                             $this->userinfo);
1070          }
1071          if ($this->mode & PEAR_ERROR_PRINT) {
1072              $modes[] = 'print';
1073          }
1074          if ($this->mode & PEAR_ERROR_TRIGGER) {
1075              $modes[] = 'trigger';
1076          }
1077          if ($this->mode & PEAR_ERROR_DIE) {
1078              $modes[] = 'die';
1079          }
1080          if ($this->mode & PEAR_ERROR_RETURN) {
1081              $modes[] = 'return';
1082          }
1083          return sprintf('[%s: message="%s" code=%d mode=%s level=%s '.
1084                         'prefix="%s" info="%s"]',
1085                         strtolower(get_class($this)), $this->message, $this->code,
1086                         implode("|", $modes), $levels[$this->level],
1087                         $this->error_message_prefix,
1088                         $this->userinfo);
1089      }
1090  
1091      // }}}
1092  }
1093  
1094  /*
1095   * Local Variables:
1096   * mode: php
1097   * tab-width: 4
1098   * c-basic-offset: 4
1099   * End:
1100   */
1101  ?>