Mattermost Publication Bundle Laravel Package

Getting Started

Minimal Steps

1. Install the Bundle

   composer require codebuds/mattermost-publication-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Codebuds\MattermostPublicationBundle\MattermostPublicationBundle::class => ['all' => true],
   ];
   

2. Configure the Bundle Add mattermost_publication.yaml to config/packages/:

   mattermost_publication:
       webhook_url: '%env(MATTERMOST_WEBHOOK_URL)%'
       username: 'LaravelApp'
       channel: '#notifications'
       icon_url: 'https://example.com/logo.png'
   

   Set the environment variable in .env:

   MATTERMOST_WEBHOOK_URL="https://your-mattermost-instance/hooks/xxxx"
   

3. First Use Case Inject MattermostPublication into a controller or service and publish a message:

   use Codebuds\MattermostPublicationBundle\Service\MattermostPublication;
   
   public function notifyUser(MattermostPublication $publication) {
       $publication->publish("Hello from Laravel!");
   }
   

Implementation Patterns

Dependency Injection

• Controllers/Commands: Inject MattermostPublication directly into methods or constructors.

  public function __construct(private MattermostPublication $publication) {}
  

• Event Listeners: Useful for async notifications (e.g., after user registration).

  public function onUserRegistered(UserRegisteredEvent $event) {
      $this->publication->publish("New user: {$event->user->name}");
  }
  

Dynamic Configuration

Override default config per message:

$publication->publish(
    "Custom message",
    [
        'channel' => '#admin',
        'username' => 'AdminBot',
    ]
);

Batch Publishing

For bulk operations (e.g., logging), use a loop with error handling:

foreach ($logs as $log) {
    try {
        $publication->publish($log->message, ['username' => 'LoggerBot']);
    } catch (\Exception $e) {
        Log::error("Mattermost publish failed: " . $e->getMessage());
    }
}

Integration with Laravel Queues

Wrap publish() in a job for async processing:

// Job class
public function handle() {
    $this->publication->publish("Async notification");
}

// Dispatch
NotifyMattermostJob::dispatch($publication);

Gotchas and Tips

Pitfalls

1. Webhook URL Validation

   • Always validate MATTERMOST_WEBHOOK_URL in .env; invalid URLs cause silent failures.
   • Test with curl first:

     curl -X POST -H 'Content-Type: application/json' -d '{"text":"test"}' $WEBHOOK_URL
     

2. Rate Limiting

   • Mattermost may throttle rapid requests. Add delays in loops:

     sleep(1); // 1-second delay between messages
     

3. Icon URL Requirements

   • icon_url must be publicly accessible. Use absolute URLs (e.g., https://).

4. Exception Handling

   • Wrap publish() calls in try-catch to avoid breaking user flows:

     try {
         $publication->publish("Critical alert!");
     } catch (\Exception $e) {
         // Log or notify admins
     }
     

Debugging

• Enable Debug Mode Add to config/packages/mattermost_publication.yaml:

  debug: true
  

  This logs raw payloads to Symfony’s debug toolbar.

• Check Payload Structure Use dd($publication->getPayload($message)) to inspect the final JSON before sending.

Extension Points

1. Custom Payloads Extend the service to support rich messages (e.g., buttons, attachments):

   $publication->publishWithPayload([
       'text' => 'Alert!',
       'attachments' => [/* ... */],
   ]);
   

2. Multiple Webhooks Register multiple configurations in config/packages/ (e.g., mattermost_dev.yaml, mattermost_prod.yaml) and switch via environment.

3. Middleware Add a middleware to auto-publish on specific routes:

   public function handle($request, Closure $next) {
       $response = $next($request);
       $publication->publish("Route accessed: {$request->path()}");
       return $response;
   }