Support Joomla!

Joomla! 1.5 Documentation

Packages

Package: patError

Developer Network License

The Joomla! Developer Network content is © copyright 2006 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution- NonCommercial- ShareAlike 2.5
Source code for file /pattemplate/patErrorManager.php

Documentation is available at patErrorManager.php

  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 47 2005-09-15 02:55:27Z rhuk $
  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 <[email protected]>
  75.  * @author    Stephan Schmidt <[email protected]>
  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.             die(
  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.             die( "<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.                 die( "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. ?>
Documentation generated on Mon, 05 Mar 2007 21:13:46 +0000 by phpDocumentor 1.3.1