Download the PHP package conduit-ui/mattermost without Composer

Mattermost for Laravel

The Laravel way to build Mattermost bots.

Status: Under active development. Not yet published on Packagist.

Contents

• Features
• Requirements
• Installation
• Configuration
• Quick start
• REST API client
• Sending messages
• Bot framework
• Slash commands
• Interactive messages
• Streaming replies
• Notifications
• Filament panel
• Artisan commands
• Testing
• Multi-server
• Local development
• License

Features

• Saloon-based REST client covering the full Mattermost API v4
• WebSocket client with auto-reconnect, typed events, and signal handling
• Event-driven bot framework — class-based handlers, middleware pipeline, queueable
• Permission guards — role, permission, channel-membership middleware
• Slash command routing
• Interactive messages — buttons, menus, action handlers
• Streaming replies — observer-driven create → edit → finalize flow
• Fluent message builder with attachments, threading, file uploads
• Laravel notification channel + broadcast driver
• Filament admin panel for status, message log, health
• Artisan commands — mattermost:listen, mattermost:post, mattermost:health
• First-class testing — Mattermost::fake(), fixture helpers, request assertions
• Multi-server support via named connections

Requirements

• PHP 8.4+
• Laravel 13+

Installation

Set the minimum env in your .env:

Configuration

config/mattermost.php defines connections, slash commands, bot middleware, and websocket settings. Most of it has sensible defaults — only connections typically needs touching.

Quick start

REST API client

Every Mattermost API v4 endpoint is wrapped in a Saloon resource. Resources are auto-generated from the OpenAPI spec — every parameter and response is typed.

Available resources via the Mattermost facade: posts(), channels(), users(), teams(), files(), reactions(), bots(), webhooks(), commands(), emoji(), status(), system().

Sending messages

The fluent Message builder produces a payload for POST /api/v4/posts without making any HTTP call — pass the result to posts()->createPost().

Bot framework

Mattermost WebSocket events route through a global + per-handler middleware pipeline to handler classes resolved from the container.

Handler classes

reply(), react(), and typing() come from the base Handler class — they pick up the correct connection, bot user id, and threading rules automatically.

Middleware

Built-in middleware ships under ConduitUI\Mattermost\Bot\Middleware:

Custom middleware implements the Middleware interface:

Guards

Permission-based middleware under ConduitUI\Mattermost\Bot\Middleware\Guards:

Queueable handlers

Handlers implementing ShouldQueue are dispatched onto Laravel's queue rather than running inline:

Configure the queue/connection per config/mattermost.php:

Slash commands

Register slash commands with the same route-style API as event handlers:

Mattermost POSTs slash command webhooks to /mattermost/slash/{command}. The route is auto-registered when enable_slash_commands is true in config.

Inside a handler:

Interactive messages

Buttons and menus on Mattermost messages POST to /mattermost/interactive when clicked. Register handlers for action ids:

The button itself is built into your post's attachments:

The context you set on the button is what the DTO surfaces as $action->context(), and context.action is what actionId() returns.

Streaming replies

For bots replying with LLM tokens, the streaming layer creates a placeholder, edits it as chunks arrive, and finalizes:

Behind the scenes: posts()->createPost() for the placeholder, batched updatePost() calls debounced to respect rate limits, and a final patch with the full text.

Notifications

Use Mattermost as a Laravel notification channel:

Route via routeNotificationFor('mattermost', ...) on the notifiable, or pass ['channel' => 'channel-id', 'connection' => 'staging'] to target a specific server.

A broadcast driver is also registered — set BROADCAST_CONNECTION=mattermost and broadcast()->channel('mattermost:channel-id') posts to Mattermost.

Filament panel

Auto-discovered Filament pages give you a status dashboard, message log, and health check inside your existing Filament admin:

Pages: Dashboard (connection + recent activity), Health (per-connection ping + latency), Message Log (recent posts).

Artisan commands

mattermost:listen handles SIGTERM/SIGINT cleanly; running it under supervisord or systemd is the recommended path.

Testing

Mattermost::fake() swaps the underlying client for an in-memory recorder. No HTTP, no network — every API call is captured for assertions.

Available assertions: assertSent, assertNotSent, assertNothingSent, assertPosted, assertNotPosted, assertNothingPosted, assertPostCount, assertUpdated, assertPatched, assertDeleted, assertReacted, assertNotReacted, assertFileUploaded, preventStrayPosts, recorded.

Fixture helpers under MattermostFixtures build realistic payloads for tests:

Multi-server

Define multiple connections in config/mattermost.php:

Pick the connection per call:

Local development

A docker-compose.yml ships a local Mattermost for development:

After the first boot, create an admin via mmctl or the web UI at localhost:8065, generate a bot token, and drop it into your .env.

The integration test suite runs against the live container:

License

MIT