Slack Notifier Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require symfony/slack-notifier
   

2. Configure the DSN in .env:

   SLACK_DSN=slack://xoxb-YOUR_BOT_TOKEN@default?channel=#general
   

   • Replace xoxb-YOUR_BOT_TOKEN with your Slack Bot Token (starts with xoxb-).
   • Replace #general with your target channel (e.g., @user, C1234567890, or #channel-name).

3. Send your first message in a controller or command:

   use Symfony\Component\Notifier\Notifier;
   use Symfony\Component\Notifier\Message\ChatMessage;
   
   $notifier = new Notifier([], [new SlackTransport($dsn)]);
   $notifier->send(new ChatMessage('Hello Slack!'));
   

First Use Case: Alerts

Use Slack Notifier to send real-time alerts (e.g., deployment failures, errors):

$notifier->send(
    new ChatMessage('Deployment failed on staging!')
        ->options((new SlackOptions())->block(
            (new SlackSectionBlock())
                ->text('*Error*: Database connection timeout')
                ->accessory(new SlackButtonBlockElement('View logs', 'https://logs.example.com', 'danger'))
        ))
);

Implementation Patterns

1. Structured Messaging Workflow

• Build blocks incrementally for complex messages:

  $options = (new SlackOptions())
      ->block(new SlackHeaderBlock('Incident Report'))
      ->block(new SlackDividerBlock())
      ->block((new SlackSectionBlock())
          ->text('Service: *Payment Processor*')
          ->field('Status', '⚠️ Degraded')
          ->field('Impact', '10% of users')
      )
      ->block(new SlackActionsBlock()
          ->button('Acknowledge', 'https://status.example.com/ack', 'primary')
          ->button('Escalate', 'https://status.example.com/escalate', 'danger')
      );
  

• Reuse blocks in templates (e.g., for error handling):

  function createErrorBlock(string $error, string $url): SlackSectionBlock {
      return (new SlackSectionBlock())
          ->text("Error: *$error*")
          ->accessory(new SlackButtonBlockElement('Details', $url, 'danger'));
  }
  

2. Integration with Laravel Services

• Queue notifications for async delivery:

  use Illuminate\Bus\Queueable;
  use Illuminate\Contracts\Queue\ShouldQueue;
  use Symfony\Component\Notifier\Message\ChatMessage;
  
  class SlackAlert implements ShouldQueue {
      use Queueable;
  
      public function __construct(public string $message, public array $options = []) {}
  
      public function handle() {
          $notifier = app(Notifier::class);
          $notifier->send(new ChatMessage($this->message, $this->options));
      }
  }
  

  Dispatch via:

  SlackAlert::dispatch('Database down!', $slackOptions)->onQueue('slack');
  

• Leverage Laravel Events:

  // In EventServiceProvider
  protected $listen = [
      'deploy:failed' => [SlackAlert::class],
  ];
  

3. Dynamic Channel Routing

• Route messages based on context (e.g., environment):

  $channel = config('app.env') === 'production' ? '#alerts' : '@dev-team';
  $dsn = "slack://{$token}@default?channel={$channel}";
  

• Use environment-specific DSNs:

  SLACK_DSN_PROD=slack://xoxb-prod-token@default?channel=#production-alerts
  SLACK_DSN_STAGING=slack://xoxb-staging-token@default?channel=@staging-team
  

4. Interactive Elements

• Confirmations for critical actions:

  $block = (new SlackActionsBlock())
      ->button(
          'Delete Backup',
          'https://backup.example.com/delete',
          'danger',
          'delete_backup',
          [
              'title' => ['type' => 'plain_text', 'text' => 'Confirm Deletion'],
              'text' => ['type' => 'plain_text', 'text' => 'Are you sure?'],
              'confirm' => ['type' => 'plain_text', 'text' => 'Delete'],
              'deny' => ['type' => 'plain_text', 'text' => 'Cancel'],
          ]
      );
  

• Modal dialogs (via Slack’s open URL scheme):

  $block->button(
      'Configure',
      'https://your-app.com/slack-modal?team={team_id}&channel={channel_id}',
      'primary'
  );
  

5. Message Updates

• Track and update messages (e.g., for long-running tasks):

  // Send initial message
  $sentMessage = $notifier->send(new ChatMessage('Processing order #123...'));
  if ($sentMessage instanceof SlackSentMessage) {
      $messageId = $sentMessage->getMessageId();
      $channelId = $sentMessage->getChannelId();
  }
  
  // Update later
  $notifier->send(
      new ChatMessage('Order #123 completed!', new UpdateMessageSlackOptions($channelId, $messageId))
  );
  

Gotchas and Tips

Common Pitfalls

1. Invalid DSN Formats:

   • ❌ slack://xoxb-token@default?channel=#channel (Slack requires @user or encoded IDs for DMs/private channels).
   • ✅ Use slack://xoxb-token@default?channel=C1234567890 or @username.

2. Bot Token Permissions:

   • Ensure your bot token has chat:write and chat:write.public scopes.
   • Test with chat.postMessage in Slack’s API tester first.

3. Rate Limits:

   • Slack enforces rate limits. Queue messages if sending bursts (e.g., during deployments).

4. Threading Issues:

   • threadTs must reference a valid message timestamp. Use SlackSentMessage to capture this:

     $sent = $notifier->send(new ChatMessage('Parent message'));
     $reply = new ChatMessage('Reply', (new SlackOptions())->threadTs($sent->getMessageId()));
     

5. Block Kit Validation:

   • Slack rejects malformed blocks. Validate with:

     curl -X POST -H 'Content-type: application/json' \
          --data '{"blocks": [YOUR_BLOCKS_JSON]}' \
          https://slack.com/api/chat.postMessage?token=xoxb-token&channel=CHANNEL
     

Debugging Tips

• Enable Symfony Notifier Debug:

  $notifier = new Notifier([], [], [
      'debug' => true, // Logs raw API responses
  ]);
  

• Inspect Raw Payloads: Use SlackTransport::getClient() to access the underlying GuzzleHttp\Client for debugging:

  $client = $transport->getClient();
  $response = $client->request('POST', 'https://slack.com/api/chat.postMessage', [
      'json' => $message->toArray(),
  ]);
  

Performance Optimization

• Batch Messages: Use SlackOptions::postAt() to schedule messages and avoid rate limits:

  $options = (new SlackOptions())->postAt(new \DateTime('+5 minutes'));
  

• Lazy-Load Blocks: For dynamic content, build blocks just before sending to avoid memory bloat.

Extension Points

1. Custom Block Types: Extend SlackBlockInterface to create reusable components:

   class CustomBlock implements SlackBlockInterface {
       public function toArray(): array {
           return ['type' => 'section', 'text' => ['type' => 'mrkdwn', 'text' => $this->content]];
       }
   }
   

2. Transport Decorators: Wrap SlackTransport to add logic (e.g., logging, retries):

   class LoggingSlackTransport extends AbstractTransport {
       public function __construct(private SlackTransport $transport) {}
   
       public function send(ChatMessage $message): SentMessage {
           \Log::debug('Sending Slack message', $message->toArray());
           return $this->transport->send($message);
       }
   }
   

3. Dynamic DSN Resolution: Override DSN logic in SlackTransportFactory for multi-environment setups:

   $factory = new SlackTransportFactory