Slack Exception Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Package Add to composer.json:

   "require": {
       "atolye15/slack-exception-bundle": "dev-master"
   }
   

   Run:

   composer update
   

2. Enable the Bundle Register in app/AppKernel.php:

   public function registerBundles()
   {
       $bundles = [
           // ...
           new Atolye15\SlackExceptionBundle\Atolye15SlackExceptionBundle(),
       ];
   }
   

3. Configure Slack Add to config/packages/atolye15_slack_exception.yaml (or app/config/config.yml in older Laravel):

   atolye15_slack_exception:
       token: "YOUR_SLACK_WEBHOOK_TOKEN"  # From Slack API
       channel: "#alerts"                  # Target channel
       environment: prod                  # Filter exceptions by env
   

4. First Use Case Trigger an exception (e.g., 1/0 in a route) and verify the error appears in Slack.

Implementation Patterns

Core Workflow

1. Exception Handling The bundle hooks into Laravel’s exception handler (App\Exceptions\Handler). Exceptions are automatically forwarded to Slack if they match the configured environment (prod by default).

2. Customizing Messages Override the default Slack message format by extending the bundle’s SlackExceptionFormatter:

   // app/SlackExceptionFormatter.php
   use Atolye15\SlackExceptionBundle\Formatter\SlackExceptionFormatter as BaseFormatter;
   
   class SlackExceptionFormatter extends BaseFormatter
   {
       protected function formatMessage(Exception $e)
       {
           return "🚨 **$e->getMessage()**\n```$e->getTraceAsString()```";
       }
   }
   

   Bind it in services.yaml:

   services:
       Atolye15\SlackExceptionBundle\Formatter\SlackExceptionFormatter:
           class: App\SlackExceptionFormatter
   

3. Environment Filtering Use environment: all to log exceptions in all environments (dev/staging/prod). Defaults to prod only.

4. Conditional Logging Skip specific exceptions by extending the handler:

   // app/Exceptions/Handler.php
   public function report(Throwable $exception)
   {
       if ($exception instanceof \Symfony\Component\HttpKernel\Exception\NotFoundHttpException) {
           return; // Skip 404s
       }
       parent::report($exception);
   }
   

5. Testing Mock Slack responses in tests:

   $this->partialMock(Atolye15\SlackExceptionBundle\SlackClient::class, ['send']);
   

Gotchas and Tips

Pitfalls

1. Token Security

   • Hardcoding tokens in config/ is unsafe. Use Laravel’s .env:

     SLACK_TOKEN=xoxb-your-token
     

   • Restrict the token’s permissions to Incoming Webhooks only.

2. Rate Limits

   • Slack’s webhook rate limit is 1000 requests/second. Excessive exceptions may trigger throttling.
   • Monitor Slack’s API status: https://status.slack.com.

3. Async Failures

   • If throw_exception: true, Slack failures will crash your app. Use false (default) for graceful degradation.

4. Legacy Laravel

   • The bundle targets Symfony 2.x (Laravel 4/5). For Laravel 8+, use a modern alternative like spatie/laravel-slack-notifier.

5. Missing Dependencies

   • The package lacks PHP 7+ support. Ensure your composer.json enforces PHP 7.4+:

     "config": {
         "platform": {
             "php": "7.4"
         }
     }
     

Debugging Tips

1. Verify Webhook URL Test the token manually via Slack’s API tester:

   curl -X POST -H 'Content-type: application/json' \
   --data '{"text":"Test message"}' \
   https://hooks.slack.com/services/YOUR/WEBHOOK
   

2. Check Logs Enable debug mode in config/atolye15_slack_exception.yaml:

   debug: true
   

   Logs appear in storage/logs/laravel.log.

3. Timeout Issues Increase request_timeout (in ms) if Slack responses are slow:

   request_timeout: 5000  # 5 seconds
   

4. Extension Points

   • Custom Channels: Dynamically set channels per exception:

     $this->slackClient->setChannel("#{$exception->getCode()}-alerts");
     

   • Attachments: Add context via Slack attachments:

     $attachment = [
         'title' => 'User Context',
         'fields' => [[
             'title' => 'User ID',
             'value' => auth()->id(),
             'short' => true,
         ]],
     ];
     $this->slackClient->addAttachment($attachment);
     

5. Fallback Notifications Combine with email alerts for critical paths:

   use Illuminate\Support\Facades\Mail;
   
   public function report(Throwable $exception)
   {
       parent::report($exception);
       Mail::to('team@example.com')->send(new ExceptionMail($exception));
   }