[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * patErrorManager main error management class used by pat tools for the
   4   * application-internal error management. Creates patError objects for
   5   * any errors for precise error management.
   6   *
   7   *    $Id: patErrorManager.php 12694 2009-09-11 21:03:02Z ian $
   8   *
   9   * @package    patError
  10   */
  11  
  12  /**
  13   * error definition: illegal options.
  14   */
  15  define( 'PATERRORMANAGER_ERROR_ILLEGAL_OPTIONS', 1 );
  16  
  17  /**
  18   * error definition: callback function does not exist.
  19   */
  20  define( 'PATERRORMANAGER_ERROR_CALLBACK_NOT_CALLABLE', 2 );
  21  
  22  /**
  23   * error definition: illegal error handling mode.
  24   */
  25  define( 'PATERRORMANAGER_ERROR_ILLEGAL_MODE', 3 );
  26  
  27  
  28  /**
  29   * global definitions needed to keep track of things when calling the patErrorManager
  30   * static methods.
  31   */
  32  $GLOBALS['_pat_errorHandling']    =    array(
  33                                              E_NOTICE    => array( 'mode' => 'echo' ),
  34                                              E_WARNING    => array( 'mode' => 'echo' ),
  35                                              E_ERROR        => array( 'mode' => 'die' )
  36                                          );
  37  
  38  /**
  39   * available error levels
  40   * Stored in a variable to keep them flexible
  41   */
  42  $GLOBALS['_pat_errorLevels']    =    array(
  43                                              E_NOTICE    => 'Notice',
  44                                              E_WARNING    => 'Warning',
  45                                              E_ERROR        => 'Error'
  46                                          );
  47  /**
  48   * error class names
  49   * Stored in a variable allows to change during runtime
  50   */
  51  $GLOBALS['_pat_errorClass']    =    'patError';
  52  
  53  /**
  54   * ignore errors
  55   * Store error-codes that will be ignored forever
  56   */
  57  $GLOBALS['_pat_errorIgnores']    =    array();
  58  
  59  /**
  60   * expects errors
  61   * Store error-codes that will be ignored once
  62   */
  63  $GLOBALS['_pat_errorExpects']    =    array();
  64  
  65  
  66  /**
  67   * patErrorManager main error management class used by pat tools for the
  68   * application-internal error management. Creates patError objects for
  69   * any errors for precise error management.
  70   *
  71   * @static
  72   * @package    patError
  73   * @version    0.3
  74   * @author    gERD Schaufelberger <gerd@php-tools.net>
  75   * @author    Stephan Schmidt <schst@php-tools.net>
  76   * @license    LGPL
  77   * @link    http://www.php-tools.net
  78   * @todo    implement ignoreError() to ignore errrors with a certain code
  79   * @todo    implement expectError() to ignore an error with a certain code only once.
  80   */
  81  class patErrorManager
  82  {
  83      /**
  84      * method for checking whether the return value of a pat application method is a pat
  85      * error object.
  86      *
  87      * @static
  88      * @access    public
  89      * @param    mixed    &$object
  90      * @return    boolean $result    True if argument is a patError-object, false otherwise.
  91      */
  92      function isError( &$object )
  93      {
  94          if( !is_object( $object ) )
  95          {
  96              return false;
  97          }
  98  
  99  
 100  
 101          if( strtolower(get_class( $object )) != strtolower( $GLOBALS['_pat_errorClass'] ) && !is_subclass_of( $object, $GLOBALS['_pat_errorClass'] ) )
 102          {
 103              return false;
 104          }
 105  
 106          return  true;
 107      }
 108  
 109      /**
 110      * wrapper for the {@link raise()} method where you do not have to specify the
 111      * error level - a {@link patError} object with error level E_ERROR will be returned.
 112      *
 113      * @static
 114      * @access    public
 115      * @param    string    $code    The application-internal error code for this error
 116      * @param    string    $msg    The error message, which may also be shown the user if need be.
 117      * @param    mixed    $info    Optional: Additional error information (usually only developer-relevant information that the user should never see, like a database DSN).
 118      * @return    object    $error    The configured patError object
 119      * @see        raise()
 120      * @see        patError
 121      */
 122      function &raiseError( $code, $msg, $info = null )
 123      {
 124          return patErrorManager::raise( E_ERROR, $code, $msg, $info );
 125      }
 126  
 127      /**
 128      * wrapper for the {@link raise()} method where you do not have to specify the
 129      * error level - a {@link patError} object with error level E_WARNING will be returned.
 130      *
 131      * @static
 132      * @access    public
 133      * @param    string    $code    The application-internal error code for this error
 134      * @param    string    $msg    The error message, which may also be shown the user if need be.
 135      * @param    mixed    $info    Optional: Additional error information (usually only developer-relevant information that the user should never see, like a database DSN).
 136      * @return    object    $error    The configured patError object
 137      * @see        raise()
 138      * @see        patError
 139      */
 140      function &raiseWarning( $code, $msg, $info = null )
 141      {
 142          return patErrorManager::raise( E_WARNING, $code, $msg, $info );
 143      }
 144  
 145      /**
 146      * wrapper for the {@link raise()} method where you do not have to specify the
 147      * error level - a {@link patError} object with error level E_NOTICE will be returned.
 148      *
 149      * @static
 150      * @access    public
 151      * @param    string    $code    The application-internal error code for this error
 152      * @param    string    $msg    The error message, which may also be shown the user if need be.
 153      * @param    mixed    $info    Optional: Additional error information (usually only developer-relevant information that the user should never see, like a database DSN).
 154      * @return    object    $error    The configured patError object
 155      * @see        raise()
 156      * @see        patError
 157      */
 158      function &raiseNotice( $code, $msg, $info = null )
 159      {
 160          return patErrorManager::raise( E_NOTICE, $code, $msg, $info );
 161      }
 162  
 163      /**
 164      * creates a new patError object given the specified information.
 165      *
 166      * @access    public
 167      * @param    int        $level    The error level - use any of PHP's own error levels for this: E_ERROR, E_WARNING, E_NOTICE, E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE.
 168      * @param    string    $code    The application-internal error code for this error
 169      * @param    string    $msg    The error message, which may also be shown the user if need be.
 170      * @param    mixed    $info    Optional: Additional error information (usually only developer-relevant information that the user should never see, like a database DSN).
 171      * @return    mixed    $error    The configured patError object or false if this error should be ignored
 172      * @see        patError
 173      * @todo        implement 'simple' mode that returns just false (BC for patConfiguration)
 174      * @todo        either remove HTML tags and entities from output or test for enviroment!!! <b></b> in shell is ugly!
 175      */
 176      function &raise( $level, $code, $msg, $info = null )
 177      {
 178          // ignore this error?
 179          if( in_array( $code, $GLOBALS['_pat_errorIgnores'] ) )
 180          {
 181              return false;
 182          }
 183  
 184          // this error was expected
 185          if( !empty( $GLOBALS['_pat_errorExpects'] ) )
 186          {
 187              $expected =    array_pop( $GLOBALS['_pat_errorExpects'] );
 188              if( in_array( $code, $expected ) )
 189              {
 190                  return false;
 191              }
 192          }
 193  
 194          // need patError
 195          $class    =    $GLOBALS['_pat_errorClass'];
 196          if( !class_exists( $class ) )
 197          {
 198              include_once dirname( __FILE__ ) . '/'. $class .'.php';
 199          }
 200  
 201          // build error object
 202          $error            = new $class( $level, $code, $msg, $info );
 203  
 204          // see what to do with this kind of error
 205          $handling    =    patErrorManager::getErrorHandling( $level );
 206  
 207          $function    =    'handleError' . ucfirst( $handling['mode'] );
 208          if (is_callable( array( 'patErrorManager', $function ) )) {
 209              return patErrorManager::$function( $error, $handling );
 210          } else {
 211              // This is required to prevent a very unhelpful white-screen-of-death
 212              jexit(
 213                  'JError::raise -> Static method JError::' . $function . ' does not exist.' .
 214                  ' Contact a developer to debug' .
 215                  '<br /><strong>Error was</strong> ' .
 216                  '<br />' . $error->getMessage()
 217              );
 218          }
 219      }
 220  
 221      /**
 222      * register a new error level
 223      *
 224      * This allows you to add custom error levels to the built-in
 225      * - E_NOTICE
 226      * - E_WARNING
 227      * - E_NOTICE
 228      *
 229      * You may use this level in subsequent calls to raise().
 230      * Error handling will be set to 'ignore' for the new level, you
 231      * may change it by using setErrorHandling().
 232      *
 233      * You could be using PHP's predefined constants for error levels
 234      * or any other integer value.
 235      *
 236      * @access    public
 237      * @param    integer    error level
 238      * @param    string    human-readable name
 239      * @return    boolean    true on success; false if the level already has been registered
 240      * @see        raise(), setErrorHandling()
 241      * @link        http://www.php.net/manual/en/function.error-reporting.php
 242      */
 243  	function registerErrorLevel( $level, $name )
 244      {
 245          if( isset( $GLOBALS['_pat_errorLevels'][$level] ) )
 246          {
 247              return false;
 248          }
 249          $GLOBALS['_pat_errorLevels'][$level]    =    $name;
 250          patErrorManager::setErrorHandling( $level, 'ignore' );
 251          return    true;
 252      }
 253  
 254      /**
 255      * sets the way the patErrorManager will handle teh different error levels. Use this
 256      * if you want to override the default settings.
 257      *
 258      * Error handling modes:
 259      * - ignore
 260      * - trigger
 261      * - verbose
 262      * - echo
 263      * - callback
 264      * - die
 265      *
 266      * You may also set the error handling for several modes at once using PHP's bit operations.
 267      * Examples:
 268      * - E_ALL = Set the handling for all levels
 269      * - E_ERROR | E_WARNING = Set the handling for errors and warnings
 270      * - E_ALL ^ E_ERROR = Set the handling for all levels except errors
 271      *
 272      * @static
 273      * @access    public
 274      * @param    int        $level        The error level for which to set the error handling
 275      * @param    string    $mode        The mode to use for the error handling.
 276      * @param    mixed    $options    Optional: Any options needed for the given mode.
 277      * @return    mixed    $result        True on success, or a patError object if failed.
 278      * @see        getErrorHandling()
 279      */
 280      function setErrorHandling( $level, $mode, $options = null )
 281      {
 282          $levels    =    $GLOBALS['_pat_errorLevels'];
 283  
 284          $function    =    'handleError' . ucfirst( $mode );
 285          if( !is_callable( array( 'patErrorManager', $function ) ) )
 286          {
 287              return patErrorManager::raiseError( E_ERROR,
 288                                                  'patErrorManager:' . PATERRORMANAGER_ERROR_ILLEGAL_MODE,
 289                                                  'Error Handling mode is not knwon',
 290                                                  'Mode: ' .  $mode . ' is not implemented.'
 291                                                  );
 292          }
 293  
 294          foreach( $levels as $eLevel => $eTitle )
 295          {
 296              if( ( $level & $eLevel ) != $eLevel )
 297              {
 298                  continue;
 299              }
 300  
 301              // set callback options
 302              if( $mode == 'callback' )
 303              {
 304                  if( !is_array( $options ) )
 305                  {
 306                      return patErrorManager::raiseError( E_ERROR,
 307                                                          'patErrorManager:' . PATERRORMANAGER_ERROR_ILLEGAL_OPTIONS,
 308                                                          'Options for callback not valid'
 309                                                          );
 310                  }
 311  
 312                  if( !is_callable( $options ) )
 313                  {
 314                      $tmp    =    array( 'GLOBAL' );
 315                      if( is_array( $options ) )
 316                      {
 317                          $tmp[0]    =    $options[0];
 318                          $tmp[1]    =    $options[1];
 319                      }
 320                      else
 321                      {
 322                          $tmp[1]    =    $options;
 323                      }
 324  
 325                      return patErrorManager::raiseError(    E_ERROR,
 326                                                          'patErrorManager:' . PATERRORMANAGER_ERROR_CALLBACK_NOT_CALLABLE,
 327                                                          'Function is not callable',
 328                                                          'Function:' . $tmp[1]  . ' scope ' . $tmp[0] . '.'
 329                                                          );
 330                  }
 331              }
 332  
 333  
 334              // save settings
 335              $GLOBALS['_pat_errorHandling'][$eLevel]    =    array( 'mode' => $mode );
 336              if( $options    != null )
 337              {
 338                  $GLOBALS['_pat_errorHandling'][$eLevel]['options']    =    $options;
 339              }
 340          }
 341  
 342          return  true;
 343      }
 344  
 345      /**
 346      * retrieves the current error handling settings for the specified error level.
 347      *
 348      * @access    public
 349      * @param    int        $level        The error level to retrieve. This can be any of PHP's own error levels, e.g. E_ALL, E_NOTICE...
 350      * @return    array    $handling    All error handling details
 351      */
 352      function getErrorHandling( $level )
 353      {
 354          return $GLOBALS['_pat_errorHandling'][$level];
 355      }
 356  
 357      /**
 358      * translate an error level
 359      *
 360      * returns the human-readable name for an error level,
 361      * e.g. E_ERROR will be translated to 'Error'.
 362      *
 363      * @access    public
 364      * @param    integer        error level
 365      * @return    string        human-readable representation
 366      */
 367  	function translateErrorLevel( $level )
 368      {
 369          if( isset( $GLOBALS['_pat_errorLevels'][$level] ) )
 370          {
 371              return    $GLOBALS['_pat_errorLevels'][$level];
 372          }
 373          return    'Unknown error level';
 374      }
 375  
 376      /**
 377      * setErrorClass
 378      *
 379      * In order to autoload this class, the filename containing that class must be
 380      * named like the class itself; with an appending ".php". Although the file must be stored
 381      * in the same directory as patErrorManager.php (this file)
 382      *
 383      * @access public
 384      * @param string $name classname
 385      * @return boolean $result true on success
 386      */
 387      function setErrorClass( $name )
 388      {
 389          // include old error-class
 390          if( $name !== $GLOBALS['_pat_errorClass'] && !class_exists( $GLOBALS['_pat_errorClass'] ) )
 391          {
 392              include_once dirname( __FILE__ ) . '/' . $GLOBALS['_pat_errorClass'] . '.php';
 393          }
 394  
 395          $GLOBALS['_pat_errorClass']    =    $name;
 396          return true;
 397      }
 398  
 399      /**
 400      * add error codes to be ingored
 401      *
 402      * @static
 403      * @access public
 404      * @param mixed $codes either an array of error code or a single code that will be ignored in future
 405      * @return boolean $result true on success
 406      */
 407      function addIgnore( $codes )
 408      {
 409          if( !is_array( $codes ) )
 410          {
 411              $codes    =    array( $codes );
 412          }
 413  
 414          $codes                            =    array_merge( $GLOBALS['_pat_errorIgnores'], $codes );
 415          $GLOBALS['_pat_errorIgnores']    =    array_unique( $codes );
 416  
 417          return true;
 418      }
 419  
 420      /**
 421      * removeIgnore
 422      *
 423      *
 424      * @static
 425      * @access public
 426      * @return boolean $result true on success
 427      */
 428      function removeIgnore( $codes )
 429      {
 430          if( !is_array( $codes ) )
 431          {
 432              $codes    =    array( $codes );
 433          }
 434  
 435          foreach( $codes as $code )
 436          {
 437              $index    =    array_search( $code, $GLOBALS['_pat_errorIgnores'] );
 438              if( $index === false )
 439              {
 440                  continue;
 441              }
 442  
 443              unset( $GLOBALS['_pat_errorIgnores'][$index] );
 444          }
 445  
 446          // reorder the codes
 447          $GLOBALS['_pat_errorIgnores']    =    array_values( $GLOBALS['_pat_errorIgnores'] );
 448  
 449          return true;
 450      }
 451  
 452      /**
 453      * recieve all registerd error codes that will be ignored
 454      *
 455      * @static
 456      * @access public
 457      * @return array $codes list of error codes
 458      */
 459      function getIgnore()
 460      {
 461          return $GLOBALS['_pat_errorIgnores'];
 462      }
 463  
 464      /**
 465      * empty list of errors to be ignored
 466      *
 467      * @static
 468      * @access public
 469      * @return boolean $result true on success
 470      */
 471      function clearIgnore()
 472      {
 473          $GLOBALS['_pat_errorIgnores']    =    array();
 474          return true;
 475      }
 476  
 477      /**
 478      * add expected errors to stack
 479      *
 480      * @static
 481      * @access public
 482      * @param mixed $codes either an array of error code or a single code that will be ignored in future
 483      * @return boolean $result true on success
 484      */
 485      function pushExpect( $codes )
 486      {
 487          if( !is_array( $codes ) )
 488          {
 489              $codes    =    array( $codes );
 490          }
 491  
 492          array_push( $GLOBALS['_pat_errorExpects'], $codes );
 493  
 494          return true;
 495      }
 496  
 497      /**
 498      * remove top of error-codes from stack
 499      *
 500      * @static
 501      * @access public
 502      * @return boolean $result true on success
 503      */
 504      function popExpect()
 505      {
 506          if( empty( $GLOBALS['_pat_errorExpects'] ) )
 507          {
 508              return false;
 509          }
 510  
 511          array_pop( $GLOBALS['_pat_errorExpects'] );
 512          return true;
 513      }
 514  
 515      /**
 516      * recieve all registerd error codes that will be ignored
 517      *
 518      * @static
 519      * @access public
 520      * @return array $codes list of error codes
 521      */
 522      function getExpect()
 523      {
 524          return $GLOBALS['_pat_errorExpects'];
 525      }
 526  
 527      /**
 528      * empty list of errors to be ignored
 529      *
 530      * @static
 531      * @access public
 532      * @return boolean $result true on success
 533      */
 534      function clearExpect()
 535      {
 536          $GLOBALS['_pat_errorExpects']    =    array();
 537          return true;
 538      }
 539  
 540      /**
 541      * handleError: Ignore
 542      * Does nothing
 543      *
 544      * @access private
 545      * @param object $error patError-Object
 546      * @param array $options options for handler
 547      * @return object $error error-object
 548      * @see raise()
 549      */
 550      function &handleErrorIgnore( &$error, $options )
 551      {
 552          return $error;
 553      }
 554  
 555      /**
 556      * handleError: Echo
 557      * display error message
 558      *
 559      * @access private
 560      * @param object $error patError-Object
 561      * @param array $options options for handler
 562      * @return object $error error-object
 563      * @see raise()
 564      */
 565      function &handleErrorEcho( &$error, $options )
 566      {
 567          $level_human    =    patErrorManager::translateErrorLevel( $error->getLevel() );
 568  
 569          if( isset( $_SERVER['HTTP_HOST'] ) )
 570          {
 571              // output as html
 572              echo "<br /><b>pat-$level_human</b>: " . $error->getMessage() . "<br />\n";
 573          }
 574          else
 575          {
 576              // output as simple text
 577              if( defined( 'STDERR' ) )
 578              {
 579                  fwrite( STDERR, "pat-$level_human: " . $error->getMessage() . "\n" );
 580              }
 581              else
 582              {
 583                  echo "pat-$level_human: " . $error->getMessage() . "\n";
 584              }
 585          }
 586          return $error;
 587      }
 588  
 589      /**
 590      * handleError: Verbose
 591      * display verbose output for developing purpose
 592      *
 593      * @access private
 594      * @param object $error patError-Object
 595      * @param array $options options for handler
 596      * @return object $error error-object
 597      * @see raise()
 598      */
 599      function &handleErrorVerbose( &$error, $options )
 600      {
 601          $level_human    =    patErrorManager::translateErrorLevel( $error->getLevel() );
 602          $info            =    $error->getInfo();
 603  
 604          if( isset( $_SERVER['HTTP_HOST'] ) )
 605          {
 606              // output as html
 607              echo "<br /><b>pat-$level_human</b>: " . $error->getMessage() . "<br />\n";
 608              if( $info != null )
 609              {
 610                  echo "&nbsp;&nbsp;&nbsp;" . $error->getInfo() . "<br />\n";
 611              }
 612              echo $error->getBacktrace( true );
 613          }
 614          else
 615          {
 616              // output as simple text
 617              echo "pat-$level_human: " . $error->getMessage() . "\n";
 618              if( $info != null )
 619              {
 620                  echo "    " . $error->getInfo() . "\n";
 621              }
 622  
 623          }
 624          return $error;
 625      }
 626  
 627      /**
 628      * handleError: die
 629      * display error-message and die
 630      *
 631      * @access private
 632      * @param object $error patError-Object
 633      * @param array $options options for handler
 634      * @return object $error error-object
 635      * @see raise()
 636      */
 637      function &handleErrorDie( &$error, $options )
 638      {
 639          $level_human    =    patErrorManager::translateErrorLevel( $error->getLevel() );
 640  
 641          if( isset( $_SERVER['HTTP_HOST'] ) )
 642          {
 643              // output as html
 644              jexit( "<br /><b>pat-$level_human</b> " . $error->getMessage() . "<br />\n" );
 645          }
 646          else
 647          {
 648              // output as simple text
 649              if( defined( 'STDERR' ) )
 650              {
 651                  fwrite( STDERR, "pat-$level_human " . $error->getMessage() . "\n" );
 652              }
 653              else
 654              {
 655                  jexit( "pat-$level_human " . $error->getMessage() . "\n" );
 656              }
 657          }
 658          return $error;
 659      }
 660  
 661      /**
 662      * handleError: trigger
 663      * trigger php-error
 664      *
 665      * @access private
 666      * @param object $error patError-Object
 667      * @param array $options options for handler
 668      * @return object $error error-object
 669      * @see raise()
 670      */
 671      function &handleErrorTrigger( &$error, $options )
 672      {
 673          switch( $error->getLevel() )
 674          {
 675              case    E_NOTICE:
 676                  $level    =    E_USER_NOTICE;
 677                  break;
 678              case    E_WARNING:
 679                  $level    =    E_USER_WARNING;
 680                  break;
 681              case    E_NOTICE:
 682                  $level =    E_NOTICE;
 683                  break;
 684              default:
 685                  $level    =    E_USER_ERROR;
 686                  break;
 687          }
 688  
 689          trigger_error( $error->getMessage(), $level );
 690          return $error;
 691      }
 692  
 693      /**
 694      * handleError: callback
 695      * forward error to custom handler
 696      *
 697      * @access private
 698      * @param object $error patError-Object
 699      * @param array $options options for handler
 700      * @return object $error error-object
 701      * @see raise()
 702      */
 703      function &handleErrorCallback( &$error, $options )
 704      {
 705          $opt    = $options['options'];
 706          $result = &call_user_func( $opt, $error );
 707          return $result;
 708      }
 709  }
 710  ?>