# tncExceptionCatcherPlugin #

## Overview ##

This plugins allows to bypass the error500 of the framework so the developer can provide a custom module/action to show the error to the user.

## Installation ##

    cd my_project
    php symfony plugin-install http://plugins.symfony-project.com/tncExceptionCatcherPlugin
    php symfony cc
    
## Usage ##

By default when an unhandled exception arises symfony redirects the user to the error500.php page,
or if we are in a development environment the it shows the stack trace.

To avoid this and provide meaningful messages to the user we developed an exception catcher class. 

This class will forward to a module/action specified in the config files, as a way to keep the user inside the application, 
so we can use the symfony rendering system.

This class needs to be registered with the symfony **sfMixer** class to be hooked to the 'sfException:printStackTrace:printStackTrace' hook, 
because there is where symfony decides to display the stack trace or the error500.php page.

To do this we go to our controller file and add the following before the dispatch line:
    
    sfMixer::register('sfException:printStackTrace:printStackTrace', array('tncCatcher', 'forwardToErrorTemplate'));

This will cause that after an exception is thrown, it will call the method 

    tncCatcher::forwardToErrorTemplate

How does this method know to which module/action it should forward the user? 

We can set up this globally in the **app.yml** or in a specific per module/action way in the **module.yml** file.

Example <code>app.yml</code> file:

    all:
      exception:
        handler:
          module: signup
          action: signupError

Example **module.yml** file:

    all:
    # the action genericError will handle the exception for the whole module
      exception_action: genericError

    # we can override for an specific action the handler
      upload:
        exception_action: uploadError

If all this mechanism fails, let's say because we misstyped something inside the **app.yml** file, 
then the handler will look for an action called **defaultError** inside the **tncExceptionCatcher** module.

For the latter to work, we need to add the tncExceptionCatcher module to the enabled modules in the settings.yml

NOTE:

The idea is to handle not catched exceptions of the rendering proccess, if something fails before that proccess has
started, let's say when symfony is writing the logs, then it will redirect the user to the error500.php page.

Also the plugin is meant that ff something fails in the catching proccess then finally the user will also go to the error500.php page.