Gitter Notifier Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require symfony/gitter-notifier
   

   Ensure your project uses Symfony HTTP Client (or integrate with Laravel HTTP Client if preferred).

2. First Use Case: Sending a Notification

   use Symfony\Component\Notifier\Notifier;
   use Symfony\Component\Notifier\Bridge\Gitter\GitterTransport;
   use Symfony\Component\Notifier\Message\ChatMessage;
   
   $notifier = new Notifier();
   $transport = new GitterTransport('YOUR_GITTER_WEBHOOK_URL');
   
   $message = (new ChatMessage('Hello from Laravel!'))
       ->from('Laravel App')
       ->to('YOUR_ROOM_ID');
   
   $notifier->send($message);
   

3. Key Files to Review

   • vendor/symfony/notifier/src/Bridge/Gitter/GitterTransport.php (Core transport logic)
   • vendor/symfony/notifier/src/Message/ChatMessage.php (Message formatting)

Implementation Patterns

Laravel Integration Workflow

1. Service Provider Setup

   // app/Providers/GitterNotifierServiceProvider.php
   public function register()
   {
       $this->app->singleton('gitter.notifier', function ($app) {
           return new Notifier([
               new GitterTransport(config('services.gitter.webhook')),
           ]);
       });
   }
   

2. Configurable Webhook

   // config/services.php
   'gitter' => [
       'webhook' => env('GITTER_WEBHOOK_URL'),
       'default_room' => env('GITTER_DEFAULT_ROOM'),
   ],
   

3. Usage in Controllers/Jobs

   use Illuminate\Support\Facades\Gitter;
   
   public function deploySuccess()
   {
       Gitter::send(new ChatMessage('Deployment successful!'))
           ->to(config('services.gitter.default_room'));
   }
   

Advanced Patterns

• Rich Formatting: Use Markdown in messages (Gitter supports it natively).

  $message = (new ChatMessage('**Bold** text and [links](https://laravel.com)'))
      ->mention('@team');
  

• Error Handling: Wrap notifications in try-catch to log failures silently.
• Rate Limiting: Implement a queue (Laravel's queue:work) to avoid hitting Gitter API limits.

Gotchas and Tips

Common Pitfalls

1. Webhook URL Validation

   • Gitter webhooks must be HTTPS. Test with curl -X POST -H "Content-Type: application/json" -d '{}' YOUR_WEBHOOK_URL.
   • Fix: Use config('services.gitter.webhook') and validate it in AppServiceProvider boot method.

2. Message Length Limits

   • Gitter truncates messages > 1000 characters. Split long messages or use attachments.
   • Tip: Use Str::limit() to preview content:

     $message = Str::limit($longText, 500) . ' (truncated)';
     

3. Room/Channel Permissions

   • Ensure your bot/user has permission to post in the target room.
   • Debug: Check Gitter API response for 403 Forbidden errors.

Debugging Tips

• Enable Symfony Notifier Debug Mode

  $notifier = new Notifier([$transport], [
      'debug' => env('APP_DEBUG', false),
  ]);
  

• Log Raw Responses

  $transport->setLogger($this->app->make('log'));
  

Extension Points

1. Custom Message Types Extend ChatMessage for Laravel-specific payloads:

   class LaravelChatMessage extends ChatMessage
   {
       public function withLaravelData(array $data): self
       {
           $this->context['laravel'] = $data;
           return $this;
       }
   }
   

2. Middleware for Notifications Add pre-send logic (e.g., sanitization):

   $transport->setOnSend(function (ChatMessage $message) {
       $message->html(Str::markdown($message->html()));
   });
   

3. Environment-Specific Webhooks Use Laravel's env() with fallbacks:

   $webhook = env('GITTER_PROD_WEBHOOK', env('GITTER_STAGING_WEBHOOK'));