Slack Laravel Package

Getting Started

1. Install the package

   composer require quitoque/slack
   

2. Register the service provider (if not auto-discovered) Laravel 5.5+ should auto-discover Quitoque\Slack\SlackServiceProvider and the Slack facade. On older apps, add them manually in config/app.php:

   'providers' => [
       Quitoque\Slack\SlackServiceProvider::class,
   ],
   'aliases' => [
       'Slack' => Quitoque\Slack\Facades\Slack::class,
   ],
   

3. Publish the config and set credentials

   php artisan vendor:publish --provider="Quitoque\Slack\SlackServiceProvider"
   

   Then set a Slack token in .env (typically SLACK_TOKEN=xoxb-...). The package is token-based, so use a bot/user token with the scopes you need (chat:write, channels:read, users:read, etc.).

4. Where to look first

   • config/slack.php for the token, base URI, and any HTTP/timeout options.
   • vendor/quitoque/slack/src to see which Slack endpoints are wrapped and how methods are named. The package exposes Slack Web API endpoints as PHP objects/methods (e.g. chat, users, channels), so the source is the fastest reference for supported calls.
   • Slack's own Web API docs for the parameter names and response shape you are passing through.

5. First use case — send a message

   use Quitoque\Slack\Facades\Slack;
   
   Slack::chat()->postMessage([
       'channel' => '#general',
       'text'    => 'Deploy finished ✅',
   ]);
   

   Verify in php artisan tinker before wiring it into application code.

Implementation Patterns

• Wrap the facade in a notifier service. Don't scatter Slack::... calls through controllers. Create a small class (e.g. App\Services\SlackNotifier) that takes the client via the container, so you can test and swap it later.
• Event → message mapping. Use a listener or a dedicated event class per Slack message (DeploymentSucceeded, NewOrderReceived) rather than inline array literals. Keeps channel names, text formatting, and blocks in one place.
• Queue the send. Slack API latency and rate limits should not block a request. Implement ShouldQueue on the job/notification that sends the message, or dispatch a queued listener.
• Rich messages. Pass Slack attachments or blocks arrays directly in the payload. Keep a small builder per message type so colors/fields stay consistent.
• Environment-aware channels. Read channel names from config (services.slack.alerts_channel) and default to a dev/sandbox channel outside production:

  'channel' => app()->isProduction() ? '#alerts' : '#dev-alerts',
  

• Dependency injection. Resolve the underlying client from the container and type-hint it in constructors. Prefer this over the facade in long-lived classes (jobs, services) for testability.
• Multi-workspace / multi-token. If the package allows constructing a client with a token, build one instance per workspace instead of relying solely on the global config.
• Tests. Mock the facade (Slack::shouldReceive('chat')...) or bind a fake notifier in the container. Never call live Slack from the test suite.

Gotchas and Tips

• Missing scopes cause silent-looking failures. A missing_scope or not_in_channel response is returned in the Slack payload, not always as an exception. Check the response body, not just for thrown errors. The bot must be invited to private channels.
• Prefer channel IDs over names. Modern Slack API calls expect C01234567-style IDs; #general can work for posting but breaks for reads and private channels. Cache the name→ID map in config or a DB table.
• Rate limits. Slack returns HTTP 429 with Retry-After. Catch it and back off; don't retry in a tight loop. Queued + retried jobs should be idempotent (use text + a unique key, or accept duplicates).
• Config caching surprises. After changing .env, run php artisan config:clear. A cached config with the old token is a common "why doesn't it work" cause.
• Facade alias collisions. If you also install maknz/slack or another Slack package, two Slack aliases conflict. Alias one explicitly in config/app.php.
• Response object shape. Depending on the version, endpoints may return arrays, Guzzle responses, or custom result objects. Don't assume ->get('ok') or ['ok'] — check the package source or dump once with dd() in tinker.
• Timeouts. Guzzle defaults can hang a worker. Set a short connect/read timeout in the published config and keep sends queued with a sensible retry_after.
• Maintenance risk. This is a small, low-usage package with few dependents. It may lag behind Slack API changes (e.g. deprecation of legacy methods, blocks vs attachments). Pin the version in composer.json, skim the source before relying on a method, and keep a thin wrapper around it so you can swap in jolicode/slack-php-api or slack-php/slack-php with minimal churn.
• Extension points. If an endpoint you need isn't wrapped, either extend the package's client class or make a direct Guzzle call through the same token; keep those raw calls in your wrapper so they're easy to migrate later.