nogo / fpErrorNotifierPlugin

A symfony plugin that add ability to catch all kind of exceptions\errors including fatal ones and send them as a mail.

#fpErrorNotifierPlugin

Overview

It catches all kinds of errors like: exceptions, fatal errors, notices, memory limit errors and so on. It is very useful for production servers. You will find out about any errors in a moment after it has happened and not when an angry customer calls you. The mail will contain a lot of useful information like description, stack trace, module\action, dump of _$SERVER and _$SESSION variables and so on.

Another good reason to use is that it was made as a set of components: message, driver, handler, decorator. These components are easy to changes or extend (in most cases just by modifing notify.yml config)

Requirements

• Symfony 1.1 - 1.4

Installation

Download:

Pear package

php symfony plugin:install fpErrorNotifierPlugin

Git dev:

git clone git://github.com/makasim/fpErrorNotifierPlugin.git

Git tag:

git clone git://github.com/makasim/fpErrorNotifierPlugin.git 
cd fpErrorNotifierPlugin
git tag
# check out the latest tag - 1.0.0 for this example
git checkout 1.0.0

Enable it

class ProjectConfiguration extends sfProjectConfiguration
{
  public function setup()
  {
    $this->enablePlugins('fpErrorNotifierPlugin');
  }
}

Getting Started

The general way of useing the plugin is to send emails about each error has happend on the server (including exceptions, notice, fatal and so on). Let's look at this example to khow how to do it with this plugin.

First we need to install the plugin. It was described earlier and it is a common symfony plugin installation Second we have to create notify.yml in any of the project config dir (I will store it in SF_ROOT_DIR/config/notify.yml) with a next content:

notify.yml

all:
  driver:
    class:                  fpErrorNotifierDriverMailNative
    options:
      to:                   '[e-mail],[e-mail],[e-mail]'
      from:                 '[e-mail]'

That's it. Now we have all errors and exceptions caught and sent to the development team members.

Features

The notify.yml config

After you setup the plugin it starts to work. By default it logs the last error into a file in the log dir. To change this behavior you need to create notify.yml in project or app config folder.

So let's say I copy notify.yml from plugin's config directory to SF_ROOT_DIR/config/notify.yml

notify.yml

prod:

all:
  handler:
    class:                   fpErrorNotifierHandler
    options:                 {}
        
  message:
    class:                   fpErrorNotifierMessage
    options:                 {}
    
  helper: 
    class:                   fpErrorNotifierMessageHelper
    options:                 {}
    
  decorator:
    class:                   fpErrorNotifierDecoratorHtml
    options:                 {}
  
  driver: 
    class:                   fpErrorNotifierDriverNull
    options:                 {}

As you can see we have some stuff like handler, message, helper, decorator and driver:

• Handler - it is a most valuable things. Because it cauth any errors and handle it
• Message - is just a data container.
• Helper - helps to fill the message with an information (like fill message from Exception instance).
• Decorator - it wrapps the message and know hot the message can be rendered.
• Driver - it is a object which knows where to send or store the message.

Handlers

There are two handlers which comes with the plugin:

• fpErrorNotifierHandler - base implementation
• fpErrorNotifierHandlerIgnore - extended version with some ignoring abilities.

fpErrorNotifierHandler does not take any options and can be configerd like this:

notify.yml

all:
  handler:
    class:                   fpErrorNotifierHandler
    options:                 {}

fpErrorNotifierHandlerIgnore:

notify.yml

all:
 handler:
   class:                   fpErrorNotifierHandlerIgnore
     options:
      ignore_@:              false
      ignore_errors:         [<?php echo E_ERROR ?>, <?php echo E_NOTICE ?>]
      ignore_exceptions:     [FooException]
      log_ignored:           true

Drivers

There are four drivers comes with the plugin:

• fpErrorNotifierDriverMailNative - use php's mail function to send an email.

notify.yml

all:
  driver:
    class:                  fpErrorNotifierDriverMailNative
    options:
      to:                   '[e-mail],[e-mail],[e-mail]'
      from:                 '[e-mail]'

• fpErrorNotifierDriverMailSymfony - use a mailer (It should be Swift) configured via factories.yml. It is taken from sfContext.

notify.yml

all:
  driver:
    class:                  fpErrorNotifierDriverMailSymfony
    options:
      to:                   '[e-mail],[e-mail],[e-mail]'
      from:                 '[e-mail]'

It is an example of SWIFT mailer configuration with gmail.com account

factories.yml

mailer:
  class: sfMailer
  param:
    logging:           %SF_LOGGING_ENABLED%
    charset:           %SF_CHARSET%
    delivery_strategy: realtime
    transport:
      class: Swift_SmtpTransport
      param:
        host:       smtp.gmail.com
        port:       587
        encryption: tls
        username:   [e-mail]
        password:   'password'

• fpErrorNotifierDriverFile - store the last error to the file (It can be helpfull for testing services in development process).

notify.yml

driver:
  class:             sfErrorNotifierDriverFile
    options:         
      path:          '%SF_LOG_DIR%/last-error.html'

• fpErrorNotifierDriverNull - just does do nothing

Decorators

You can render the message as simple text or html (set by default).

• fpErrorNotifierDecoratorHtml

notify.yml

all:
  decorator:
    class:                   fpErrorNotifierDecoratorHtml
    options:                 {}

• fpErrorNotifierDecoratorText

notify.yml

all:
  decorator:
    class:                   fpErrorNotifierDecoratorText
    options:                 {}

Customizing

Send a custom message

<?php

$message = fpErrorNotifier::getInstance()->decoratedMessage('A Custom message title');
$message->addSection('Detailed info', array('Detail 1' => 'Foo', 'Detail 2' => 'Bar'));

fpErrorNotifier::getInstance()->driver()->notify($message);

But this code creates a hard coded relation between your code and the plugin isn't it? It can be done this way but it is not a good idea. So how can we do it better? Below we are sending absolutly the same message using sfEventDispatcher:

<?php

$dispatcher = sfContext::getInstance()->getEventDispatcher();
$event = new sfEvent('A Custom message title', 'notify.send_message', array('Detail 1' => 'Foo', 'Detail 2' => 'Bar'));

$dispatcher->notify($event);

Add more info to the error message

<?php 

function addMoreErrorInfo(sfEvent $event)
{
  $message = $event->getSubject();
  $message->addSection('Detailed info', array('Detail 1' => 'Foo', 'Detail 2' => 'Bar'));
}

// notify.decorate_message for adding additional info to custom simple messages
fpErrorNotifier::getInstance()->dispather()->connect('notify.decorate_exception', 'addMoreErrorInfo');

// then when an error happend this event would be raised and additional info added.

Use custom driver

<?php 

$driver = new sfErrorNotifierDriverMailNative(array(
  'to' => '[e-mail]',
  'from,' => '[e-mail]'));

Run the plugin tests

It's used sfPhpunitPlugin as a testing framework.

So to run test you need this plugin first. Then you can run this command to execute the plugin tests.

./symfony phpunit --only-plugin=fpErrorNotifierPlugin

Feedback

I am very welcome for any comments suggestions, bug fixes, implementations and so on. You can create a ticket at my github repository or make a fork and do your changes.