Slackbot Laravel Package

Getting Started

Verify what you actually installed before writing a line of bot code. The sources disagree on the deployment model — one describes an RTM/websocket driver needing a long-running supervised process, the other an HTTP webhook package for slash commands and the Events API. These have different infrastructure, security, and on-call footprints. Resolve it from source, not from 2020-era docs:

composer show mpociot/slackbot        # pinned version + its botman/driver constraints
composer update --dry-run             # does it even resolve on your Laravel/PHP?

Look at the driver class the service provider binds and whether the package exposes a listen entrypoint (console command / route handler) or expects a webhook route. That single fact gates everything else.

Install and configure (Laravel 7/8 is the claimed happy path):

composer require mpociot/slackbot
php artisan vendor:publish --provider="Mpociot\SlackBot\SlackBotServiceProvider"

Register the provider and facade if the version predates auto-discovery, then put the Slack token in .env and reference it through config/slackbot.php — never read env() directly from bot code, since config:cache will silently return null in production. Create a Slack app with the scopes the driver actually asks for, invite the bot to a sandbox channel, and confirm the transport works with a trivial echo before building anything real.

Where to look first: the service provider (what it binds and registers), the published config (token, bot name, driver options), and the driver's hears/respondsTo implementation — BotMan normalizes inbound messages into a message object, so knowing its shape is most of the debugging battle.

First use case: a handler that reads real application state, not a ping/pong. The entire value proposition is that the bot is a thin interface over logic you already have — Eloquent, queues, policies, jobs — so your first slice should prove that claim. Something like @bot status staging returning the latest deploy from your deployments table, or a slash command that returns who is currently on call. A day's work, and it tells you whether the dependency is worth keeping.

Implementation Patterns

Keep handlers thin; put logic in domain services. Handlers should parse intent, authorize, dispatch, and reply — nothing more. Everything they call should be independently testable and reachable from a controller, a job, or a console command. This is not stylistic: it is what makes the bot a replaceable adapter rather than a rewrite when you migrate off an unmaintained library.

SlackBot::hears('deploy status {env}', function ($bot, $message) {
    $deploy = app(DeploymentStatus::class)->latestFor($message->getParameter('env'));
    $bot->reply($deploy->summary());
});

Register handlers in one place. A dedicated BotServiceProvider (or app/Bot/ directory with a single boot file) beats scattering hears() calls across providers. hears() for keyword/mention triggers, respondsTo() for regex, and the event/on() hooks for channel joins, message edits, and mentions. Namespace commands (deploy approve, deploy status) rather than free-text matching — it keeps the routing table readable and the intent unambiguous.

Route interactive components through a dispatch table, not a closure pile. Buttons and menu actions arrive as payloads with a callback_id; map callback_id to an action class and keep the payload parsing in one place. Key side effects on action_ts / trigger_id / response_url so Slack's retries cannot double-approve a deployment.

Authorize with the Laravel you already have. A deploy-approval button must check a policy against the Slack user's mapped identity (email lookup against users, or a slack_id column). This is the payoff of reusing the monolith: no second auth model, no second permission system, no divergent answer to "may this person do this?"

Offload anything slow to the queue. Slack expects a fast response and its response_url expires; dispatch a job for anything touching a slow API or a report query, then reply asynchronously. Outbound sends — the CI/CD notification case — belong in queued jobs with retry and backoff as a matter of course, not as a later optimization.

Prefer stateless commands over conversations. BotMan's ask()/conversation state is convenient but lives in the driver; across restarts or multiple web dynos it becomes a correctness bug. Where you genuinely need multi-step interaction, persist state explicitly (cache/Redis/DB) keyed on user + channel, and treat the framework's conversation cache as an optimization, not the source of truth.

Keep conversational state and transport state out of your domain. A SlackClient-style interface with reply(), postEphemeral(), openConversation() implemented by the bot gives you one seam to swap. Handlers depend on the interface; only the adapter knows BotMan exists. This is the cheapest insurance available against the dependency's staleness.

Test the seam, not the library. Unit-test domain services and action classes directly. For the bot layer, post recorded Slack payload fixtures at the webhook route (or invoke the handler) and assert on the outbound call via a fake adapter. When you migrate to Bolt or BotMan directly, only the adapter test suite changes.

Gotchas and Tips

Dependency resolution is the real first test. The last release is September 2020 and claims Laravel 7/8 only. On Laravel 10/11 or PHP 8.2+, assume incompatibility until composer update --dry-run passes in a scratch project on the exact target stack. If it fails there, you've lost two hours instead of two weeks. Pin versions, commit the lockfile, and name the engineer who will fork if a Laravel upgrade gets blocked.

Consider skipping the wrapper. mpociot/slackbot is a thin Laravel-flavored layer over botman/botman; with zero dependents, the wrapper inherits the staleness with none of the community. Depending on BotMan directly costs a small amount of setup and removes a package from your fork list.

The deployment model is a security decision. If it's a public webhook, Slack signing-secret verification, timestamp replay protection (reject payloads older than a few minutes), and rejection of unsigned requests are non-negotiable — and must be confirmed in the driver source, not assumed. If it's RTM, the token has a broader surface, the process needs a supervisor, and connection management across restarts becomes an operational concern. Confirm which one you're running before a security review, not after.

Slack's retry semantics will bite you. Events are retried (X-Slack-Retry-Num), interactive payloads can arrive twice, and slash commands time out in three seconds. Make handlers idempotent and answer fast. Log the raw inbound payload before parsing anything — half of all integration bugs are payload-shape mismatches, and the raw log resolves them in one look.

Config and env quirks. php artisan config:cache in deployment will break any env() call made at runtime inside bot code; always go through config. If you support multiple workspaces, the single-token config model is a hard limit — plan for per-workspace config keys or accept one workspace per deployment.

Rate limits and outages are yours to handle. The library predates most modern Slack platform changes and will not handle 429s or token rotation for you. Wrap outbound calls, honor Retry-After, and alert on non-2xx webhook responses — a silently failing bot is worse than no bot, because the team stops trusting the workflow and goes back to doing it manually.

Debugging workflow that works: a scratch Slack workspace, a trivial echo handler, structured logging of every inbound payload and every outbound request, and a route or command you can invoke locally to exercise handlers without Slack in the loop. Do not debug against a shared team channel.

Document the exit trigger in the repo. The package is effectively in an unannounced maintenance freeze. Write down the two conditions that force a fork or migration — an unpatched Slack API break, or a Laravel upgrade blocked by the dependency — and keep the adapter boundary intact so acting on them is a contained change rather than an archaeology project.