Search by

mountain / laraslack

ThomasMountain

Send alerts, notifications and Block Kit messages to Slack from Laravel via incoming webhooks.

Package info

github.com/ThomasMountain/laraslack

pkg:composer/mountain/laraslack

Statistics

Installs: 359

Dependents: 0

Suggesters: 0

Stars: 2

Open Issues: 0

v2.0.0 2026-09-30 12:00 UTC

This package is auto-updated.

Last update: 2026-10-29 16:07:10 UTC


README

Send alerts, notifications and Block Kit messages to Slack from Laravel, via incoming webhooks.

  • No Slack SDK, no OAuth, no queue requirement. One HTTP POST.
  • Posts through Laravel's Http client, so it is fakeable in tests and uses your existing connection handling.
  • Sensible defaults for local and testing environments: with no webhook configured, nothing is sent.

Requirements

  • PHP 8.1+
  • Laravel 10, 11 or 12

Installation

composer require mountain/laraslack

The service provider is auto-discovered. Publish the config if you want to edit it in your application:

php artisan vendor:publish --tag=laraslack-config

Then add your webhook URL to .env:

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX

To create a webhook, go to https://api.slack.com/messaging/webhooks and create a Slack app with the Incoming Webhooks permission, or add an incoming webhook to an existing one.

Usage

use ThomasMountain\LaraSlack\Facades\LaraSlack;

// Simplest possible message.
LaraSlack::send('Deploy finished');

// Same thing, with the builder.
LaraSlack::message('Deploy finished')->send();

send() returns true if Slack accepted the message, and false if it was skipped or rejected. It does not throw unless you ask it to.

Block Kit

LaraSlack::message('Deployment finished')
    ->blocks([
        [
            'type' => 'header',
            'text' => ['type' => 'plain_text', 'text' => 'Deployment finished'],
        ],
        [
            'type' => 'section',
            'fields' => [
                ['type' => 'mrkdwn', 'text' => "*Environment*\nproduction"],
                ['type' => 'mrkdwn', 'text' => "*Duration*\n1m 42s"],
            ],
        ],
    ])
    ->send();

Attachments

LaraSlack::message('Nightly build failed')
    ->attachment([
        'color' => '#e01e5a',
        'title' => 'Nightly build failed',
        'text' => 'Exit code 1 on `main`',
        'footer' => 'CI',
        'ts' => time(),
    ])
    ->send();

Posting to more than one channel

See "Identity and channels" below for why this matters.

LaraSlack::message('Disk nearly full')->webhook(config('services.slack.ops'))->send();
LaraSlack::message('Disk nearly full')->webhook(config('services.slack.dba'))->send();

Anything else

Anything the builder does not cover can be passed straight through as a raw Slack payload. This is also the reason the method is a single array rather than key/value pairs: a text value containing = would otherwise be misparsed as a form field.

LaraSlack::send([
    'text' => 'Nightly build failed',
    'unfurl_links' => false,
    'blocks' => [/* ... */],
]);

Without the facade

use ThomasMountain\LaraSlack\LaraSlackManager;

app(LaraSlackManager::class)->send('Deploy finished');

Identity and channels

channel, username and icon are only honoured by legacy custom integration webhooks. Webhooks that belong to a Slack app ignore all three, because the app's own configuration wins:

You cannot override the default channel (chosen by the user who installed your app), username, or icon when you're using incoming webhooks to post messages. — Slack's documentation

So if SLACK_CHANNEL seems to be ignored, that is why. To post to a different channel, post to a different webhook, which is scoped to a channel at creation time. That is what webhook() is for.

If you need per-message identity as well, use the chat.postMessage Web API method with a bot token and the chat:write.customize scope instead. This package deliberately does not do that, to avoid pulling in token management.

Testing

With no SLACK_WEB_HOOK_URL configured, send() returns false and makes no request, so nothing is posted to Slack from your test suite.

To assert on what would have been sent, fake the HTTP client:

use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\Http;
use ThomasMountain\LaraSlack\Facades\LaraSlack;

protected function setUp(): void
{
    parent::setUp();

    config()->set('slack.endpoint', 'https://hooks.slack.test/services/T000/B000/XXXX');

    Http::fake(['*' => Http::response('ok')]);
}

public function test_it_alerts_ops_when_a_deploy_finishes(): void
{
    LaraSlack::message('Deploy finished')->send();

    Http::assertSent(function (Request $request) {
        $payload = json_decode($request->data()['payload'], true, flags: JSON_THROW_ON_ERROR);

        $this->assertSame('Deploy finished', $payload['text']);

        return true;
    });
}

Remember that Slack answers with HTTP 200 and a body of ok on success, so fake that rather than a bare Http::response() if you want the transport to see a success.

Configuration

Key Env Default Notes
endpoint SLACK_WEB_HOOK_URL null Blank or missing disables sending entirely.
channel SLACK_CHANNEL null Legacy webhooks only.
username SLACK_USERNAME null Legacy webhooks only.
icon SLACK_ICON null An emoji shortcode, e.g. :rocket:. Legacy webhooks only.
enabled SLACK_ENABLED true Master switch.
throw_exceptions SLACK_THROW_EXCEPTIONS false Throw SlackRequestException instead of logging.
connect_timeout SLACK_CONNECT_TIMEOUT 3 Seconds to establish a connection.
timeout SLACK_TIMEOUT 5 Seconds for the whole request.
verify_tls SLACK_VERIFY_TLS true Leave this on.
proxy SLACK_PROXY null e.g. http://user:pass@proxy.internal:3128.

Error handling

By default a failed message is reported to your application logger and send() returns false. That includes connection failures, DNS errors and timeouts, so a Slack outage never breaks the request that triggered the alert.

Set SLACK_THROW_EXCEPTIONS=true to throw instead:

use ThomasMountain\LaraSlack\Exceptions\SlackRequestException;

try {
    LaraSlack::message('Deploy finished')->send();
} catch (SlackRequestException $e) {
    $e->status;   // HTTP status, or null if Slack was never reached
    $e->body;     // Slack's response body, e.g. 'invalid_payload'
    $e->payload;  // what was sent
}

Note that Slack reports most webhook errors with an HTTP 200 and a plain text body such as invalid_payload or channel_not_found, so a 2xx status on its own does not mean the message arrived. This package checks both.

A message with no text, blocks or attachments throws EmptyMessageException before any request is made, rather than being posted as a blank message.

Contributing

composer install
composer test

Licence

MIT. See LICENSE.