Getting Started

Minimal Setup

Installation:

composer require spatie/laravel-slack-alerts

Publish the config file:

php artisan vendor:publish --provider="Spatie\SlackAlerts\SlackAlertsServiceProvider"

Configuration:
- Set your Slack webhook URL in .env:
```
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ
```
- Optionally configure channels, default message format, or retry logic in config/slack-alerts.php.

First Use Case: Send a basic alert in a controller or command:

use Spatie\SlackAlerts\Facades\SlackAlert;

SlackAlert::message("User {$user->name} signed up!");

Where to Look First

Facade: Spatie\SlackAlerts\Facades\SlackAlert (primary entry point).
Config: config/slack-alerts.php (customize channels, formatting, retries).
Jobs: app/Jobs/SendSlackAlert (extend or inspect for custom logic).

Implementation Patterns

Core Workflows

Basic Alerts:

// Simple message
SlackAlert::message("Deployment started at " . now()->format('H:i'));

// With context (e.g., user ID, action)
SlackAlert::message("Failed login attempt for user {$user->email}", [
    'user_id' => $user->id,
    'ip' => request()->ip(),
]);

Channel-Specific Alerts:

// Send to a specific channel
SlackAlert::channel('alerts')->message("High CPU usage detected!");

// Default channel (configured in config)
SlackAlert::message("Weekly report generated.");

Async with Queues: The package uses Laravel queues by default. Ensure your queue worker is running:
```
php artisan queue:work
```

Customizing Messages: Use the format() method to override default formatting:

SlackAlert::format(function ($message, $context) {
    return "🚨 *Alert*: {$message}\n*Context*: " . json_encode($context);
})->message("Database backup failed");

Event-Based Alerts: Listen to Laravel events and trigger alerts:

use Illuminate\Auth\Events\Registered;

Registered::listen(function ($event) {
    SlackAlert::message("New user registered: {$event->user->email}");
});

Batch Processing: Send multiple alerts in a loop (e.g., for bulk actions):

foreach ($failedJobs as $job) {
    SlackAlert::message("Job {$job->id} failed: {$job->exception}");
}

Integration Tips

Logging: Combine with Laravel’s logging to correlate alerts with logs:

Log::error("Payment failed for user {$user->id}", ['user' => $user]);
SlackAlert::message("Payment failed for {$user->email}");

Environment Awareness: Use different channels for local vs. production:

$channel = config('slack-alerts.channels.default') === 'general'
    ? 'dev-alerts'
    : 'production-alerts';
SlackAlert::channel($channel)->message("Environment: " . app()->environment());

Rate Limiting: Avoid spamming Slack by throttling alerts (e.g., using throttle middleware or a decorator).

Gotchas and Tips

Pitfalls

Webhook Validation:
- Slack webhooks must be HTTPS. HTTP webhooks will fail silently.
- Test the webhook URL using Slack’s incoming webhook tester.

Queue Failures:

If Slack is down, the job will retry (configurable in config/slack-alerts.php). Monitor failed jobs:
```
php artisan queue:failed
```

To handle persistent failures, extend the job:

use Spatie\SlackAlerts\Jobs\SendSlackAlert;

class CustomSendSlackAlert extends SendSlackAlert {
    public function failed(Throwable $exception) {
        Log::error("Slack alert failed: " . $exception->getMessage());
        // Send fallback notification (e.g., email)
    }
}

Message Formatting:
- Slack has message formatting limits. Long messages may truncate.
- Use SlackAlert::format() to sanitize or truncate messages:
```
SlackAlert::format(fn ($msg) => Str::limit($msg, 200))->message($longMessage);
```
Channel Mismatches:
- Ensure the channel name in SlackAlert::channel() matches exactly (including case) with Slack’s channel name or ID.
- Use Slack’s API to fetch channel IDs if unsure:
```
curl -X GET -H "Authorization: Bearer YOUR_TOKEN" "https://slack.com/api/conversations.list"
```
Rate Limits:
- Slack imposes rate limits. Exceeding limits may cause temporary bans.
- Monitor your usage in Slack’s API dashboard.

Debugging

Check Job Execution:
- Temporarily disable queue retries to debug:
```
'max_retries' => 0, // in config/slack-alerts.php
```
- Use queue:listen for real-time feedback:
```
php artisan queue:listen
```

Log Webhook Responses:

Extend the job to log responses:

use Spatie\SlackAlerts\Jobs\SendSlackAlert;

class DebugSendSlackAlert extends SendSlackAlert {
    protected function sendToSlack($message) {
        $response = Http::post(config('slack-alerts.webhook_url'), ['text' => $message]);
        Log::debug('Slack response:', ['status' => $response->status(), 'body' => $response->body()]);
        return $response->successful();
    }
}

Test Locally:
- Use ngrok to expose a local Slack webhook for testing:
```
ngrok http 8000
```
- Configure .env to point to your ngrok URL:
```
SLACK_WEBHOOK_URL=https://your-ngrok-url.ngrok.io/slack-webhook
```

Extension Points

Custom Job: Override the default job to add logic (e.g., logging, fallback notifications):
```
// config/slack-alerts.php
'job' => \App\Jobs\CustomSlackAlertJob::class;
```
Dynamic Webhook URLs: Use a closure to fetch the webhook URL dynamically (e.g., from a service or cache):
```
SlackAlert::setWebhookUrl(fn () => Cache::get('slack_webhook_url'));
```

Attachments/Blocks: Leverage Slack’s message attachments or blocks:

SlackAlert::message("Deployment failed!", [
    'attachments' => [
        [
            'title' => 'Error Details',
            'text' => 'See logs at: ' . route('logs'),
            'color' => '#ff0000',
        ],
    ],
]);

Environment-Specific Config: Use Laravel’s config() helper to switch behavior:

$webhook = config('slack-alerts.webhook_url.' . app()->environment());
SlackAlert::setWebhookUrl($webhook);

Mocking for Tests: Use Laravel’s HTTP mocking to test alerts without hitting Slack:

Http::fake([
    config('slack-alerts.webhook_url') => Http::response(['ok' => true], 200),
]);

SlackAlert::message("Test alert");

Laravel Slack Alerts Laravel Package