Error Notifier Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require elao/error-notifier-bundle:dev-master
   

   Register the bundle in config/bundles.php:

   Elao\ErrorNotifierBundle\ElaoErrorNotifierBundle::class => ['all' => true],
   

2. Configuration: Add to config/packages/elao_error_notifier.yaml:

   elao_error_notifier:
       recipients: ['admin@example.com']
       # Optional: Customize email subject, template, or transport
   

3. First Use Case: Trigger a 500 error (e.g., throw new \Exception('Test error') in a controller). Verify the email arrives with:

   • Error details (message, stack trace, request data).
   • Environment context (Symfony version, PHP config).
   • User session data (if authenticated).

Implementation Patterns

Core Workflows

1. Error Handling Integration:

   • Symfony Events: Listen to kernel.exception (for HTTP errors) and kernel.terminate (for PHP fatal errors).

     // config/services.yaml
     services:
         App\EventListener\ErrorNotifierListener:
             tags:
                 - { name: 'kernel.event_listener', event: 'kernel.exception', method: 'onKernelException' }
     

   • Custom Logic: Extend Elao\ErrorNotifierBundle\Notifier\NotifierInterface to filter errors or enrich payloads.

2. Email Customization:

   • Override the default Twig template (templates/elao_error_notifier/email.html.twig).
   • Pass dynamic data via setTemplateVariables() in a custom notifier service.

3. Transport Flexibility:

   • Use Symfony’s mailer component for async sending:

     elao_error_notifier:
         transport: 'async'
     

   • Integrate with external APIs (e.g., Slack) by implementing NotifierInterface.

Advanced Patterns

• Environment-Specific Notifications:

  elao_error_notifier:
      environments: ['prod', 'staging']  # Only notify in these
  

• Rate Limiting: Cache error notifications to avoid spam (e.g., using symfony/cache).
• Sensitive Data Redaction: Filter request data in Elao\ErrorNotifierBundle\Notifier\Notifier:

  protected function getRequestData(Request $request) {
      $data = parent::getRequestData($request);
      unset($data['password']); // Example: Redact sensitive fields
      return $data;
  }
  

Gotchas and Tips

Pitfalls

1. Archived Package:

   • No active maintenance; fork or patch locally if critical bugs arise.
   • Test thoroughly in staging before relying on it in production.

2. Configuration Overrides:

   • Ensure elao_error_notifier.yaml is loaded after default configs to avoid precedence issues.
   • Debug missing emails by checking Symfony’s monolog logs for Elao\ErrorNotifierBundle entries.

3. Fatal Errors:

   • PHP fatal errors (e.g., syntax errors) may not trigger notifications due to early termination. Use register_shutdown_function as a fallback:

     register_shutdown_function(function() {
         if (($error = error_get_last()) && in_array($error['type'], [E_ERROR, E_PARSE])) {
             // Log or notify manually
         }
     });
     

4. Email Delivery:

   • Verify swiftmailer (or mailer) is configured in config/packages/mailer.yaml.
   • Test with php bin/console debug:mailer:send to confirm transport works.

Debugging Tips

• Enable Debug Mode:

  elao_error_notifier:
      debug: true  # Logs errors to Symfony's logger
  

• Inspect Notifier: Override Elao\ErrorNotifierBundle\Notifier\Notifier to dump payloads:

  public function notify(Error $error) {
      file_put_contents('/tmp/error_notifier_debug.log', print_r($error->getDetails(), true));
      parent::notify($error);
  }
  

• Check Dependencies: Ensure symfony/debug, twig, and swiftmailer are installed (required for full functionality).

Extension Points

1. Custom Notifiers: Implement NotifierInterface to add channels (e.g., SMS, PagerDuty):

   class SlackNotifier implements NotifierInterface {
       public function notify(Error $error) {
           // Send to Slack webhook
       }
   }
   

   Register in services.yaml:

   services:
       App\Notifier\SlackNotifier:
           tags: [elao_error_notifier.notifier]
   

2. Dynamic Recipients: Use a service to resolve recipients dynamically:

   elao_error_notifier:
       recipient_resolver: 'app.error_recipient_resolver'
   

   class ErrorRecipientResolver {
       public function resolve(Error $error) {
           return ['team-' . $error->getType() . '@example.com'];
       }
   }
   

3. Template Inheritance: Extend the base template to add company branding:

   {# templates/elao_error_notifier/email.html.twig #}
   {% extends '@ElaoErrorNotifier/email.html.twig' %}
   {% block header %}
       {{ parent() }}
       <img src="{{ asset('images/logo.png') }}" alt="Company Logo">
   {% endblock %}