Added by Aleksey V. Zapparov, last edited by Aleksey V. Zapparov on Jun 21, 2008 (view change)

Labels

proposal, error, exception, zend_exception

Zend Framework: Zend_Exception Component Proposal

Proposed Component Name	Zend_Exception
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Exception
Proposers	Aleksey V. Zapparov
Revision	1.1 - 24 December 2007: First release of the proposal. 1.2 - 01 January 2008: Prepared for review. 1.2 - 21 June 2008: Ready for review. (wiki revision: 14)

1. Overview
2. References
3. Component Requirements, Constraints, and Acceptance Criteria
4. Dependencies on Other Framework Components
5. Theory of Operation
6. Milestones / Tasks
7. Class Index
8. Use Cases
9. Class Skeletons

1. Overview

Today Zend_Exception extends SPL's Exception class, which has not very much of info. Instead of this I propose to extend ErrorException, so Zend_Exception can be used as set_error_handler() handler.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

4. Dependencies on Other Framework Components

5. Theory of Operation

This proposal will allow to handle errors just like exceptions.
The purpose of this modification is to use Zend_Exception as an error to exception convertor.

6. Milestones / Tasks

7. Class Index

Zend_Exception

8. Use Cases

Zend_Exception::handleErrors();

try {
    if ($undefined_var) {
        echo 'You can\'t see me, cause $undefined_var was tested';
    }
} catch (Zend_Exception $e) {
    echo $e->getSeverity() . ': ' . $e->getMessage();
    // Output:
    // 8: Undefined variable: undefined_var
}

9. Class Skeletons

class Zend_Exception extends ErrorException  
{  
    protected $context;  
      
    function __construct($message, $code = null, $severity = E_ERROR, $filename = null,  
                         $lineno= null, array $context = array()) {  
        parent::__construct($message, $code, $severity, $filename, $lineno);  
        $this->context = $context;  
    }  
    
    /**
     * Return array that points to the active symbol table at the point the error
     * occurred. In other words, it will contain an array of every variable that
     * existed in the scope the error was triggered in.
     * 
     * @see Zend_Exception::errorHandler()
     * @return array
     */
    public function getContext()  
    {  
        return $this->context;  
    }  
    
    /**
     * Set Zend_Exception::errorHandler() as error handling function.
     *
     * @param integer $error_types (optional) used to mask the triggering of the Zend_Exception::errorHandler() function.
     * @return boolean
     */
    public static function setErrorHandler($error_types = E_ALL)
    {
        set_error_handler('Zend_Exception::errorHandler', (int) $error_types);  
        return true;  
    }
    
    /**
     * Alias for Zend_Exception::setErrorHandler()
     *
     * @see Zend_Exception::setErrorHandler()
     */
    public static function handleErrors($error_types = E_ALL)
    {
        return self::setErrorHandler($error_types);
    }
    
    /**
     * Error handling function. Used by Zend_Exception::setErrorHandler()
     *
     * @param integer $errno Level of the error raised
     * @param string $errstr Error message
     * @param string $errfile Filename that the error was raised in
     * @param integer $errline Line number the error was raised at
     * @param array $context Array that points to the active symbol table at the
     * point the error occurred
     * @throws Zend_Exception
     * @return void
     */
    public static function errorHandler($errno = E_ERROR, $errstr, $errfile,
                                        $errline, $context)
    {
        throw new Zend_Exception($errstr, 0, $errno, $errfile, $errline,
                                 $context);
    }
}

Comments (Hide Comments)

I would propose not to use create_function() but a static function Zend_Exception::handleError() which handles as the error handler. Except that this seems to be a great proposal.

Posted by Lars Strojny at Dec 26, 2007 18:54

I have didn't thounght about it. I agree that static function Zend_Exception::handleError() will be much better. I'll update skeleton according to your suggestion.

Posted by Aleksey V. Zapparov at Dec 27, 2007 07:22

I don't think it should be placed under Zend_Exception, but rather Zend_Error because an error handling system could be developed more flexible that way. Restricting it to Zend_Exception would not be ideal.

Posted by Geoffrey Tran at Jan 24, 2008 18:30

I'd like to see the ability to pass severity levels to the handleErrors method to allow more fine-grained control

E.g. handleErrors($severity = E_ALL)

So you could potentially pass Zend_Exception::handleErrors(E_ALL & ~E_NOTICE | E_WARNING);

I can't see the point in a Zend_Error component - if you wished to handle errors in a more specific way you'd no doubt be creating your own classes to deal with that?

Posted by Simon Mundy at Jan 24, 2008 18:49

Thank you for your notice about severity level.
I've just forgot about this optional argument of set_error_handler() function. I agree that this is necesary ability.
Added this ability, but called it $error_types (not $severity) just for "backward compability" with manual. I agree that $severity is maybe much better name for this param, but imho it's much better to give the same name as in PHP manual. I'm judging by myself - I always have PHP manual opened when I'm coding, so it take less time to understand what one thing (or wraper) is doing if arguments have the same names as in manual. If you think else, please let me know.

Posted by Aleksey V. Zapparov at Jan 26, 2008 07:57

I don't think that it has to be placed into independet class such as Zend_Error, just because Zend_Exception is the "core" of error handling in framework and this proposal is just makng Zend_Exception able to serve almost all errors happened in application.

But in other hand, I think there is a place for Zend_Error class, just in the role of decorator. So it can be used to handle exceptions in common way or something like this. But, as Simon noticed: "if you wished to handle errors in a more specific way you'd no doubt be creating your own classes to deal with that". So IMHO even if there will be Zend_Error it will be just a wraper to do tricks with exceptions and errors.

Posted by Aleksey V. Zapparov at Jan 26, 2008 08:04

Alexsey, is this proposal ready for community review?

,Wil

Posted by Wil Sinclair at May 13, 2008 23:41

Hello, Wil.

Yes. This proposal is ready for review.

Posted by Aleksey V. Zapparov at May 21, 2008 06:38

You should put this in to the 'Ready for Review' section and announce that it is ready for review on the general mailing list. Please see the new proposal process docs.

,Wil

Posted by Wil Sinclair at Jun 20, 2008 05:49

Note that in its current form this proposal is incompatible with the built-in translation functionality of Exception codes in exceptions - Matthew Ratzloff & Thomas Weidner.

Posted by Matthew Ratzloff at Jun 21, 2008 09:39

I disagree. I don't see any problems here. It's totally compatible, except only that it take severity level in constructor.

So for example, here's almost mixed (and probably buggy) version of your proposals (with my fixes which I have commented on proposal's page) and mine:

class Zend_Exception extends ErrorException
{
    /** @const integer Exception code range assigned to this component */
    const ASSIGNED_RANGE = 0x000000;

    /** @const integer Unknown exception */
    const UNKNOWN = 0x000000;

    /** @const integer The supplied exception code is not an integer */
    const CODE_NOT_INTEGER = 0x000001;

    /** @const integer The supplied exception code is out of range */
    const CODE_OUT_OF_RANGE = 0x000002;

    /** @const integer The given locale does not exist */
    const UNKNOWN_LOCALE = 0x000003;
    
    /**
     * The error caught by error_handler
     * @const integer
     * */
    const HANDLED_ERROR = 0x000004;

    /** @var string Locale */
    protected static $_locale = 'en';

    /** @var array|null Message parameters */ 
    protected $_messageParams = null;

    /** @var string Path in which to find message (i.e., translation) files */
    protected $_messagePath = 'Zend/Exception';

    /** @var string Message file format */
    protected $_messageFileFormat = 'gettext';

    /** @var string Message file extension */
    protected $_messageFileExt = 'mo';
    
    protected $context;

    /**
     * Constructor.
     *
     * Additional parameters may be passed in after the code for message translation purposes.
     * 
     * @param string $message Exception message
     * @param integer $code 3-byte hexadecimal exception code constant (e.g., Zend_Exception::EXAMPLE)
     */
    public function __construct($message, $code = 0, $severity = E_ERROR,
                                $filename = null, $lineno= null,
                                array $context = array())
    {
        if (!is_int($code)) {
            throw new Zend_Exception('Exception code must be an integer', self::CODE_NOT_INTEGER);
        }
        
        if (($code & self::ASSIGNED_RANGE) !== self::ASSIGNED_RANGE) {
            throw new Zend_Exception('Exception code is out of range', self::CODE_OUT_OF_RANGE);
        }

        parent::__construct($message, $code, $severity, $filename, $lineno);    
        $this->context = $context;  
        
        if (0) {
            // I don't know what is this, because I'm not using (and I hope I'll
            // never be using) Zend_Translator. So if you'll describe me what is
            // this in few words - I'll be thankful.
            if (func_num_args() > 2) {
                $this->_messageParams = array_splice(func_get_args(), 2);
            }
        }
    }
    
    /** 
     * Return array that points to the active symbol table at the point the error 
     * occurred. In other words, it will contain an array of every variable that 
     * existed in the scope the error was triggered in. 
     *  
     * @see Zend_Exception::errorHandler() 
     * @return array 
     */  
    public function getContext()    
    {    
        return $this->context;    
    }
    
    /** 
     * Set Zend_Exception::errorHandler() as error handling function. 
     * 
     * @param integer $error_types (optional) used to mask the triggering of the Zend_Exception::errorHandler() function. 
     * @return boolean 
     */  
    public static function setErrorHandler($error_types = E_ALL)  
    {  
        set_error_handler('Zend_Exception::errorHandler', (int) $error_types);    
        return true;    
    }  
      
    /** 
     * Alias for Zend_Exception::setErrorHandler() 
     * 
     * @see Zend_Exception::setErrorHandler() 
     */  
    public static function handleErrors($error_types = E_ALL)  
    {  
        return self::setErrorHandler($error_types);  
    }  
      
    /** 
     * Error handling function. Used by Zend_Exception::setErrorHandler() 
     * 
     * @param integer $errno Level of the error raised 
     * @param string $errstr Error message 
     * @param string $errfile Filename that the error was raised in 
     * @param integer $errline Line number the error was raised at 
     * @param array $context Array that points to the active symbol table at the 
     * point the error occurred 
     * @throws Zend_Exception 
     * @return void 
     */  
    public static function errorHandler($errno = E_ERROR, $errstr, $errfile,  
                                        $errline, $context)  
    {  
        throw new Zend_Exception($errstr, Zend_Exception::HANDLED_ERROR, $errno,
                                 $errfile, $errline, $context);  
    }
    
    /**
     * Sets a new standard locale for all exception objects.
     *
     * @param  string|Zend_Locale $locale Locale object or textual representation
     * @return string Locale (can differ from the given one)
     */
    public static function setLocale($locale = null)
    {
        require_once 'Zend/Locale.php';
        if ($locale instanceof Zend_Locale) {
            self::$_locale = $locale->toString();
        } else if (!($locale = Zend_Locale($locale, true))) {
            throw new Zend_Exception("Given locale '%1\$s' does not exist", self::UNKNOWN_LOCALE, $locale);
        } else {
            self::$_locale = $locale;
        }
        return self::_locale;
    }

    /**
     * Returns the standard locale for all exception objects.
     *
     * @return string Locale
     */
    public static function getLocale()
    {
        return self::_locale;
    }

    /**
     * Returns a translated exception message.
     *
     * @param string|Zend_Locale $locale Locale
     */
    public function getTranslatedMessage($locale = null)
    {
        $message = $this->getMessage();

        try {
            require_once 'Zend/Translate.php';
            require_once 'Zend/Locale.php';
            if (!($locale = Zend_Locale::isLocale($locale, true))) {
                $locale = 'en';
            }
            if ($locale instanceof Zend_Locale) {
                $locale = $locale->toString();
            }
            $messagePath = $this->_getMessageFilePath($locale);
            $translator  = new Zend_Translate($this->_messageFileFormat, $messagePath, $locale);
            return vprintf($translator->_($message, $this->_messageParams));
        } catch (Exception $e) {
            return vprintf($message, $this->_messageParams);
        }
    }

    /**
     * Returns an exception code given a valid method name.
     *
     * @param  string  $exceptionName Exception name (as a method call)
     * @return integer Exception code
     */
    public function __call($exceptionName, $value = null)
    {
        return ($this->_getConstant($exceptionName) === $this->code); 
    }

    /**
     * Returns the path to the message (i.e., translation) file.
     *
     * For example, given a component of "Zend_Example", this would return 
     * "Zend/Exception/en/Example.mo".
     *
     * @return string Message file path
     */
    protected function _getMessageFilePath($locale)
    {
        $componentName = implode('', array_splice(explode('_', get_class($this)), 1, 2));
        $filePath      = $this->_messagePath . DIRECTORY_SEPARATOR . $locale . DIRECTORY_SEPARATOR
                       . $componentName . '.' . $this->_messageFileExt;
        return $filePath;
    }

    /**
     * Retrieves a constant given an exception name.
     *
     * @param  string  $exceptionName Exception name
     * @return integer Exception code, or self::UNKNOWN if not found
     */
    protected function _getConstant($exceptionName)
    {
        $constantName = get_class($this) . '::' . $this->_formatAsConstant($exceptionName);
        if (!defined($constantName)) {
            return self::UNKNOWN;
        }
        return constant($constantName);
    }

    /**
     * Converts exceptionName to EXCEPTION_NAME.
     *
     * @param  string $exceptionName Unformatted exception name
     * @return string Formatted exception name
     */
    protected function _formatAsConstant($exceptionName)
    {
        $parts = preg_split('/([A-Z][a-z0-9]+)/', $exceptionName, -1, 
                            PREG_SPLIT_NO_EMPTY | PREG_SPLIT_DELIM_CAPTURE);
        return strtoupper(implode('_', $parts));
    }
}

Anyway, even with some of my fixes it still has bugs. And even with respect to that proposal is older then this, it has to be fixed. And maybe it's better to apply that proposal over this. Or return to talks about this proposal's incompatability with that proposal, when that proposal will be at least in incubator (so it will have no bugs).

When I'm saying about bugs I mean for example:

/**
     * Returns an exception code given a valid method name.
     *
     * @param  string  $exceptionName Exception name (as a method call)
     * @return integer Exception code
     */
    public function __call($exceptionName, $value = null)
    {
        return ($this->_getConstant($exceptionName) === $this->code); 
    }

In this method you are expecting to get an integer of Exception code as a return value, but you'll get boolean true if $this->_getConstant($exceptionName) equal to $this->code, and false otherwise.

Posted by Aleksey V. Zapparov at Jun 22, 2008 01:56 Updated by Aleksey V. Zapparov

Wouldn't it be problematic if someone is already using his own error_handler ?
You can only set one error_handler at once.

Wouldn't it be better to have exceptions and errors seperated ?

An exception can be handled by the application.
An error would need a completly different usage to be handled.

Also as already mentioned, the output can not be translated so all logs must be in english which does not take in account all non-native english people.

Posted by Thomas Weidner at Jun 22, 2008 00:08

This proposal not forces anybody to use this error_handler.
So if somebody have it's own error handler - he just have not to call Zend_Exception::setErrorHandler() method.

And yes if somebody want to have exceptions and errors separated - he can. But for me, for example, it's better to use everything as exceptions, so I can handle all of it in one place.

Posted by Aleksey V. Zapparov at Jun 22, 2008 02:01 Updated by Aleksey V. Zapparov

I was thinking about what Thomas Weidner said about "separating flies from cutlets" and idea stikes me.

The best way is to separate this proposal to Zend_Exception_Error

So one part (constructor for example) of this proposal will migrate to Zend_Exception_Error
and another part (static methods of setting error_handler) will stay in Zend_Exception.

This way will help to integrate this proposal into current structure easily and without any additional modifications (So integration with Exception codes in exceptions - Matthew Ratzloff & Thomas Weidner will become transparent). )

Posted by Aleksey V. Zapparov at Jun 22, 2008 04:07 Updated by Aleksey V. Zapparov

Shouldn't the default value for $error_types only contain errors (E_USER_ERROR and E_RECOVERABLE_ERROR)? Everything else is not really an error and shouldn't even happen in deployed code.

Posted by Nico Edtinger at Jun 22, 2008 13:28

Page Operations

Browse Space

Zend_Exception based on ErrorException - Aleksey V. Zapparov