<?php
/**
 * patErrorManager main error management class used by pat tools for the
 * application-internal error management. Creates patError objects for
 * any errors for precise error management.
 *
 * $Id: patErrorManager.php,v 1.16 2005/03/06 12:43:32 schst Exp $
 *
 * @package    patError
 */

/**
 * error definition: illegal options.
 */                                    
define( 'PATERRORMANAGER_ERROR_ILLEGAL_OPTIONS', 1 );

/**
 * error definition: callback function does not exist.
 */                                    
define( 'PATERRORMANAGER_ERROR_CALLBACK_NOT_CALLABLE', 2 );

/**
 * error definition: illegal error handling mode.
 */                                    
define( 'PATERRORMANAGER_ERROR_ILLEGAL_MODE', 3 );

 
/**
 * global definitions needed to keep track of things when calling the patErrorManager
 * static methods.
 */
$GLOBALS['_pat_errorHandling']    =    array( 
                                            E_NOTICE    => array( 'mode' => 'echo' ),
                                            E_WARNING    => array( 'mode' => 'echo' ),
                                            E_ERROR        => array( 'mode' => 'die' )
                                        );

/**
 * available error levels
 * Stored in a variable to keep them flexible
 */
$GLOBALS['_pat_errorLevels']    =    array(
                                            E_NOTICE    => 'Notice',
                                            E_WARNING    => 'Warning',
                                            E_ERROR        => 'Error'
                                        );
/**
 * error class names
 * Stored in a variable allows to change during runtime
 */
$GLOBALS['_pat_errorClass']    =    'patError';

/**
 * ignore errors
 * Store error-codes that will be ignored forever
 */
$GLOBALS['_pat_errorIgnores']    =    array();

/**
 * expects errors
 * Store error-codes that will be ignored once
 */
$GLOBALS['_pat_errorExpects']    =    array();

 
/**
 * patErrorManager main error management class used by pat tools for the
 * application-internal error management. Creates patError objects for
 * any errors for precise error management.
 *
 * @static
 * @package    patError
 * @version    0.3
 * @author    gERD Schaufelberger <gerd@php-tools.net>
 * @author    Stephan Schmidt <schst@php-tools.net>
 * @license    LGPL
 * @link    http://www.php-tools.net
 * @todo    implement ignoreError() to ignore errrors with a certain code
 * @todo    implement expectError() to ignore an error with a certain code only once.
 */
class patErrorManager
{
   /**
    * method for checking whether the return value of a pat application method is a pat
    * error object.
    *
    * @static
    * @access    public
    * @param    mixed    &$object
    * @return    boolean $result    True if argument is a patError-object, false otherwise.
    */
    function isError( &$object )
    {
        if( !is_object( $object ) )
        {
            return false;
        }

        if( strtolower( get_class( $object ) ) != strtolower( $GLOBALS['_pat_errorClass'] ) && !is_subclass_of( $object, $GLOBALS['_pat_errorClass'] ) )
        {
            return false;
        }
        
        return  true;
    }
    
   /**
    * wrapper for the {@link raise()} method where you do not have to specify the
    * error level - a {@link patError} object with error level E_ERROR will be returned.
    *
    * @static
    * @access    public
    * @param    string    $code    The application-internal error code for this error
    * @param    string    $msg    The error message, which may also be shown the user if need be.
    * @param    mixed    $info    Optional: Additional error information (usually only developer-relevant information that the user should never see, like a database DSN).
    * @return    object    $error    The configured patError object
    * @see        raise()
    * @see        patError
    */
    function &raiseError( $code, $msg, $info = null )
    {
        return patErrorManager::raise( E_ERROR, $code, $msg, $info );
    }
    
   /**
    * wrapper for the {@link raise()} method where you do not have to specify the
    * error level - a {@link patError} object with error level E_WARNING will be returned.
    *
    * @static
    * @access    public
    * @param    string    $code    The application-internal error code for this error
    * @param    string    $msg    The error message, which may also be shown the user if need be.
    * @param    mixed    $info    Optional: Additional error information (usually only developer-relevant information that the user should never see, like a database DSN).
    * @return    object    $error    The configured patError object
    * @see        raise()
    * @see        patError
    */
    function &raiseWarning( $code, $msg, $info = null )
    {
        return patErrorManager::raise( E_WARNING, $code, $msg, $info );
    }
    
   /**
    * wrapper for the {@link raise()} method where you do not have to specify the
    * error level - a {@link patError} object with error level E_NOTICE will be returned.
    *
    * @static
    * @access    public
    * @param    string    $code    The application-internal error code for this error
    * @param    string    $msg    The error message, which may also be shown the user if need be.
    * @param    mixed    $info    Optional: Additional error information (usually only developer-relevant information that the user should never see, like a database DSN).
    * @return    object    $error    The configured patError object
    * @see        raise()
    * @see        patError
    */
    function &raiseNotice( $code, $msg, $info = null )
    {
        return patErrorManager::raise( E_NOTICE, $code, $msg, $info );
    }
    
   /**
    * creates a new patError object given the specified information.
    *
    * @access    public
    * @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.
    * @param    string    $code    The application-internal error code for this error
    * @param    string    $msg    The error message, which may also be shown the user if need be.
    * @param    mixed    $info    Optional: Additional error information (usually only developer-relevant information that the user should never see, like a database DSN).
    * @return    mixed    $error    The configured patError object or false if this error should be ignored
    * @see        patError
    * @todo        implement 'simple' mode that returns just false (BC for patConfiguration)
    * @todo        either remove HTML tags and entities from output or test for enviroment!!! <b></b> in shell is ugly!
    */
    function &raise( $level, $code, $msg, $info = null )
    {
        // ignore this error?
        if( in_array( $code, $GLOBALS['_pat_errorIgnores'] ) )
        {
            return false;
        }

        // need patError
        $class    =    $GLOBALS['_pat_errorClass'];
        if( !class_exists( $class ) )
        {
            include_once dirname( __FILE__ ) . '/'. $class .'.php';
        }
        
        // build error object
        $error            =&    new    $class( $level, $code, $msg, $info );

        // this error was expected
        if( !empty( $GLOBALS['_pat_errorExpects'] ) )
        {
            $expected =    array_pop( $GLOBALS['_pat_errorExpects'] );
            array_push( $GLOBALS['_pat_errorExpects'], $expected );
            if( in_array( $code, $expected ) )
            {
                return $error;
            }
        }
        
        // see what to do with this kind of error        
        $handling    =    patErrorManager::getErrorHandling( $level );
        
        $function    =    'handleError' . ucfirst( $handling['mode'] );
        return patErrorManager::$function( $error, $handling );
    }

   /**
    * register a new error level
    *
    * This allows you to add custom error levels to the built-in
    * - E_NOTICE
    * - E_WARNING
    * - E_NOTICE
    *
    * You may use this level in subsequent calls to raise().
    * Error handling will be set to 'ignore' for the new level, you
    * may change it by using setErrorHandling().
    *
    * You could be using PHP's predefined constants for error levels
    * or any other integer value.
    *
    * @access    public
    * @param    integer    error level
    * @param    string    human-readable name
    * @return    boolean    true on success; false if the level already has been registered
    * @see        raise(), setErrorHandling()
    * @link        http://www.php.net/manual/en/function.error-reporting.php
    */
    function registerErrorLevel( $level, $name )
    {
        if( isset( $GLOBALS['_pat_errorLevels'][$level] ) )
        {
            return false;
        }
        $GLOBALS['_pat_errorLevels'][$level]    =    $name;
        patErrorManager::setErrorHandling( $level, 'ignore' );
        return    true;
    }
    
   /**
    * sets the way the patErrorManager will handle teh different error levels. Use this
    * if you want to override the default settings.
    *
    * Error handling modes:
    * - ignore
    * - trigger
    * - verbose
    * - echo
    * - callback
    * - die
    *
    * You may also set the error handling for several modes at once using PHP's bit operations.
    * Examples:
    * - E_ALL = Set the handling for all levels
    * - E_ERROR | E_WARNING = Set the handling for errors and warnings
    * - E_ALL ^ E_ERROR = Set the handling for all levels except errors
    *
    * @static
    * @access    public
    * @param    int        $level        The error level for which to set the error handling
    * @param    string    $mode        The mode to use for the error handling.
    * @param    mixed    $options    Optional: Any options needed for the given mode.
    * @return    mixed    $result        True on success, or a patError object if failed.
    * @see        getErrorHandling()
    */
    function setErrorHandling( $level, $mode, $options = null )
    {
        $levels    =    $GLOBALS['_pat_errorLevels'];

        $function    =    'handleError' . ucfirst( $mode );
        if( !is_callable( array( 'patErrorManager', $function ) ) )
        {
            return patErrorManager::raiseError( E_ERROR, 
                                                'patErrorManager:' . PATERRORMANAGER_ERROR_ILLEGAL_MODE, 
                                                'Error Handling mode is not knwon',
                                                'Mode: ' .  $mode . ' is not implemented.'
                                                );
        }
        
        foreach( $levels as $eLevel => $eTitle )
        {
            if( ( $level & $eLevel ) != $eLevel )
            {
                continue;
            }

            // set callback options
            if( $mode == 'callback' )
            {
                if( !is_array( $options ) )
                {
                    return patErrorManager::raiseError( E_ERROR, 
                                                        'patErrorManager:' . PATERRORMANAGER_ERROR_ILLEGAL_OPTIONS, 
                                                        'Options for callback not valid' 
                                                        );
                }
                
                if( !is_callable( $options ) )
                {
                    $tmp    =    array( 'GLOBAL' );
                    if( is_array( $options ) )
                    {
                        $tmp[0]    =    $options[0];
                        $tmp[1]    =    $options[1];
                    }
                    else
                    {
                        $tmp[1]    =    $options;
                    }
                    
                    return patErrorManager::raiseError(    E_ERROR, 
                                                        'patErrorManager:' . PATERRORMANAGER_ERROR_CALLBACK_NOT_CALLABLE, 
                                                        'Function is not callable', 
                                                        'Function:' . $tmp[1]  . ' scope ' . $tmp[0] . '.' 
                                                        );
                }
            }
                
        
            // save settings
            $GLOBALS['_pat_errorHandling'][$eLevel]    =    array( 'mode' => $mode );
            if( $options    != null )
            {
                $GLOBALS['_pat_errorHandling'][$eLevel]['options']    =    $options;
            }
        }
            
        return  true;
    }

   /**
    * retrieves the current error handling settings for the specified error level.
    *
    * @access    public
    * @param    int        $level        The error level to retrieve. This can be any of PHP's own error levels, e.g. E_ALL, E_NOTICE...
    * @return    array    $handling    All error handling details
    */
    function getErrorHandling( $level )
    {
        return $GLOBALS['_pat_errorHandling'][$level];
    }

   /**
    * translate an error level
    *
    * returns the human-readable name for an error level,
    * e.g. E_ERROR will be translated to 'Error'.
    *
    * @access    public
    * @param    integer        error level
    * @return    string        human-readable representation
    */
    function translateErrorLevel( $level )
    {
        if( isset( $GLOBALS['_pat_errorLevels'][$level] ) )
        {
            return    $GLOBALS['_pat_errorLevels'][$level];
        }
        return    'Unknown error level';
    }
    
   /**
    * setErrorClass
    *
    * In order to autoload this class, the filename containing that class must be
    * named like the class itself; with an appending ".php". Although the file must be stored
    * in the same directory as patErrorManager.php (this file)
    *
    * @access public
    * @param string $name classname
    * @return boolean $result true on success
    */
    function setErrorClass( $name )
    {
        // include old error-class
        if( $name !== $GLOBALS['_pat_errorClass'] && !class_exists( $GLOBALS['_pat_errorClass'] ) )
        {
            include_once dirname( __FILE__ ) . '/' . $GLOBALS['_pat_errorClass'] . '.php';
        }
    
        $GLOBALS['_pat_errorClass']    =    $name;
        return true;
    }

   /**
    * add error codes to be ingored
    *
    * @static
    * @access public
    * @param mixed $codes either an array of error code or a single code that will be ignored in future
    * @return boolean $result true on success
    */
    function addIgnore( $codes )
    {
        if( !is_array( $codes ) )
        {
            $codes    =    array( $codes );
        }
    
        $codes                            =    array_merge( $GLOBALS['_pat_errorIgnores'], $codes );
        $GLOBALS['_pat_errorIgnores']    =    array_unique( $codes );

        return true;
    }
    
   /**
    * removeIgnore
    *
    *
    * @static
    * @access public
    * @return boolean $result true on success
    */
    function removeIgnore( $codes )
    {
        if( !is_array( $codes ) )
        {
            $codes    =    array( $codes );
        }
        
        foreach( $codes as $code )
        {
            $index    =    array_search( $code, $GLOBALS['_pat_errorIgnores'] );
            if( $index === false )
            {
                continue;
            }
            
            unset( $GLOBALS['_pat_errorIgnores'][$index] );
        }

        // reorder the codes        
        $GLOBALS['_pat_errorIgnores']    =    array_values( $GLOBALS['_pat_errorIgnores'] );
        
        return true;
    }
    
   /**
    * recieve all registerd error codes that will be ignored
    *
    * @static
    * @access public
    * @return array $codes list of error codes
    */
    function getIgnore()
    {
        return $GLOBALS['_pat_errorIgnores'];
    }

   /**
    * empty list of errors to be ignored
    *
    * @static
    * @access public
    * @return boolean $result true on success
    */
    function clearIgnore()
    {
        $GLOBALS['_pat_errorIgnores']    =    array();
        return true;
    }
    
   /**
    * add expected errors to stack
    *
    * @static
    * @access public
    * @param mixed $codes either an array of error code or a single code that will be ignored in future
    * @return boolean $result true on success
    */
    function pushExpect( $codes )
    {
        if( !is_array( $codes ) )
        {
            $codes    =    array( $codes );
        }
        
        array_push( $GLOBALS['_pat_errorExpects'], $codes );
        
        return true;
    }

   /**
    * remove top of error-codes from stack
    *
    * @static
    * @access public
    * @return boolean $result true on success
    */
    function popExpect()
    {
        if( empty( $GLOBALS['_pat_errorExpects'] ) )
        {
            return false;
        }
        
        array_pop( $GLOBALS['_pat_errorExpects'] );
        return true;
    }

   /**
    * recieve all registerd error codes that will be ignored
    *
    * @static
    * @access public
    * @return array $codes list of error codes
    */
    function getExpect()
    {
        return $GLOBALS['_pat_errorExpects'];
    }

   /**
    * empty list of errors to be ignored
    *
    * @static
    * @access public
    * @return boolean $result true on success
    */
    function clearExpect()
    {
        $GLOBALS['_pat_errorExpects']    =    array();
        return true;
    }
    
   /**
    * handleError: Ignore
    * Does nothing
    *
    * @access private
    * @param object $error patError-Object
    * @param array $options options for handler
    * @return object $error error-object
    * @see raise()
    */
    function &handleErrorIgnore( &$error, $options )
    {
        return $error;
    }
    
   /**
    * handleError: Echo
    * display error message
    *
    * @access private
    * @param object $error patError-Object
    * @param array $options options for handler
    * @return object $error error-object
    * @see raise()
    */
    function &handleErrorEcho( &$error, $options )
    {
        $level_human    =    patErrorManager::translateErrorLevel( $error->getLevel() );
    
        if( isset( $_SERVER['HTTP_HOST'] ) )
        {
            // output as html
            echo "<br /><b>pat-$level_human</b>: " . $error->getMessage() . "<br />\n";
        }
        else
        {
            // output as simple text
            if( defined( 'STDERR' ) )
            {
                fwrite( STDERR, "pat-$level_human: " . $error->getMessage() . "\n" );
            }
            else
            {
                echo "pat-$level_human: " . $error->getMessage() . "\n";
            }
        }
        return $error;
    }
    
   /**
    * handleError: Verbose
    * display verbose output for developing purpose
    *
    * @access private
    * @param object $error patError-Object
    * @param array $options options for handler
    * @return object $error error-object
    * @see raise()
    */
    function &handleErrorVerbose( &$error, $options )
    {
        $level_human    =    patErrorManager::translateErrorLevel( $error->getLevel() );
        $info            =    $error->getInfo();
    
        if( isset( $_SERVER['HTTP_HOST'] ) )
        {
            // output as html
            echo "<br /><b>pat-$level_human</b>: " . $error->getMessage() . "<br />\n";
            if( $info != null )
            {
                echo "&nbsp;&nbsp;&nbsp;" . $error->getInfo() . "<br />\n";
            }
        }
        else
        {
            // output as simple text
            echo "pat-$level_human: " . $error->getMessage() . "\n";
            if( $info != null )
            {
                echo "    " . $error->getInfo() . "\n";
            }
        }
        return $error;
    }
    
   /**
    * handleError: die
    * display error-message and die
    *
    * @access private
    * @param object $error patError-Object
    * @param array $options options for handler
    * @return object $error error-object
    * @see raise()
    */
    function &handleErrorDie( &$error, $options )
    {
        $level_human    =    patErrorManager::translateErrorLevel( $error->getLevel() );
    
        if( isset( $_SERVER['HTTP_HOST'] ) )
        {
            // output as html
            die( "<br /><b>pat-$level_human</b> " . $error->getMessage() . "<br />\n" );
        }
        else
        {
            // output as simple text
            if( defined( 'STDERR' ) )
            {
                fwrite( STDERR, "pat-$level_human " . $error->getMessage() . "\n" );
            }
            else
            {
                die( "pat-$level_human " . $error->getMessage() . "\n" );
            }
        }
        return $error;
    }
    
   /**
    * handleError: trigger
    * trigger php-error
    *
    * @access private
    * @param object $error patError-Object
    * @param array $options options for handler
    * @return object $error error-object
    * @see raise()
    */
    function &handleErrorTrigger( &$error, $options )
    {
        switch( $error->getLevel() )
        {
            case    E_NOTICE:
                $level    =    E_USER_NOTICE;
                break;
            case    E_WARNING:
                $level    =    E_USER_WARNING;
                break;
            case    E_NOTICE:
                $level =    E_NOTICE;
                break;
            default:
                $level    =    E_USER_ERROR;
                break;
        }
    
        trigger_error( $error->getMessage(), $level );
        return $error;
    }
    
   /**
    * handleError: callback
    * forward error to custom handler
    *
    * @access private
    * @param object $error patError-Object
    * @param array $options options for handler
    * @return object $error error-object
    * @see raise()
    */
    function &handleErrorCallback( &$error, $options )
    {
        $opt    =    $options['options'];
        return call_user_func( $opt, $error );
    }
   /**
    * handleError: throw an exception
    *
    * @access private
    * @param object $error patError-Object
    * @param array $options options for handler
    * @return null
    * @throws Exception
    * @see raise()
    */
    function &handleErrorException(&$error, $options)
    {
        if (isset($options['options'])) {
            $exception = $options['options'];
        } else {
            $exception = 'Exception';
        }
        $code = 'throw new '.$exception.'("'.$error->getMessage().'");';
        eval($code);
    }
}
?>