...

To be more flexible in filtering on logging exceptions but also on internal exception handling with try catch more exceptions are needed.

Examples

editor_Models_Import_FileParser_Sdlxliff_Exception extends editor_Models_Import_FileParser_Exception extends ZfExtended_ErrorCodeException

...

Since in FileParsing many errors can happen, a fine granulated exception structure is needed. In other code places this is not the case. At least one own Exception per Plugin / Package.

Internal Exception Structure

Each exception contains the mapping between the used event code and the related error message string. Since we are in an exception we can talk here about errors and not generally about events.

class editor_Models_Import_FileParser_Sdlxliff_Exception extends editor_Models_Import_FileParser_Exception {
    /**
     * @var string
     */
    protected $domain = 'editor.import.fileparser.sdlxliff';  //the domain (origin) string for hierarchical filtering
    
    static protected $localErrorCodes = [              //the error (event) codes used by that exception
        'E1000' => 'The file "{filename}" contains SDL comments which are currently not supported!',
        'E1001' => 'The opening tag "{tagName}" contains the tagId "{tagId}" which is no valid SDLXLIFF!',
        'E1003' => 'There are change Markers in the sdlxliff-file "{filename}"! Please clear them first and then try to check in the file again.',
		// [...] more mappings
    ];
}

Exception usage

if ($shitHappened && $itWasMyFault) {
	//There are change Markers in the sdlxliff-file which are not supported!        → there should be a brief comment to explain what is going wrong
    throw new editor_Models_Import_FileParser_Sdlxliff_Exception('E1003', [		 // → The exception receives just the EventCode and an array with extra data
        'task' => $this->task,
        'filename' => $this->_fileName,
    ]);
}

Exception Hierarchy and way to the frontend

Generic Exceptions

For the handling / catching of such exceptions see the section "Examples for specific Exceptions" below.

Exceptions with Semantic

This exceptions are used to answer errors to the API in REST full way, by transporting semantic as HTTP response code.

This Exceptions are intended not to be caught, since they transport information to the Caller.
But of course they can be caught if needed and handled differently.

Creation of exceptions static method createResponse

One fundamental problem for development in translate5 is that the default GUI language of translate5 is german, but most of the error messages are in english.
At some places the error message is intended to be used directly as user feedback, therefore the error message must be also in german at that place and the message must go through the internal translation mechanism before send to the user.

...

• the default constructor, all data must be given as usual.
• the static method getResponse which creates a new exception instance prefilled with the given error messages in the users GUI language

Examples for specific Exceptions

This exceptions are used in the case of errors in the application.

...

1. They are caught and the application deals with the error.
   No impact to the API result.
2. They are caught and the exceptions is translated into an exception with semantic
   This happens mostly on the Controller level. The main error message remains untranslated.
   In an additional Container multiple errors, with extra data and translated messages can be stored into the semantic exception.
3. Nothing is done and the exception bubbles to the caller:
   In direct API usage this should happen only if we really don't except that such exceptions happens.
   In worker context it is Ok to bubble such exceptions, since they are called via REST,
   but are then mostly running asynchronous without answering in a RESTfull way to the caller.
   This exceptions are transported untranslated into the GUI.