#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](http://www.symfony-project.org) 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: 'manager@example.com,teamleader@example.com,developer@example.com'
from: 'noreply@live.example.com'
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: 'manager@example.com,teamleader@example.com,developer@example.com'
from: 'noreply@live.example.com'
* _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: 'manager@example.com,teamleader@example.com,developer@example.com'
from: 'noreply@live.example.com'
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: your-account@gmail.com
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' => 'first.developer@example.com',
'from,' => 'noreplay@yout-project.com'));
### Run the plugin tests
It's used _[sfPhpunitPlugin](http://www.symfony-project.org/plugins/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](http://github.com/makasim/fpErrorNotifierPlugin/issues) or make a fork and do your changes.