28.9 Mapping for Exceptions

The mapping for exceptions is based on the inheritance hierarchy shown in Figure 28.1

Figure 28.1. Inheritance structure for Ice exceptions.

The ancestor of all exceptions is Exception, from which Ice_Exception is derived. Ice_LocalException and Ice_UserException are derived from Ice_Exception and form the base for all run-time and user exceptions.

Consider the following Slice definitions:

exception GenericError {
    string reason;
};
exception BadTimeVal extends GenericError {};
exception BadZoneName extends GenericError {};

These exception definitions map to the abbreviated PHP class definitions shown below:

class GenericError extends Ice_UserException
{
    public function __construct($reason='');
    public function ice_name();
    public function __toString();

    public $reason;
}

class BadTimeVal extends GenericError
{
    public function __construct($reason='');
    public function ice_name();
    public function __toString();
}

class BadZoneName extends GenericError
{
    public function __construct($reason='');
    public function ice_name();
    public function __toString();
}

Each Slice exception is mapped to a PHP class with the same name. The inherit­ance structure of the Slice exceptions is preserved for the generated classes, so BadTimeVal and BadZoneName inherit from GenericError.

Each exception member corresponds to an instance variable of the instance, which the constructor initializes to a default value appropriate for its type. You can also declare different default values for members of primitive and enumerated types, as discussed in Section 4.10.2.

Although BadTimeVal and BadZoneName do not declare data members, their constructors still accept a value for the inherited data member reason in order to pass it to the constructor of the base exception GenericError.

Each exception also defines the ice_name method to return the exception’s type name, as well as the __toString magic method to return a stringified representation of the exception and its members.

All user exceptions are derived from the base class Ice_UserException. This allows you to catch all user exceptions generically by installing a handler for Ice_UserException. Similarly, you can catch all Ice run-time exceptions with a handler for Ice_LocalException, and you can catch all Ice excep­tions with a handler for Ice_Exception.