Frameworki

Laravel SMS Notifications — natywny kanał powiadomień (krok po kroku)

Tomasz Lewandowski - Lead Developer, SMSIK 11 min czytania

Laravel ma wbudowany system powiadomień (mail, database, broadcast). Dowiedz się, jak dodać własny kanał SMS przez SMSIK — z użyciem NotificationChannel, kolejek i testów.

Laravel ma wbudowany system powiadomień (Illuminate\Notifications). Domyślnie obsługuje kanały: mail, database, broadcast, vonage (SMS), slack. Jeśli używasz SMSIK, a nie Vonage, musisz dodać własny kanał SMS.

W tym artykule pokazujemy, jak to zrobić krok po kroku — z użyciem NotificationChannel, kolejek i testów. To rozwinięcie artykułu Integracja SMS API w Laravel (który pokazuje ręczne wywołanie API).

Kiedy używać Notifications, a kiedy ręcznego API?

Scenariusz Rekomendacja
Powiadomienie do użytkownika (np. „zamówienie wysłane") Notifications — natywny mechanizm
Powiadomienie do wielu kanałów (mail + SMS) Notifications — jeden via()
Wysyłka marketingowa do grupy Ręczne API lub kampania w panelu
Wysyłka z formularza kontaktowego Ręczne API

Krok 1: Konfiguracja klucza API

Dodaj do .env:

SMSIK_API_KEY=sk_live_TWOJ_KLUCZ
SMSIK_API_URL=https://smsik.pl/api/v1

I do config/services.php:

'smsik' => [
    'api_key' => env('SMSIK_API_KEY'),
    'api_url' => env('SMSIK_API_URL', 'https://smsik.pl/api/v1'),
],

Krok 2: Kanał powiadomień SMS

Utwórz app/Notifications/Channels/SmsikChannel.php:

<?php

namespace App\Notifications\Channels;

use Illuminate\Notifications\Notification;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class SmsikChannel
{
    /**
     * Wysyła powiadomienie przez SMSIK API.
     *
     * Oczekuje, że Notification ma metodę toSmsik($notifiable),
     * która zwraca array: ['to_number' => '...', 'message' => '...', 'idempotency_key' => '...'].
     */
    public function send(object $notifiable, Notification $notification): void
    {
        if (!method_exists($notification, 'toSmsik')) {
            throw new \InvalidArgumentException(
                'Notification musi mieć metodę toSmsik().'
            );
        }

        $payload = $notification->toSmsik($notifiable);

        if (empty($payload['to_number']) || empty($payload['message'])) {
            throw new \InvalidArgumentException(
                'toSmsik() musi zwrócić to_number i message.'
            );
        }

        $response = Http::withHeaders([
            'X-API-Key' => config('services.smsik.api_key'),
            'Content-Type' => 'application/json',
        ])
            ->timeout(30)
            ->retry(3, 1000, function ($exception) {
                return $exception instanceof \Illuminate\Http\Client\ConnectionException;
            })
            ->post(config('services.smsik.api_url') . '/sms/send', $payload);

        if ($response->failed()) {
            Log::error('SMSIK notification failed', [
                'status' => $response->status(),
                'body' => $response->body(),
                'notifiable' => $notifiable->id ?? null,
            ]);

            // Rzuć wyjątek, żeby Laravel oznaczył powiadomienie jako nieudane
            throw new \RuntimeException('SMSIK send failed: ' . $response->body());
        }
    }
}

Krok 3: Notification

Utwórz app/Notifications/OrderShipped.php:

<?php

namespace App\Notifications;

use App\Models\Order;
use App\Notifications\Channels\SmsikChannel;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Notifications\Notification;

class OrderShipped extends Notification implements ShouldQueue
{
    use Queueable;

    public function __construct(public Order $order) {}

    /**
     * Kanały: mail + SMS.
     */
    public function via(object $notifiable): array
    {
        return ['mail', SmsikChannel::class];
    }

    /**
     * Treść maila.
     */
    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)
            ->subject("Zamówienie #{$this->order->id} wysłane")
            ->line("Twoje zamówienie zostało wysłane.")
            ->line("Numer śledzenia: {$this->order->tracking_number}");
    }

    /**
     * Treść SMS-a.
     */
    public function toSmsik(object $notifiable): array
    {
        return [
            'to_number' => $notifiable->phone,
            'message' => "Zamowienie #{$this->order->id} wyslane! "
                . "Numer sledzenia: {$this->order->tracking_number}",
            'idempotency_key' => "order-{$this->order->id}-shipped",
        ];
    }
}

Krok 4: Użycie w kodzie

use App\Notifications\OrderShipped;

// W kontrolerze / serwisie:
$order->user->notify(new OrderShipped($order));

Lub do wielu użytkowników:

use Illuminate\Support\Facades\Notification;

Notification::send($users, new OrderShipped($order));

Krok 5: Kolejki

Notification implementuje ShouldQueue — automatycznie trafia do kolejki. Upewnij się, że masz uruchomiony worker:

php artisan queue:work

W produkcji użyj supervisor lub laravel horizon.

Krok 6: Testy

W tests/Feature/OrderShippedTest.php:

<?php

namespace Tests\Feature;

use App\Models\Order;
use App\Models\User;
use App\Notifications\OrderShipped;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Notification;
use Tests\TestCase;

class OrderShippedTest extends TestCase
{
    use RefreshDatabase;

    public function test_order_shipped_sends_sms(): void
    {
        Http::fake([
            'smsik.pl/api/v1/sms/send' => Http::response([
                'id' => 123,
                'status' => 'queued',
                'to_number' => '+48512017029',
                'price_grosze' => 1,
            ], 200),
        ]);

        $user = User::factory()->create(['phone' => '+48512017029']);
        $order = Order::factory()->create(['user_id' => $user->id]);

        $user->notify(new OrderShipped($order));

        Http::assertSent(function ($request) use ($order) {
            return $request->url() === 'https://smsik.pl/api/v1/sms/send'
                && $request->hasHeader('X-API-Key')
                && $request['to_number'] === '+48512017029'
                && str_contains($request['message'], "#{$order->id}")
                && $request['idempotency_key'] === "order-{$order->id}-shipped";
        });
    }

    public function test_sms_not_sent_when_channel_not_selected(): void
    {
        Notification::fake();

        $user = User::factory()->create();
        $order = Order::factory()->create();

        $user->notify(new OrderShipped($order));

        Notification::assertSentTo($user, OrderShipped::class);
    }
}

Krok 7: Obsługa błędów

Jeśli SMSIK zwróci błąd, Notification zostanie oznaczone jako nieudane. Możesz nasłuchiwać zdarzenia:

// W AppServiceProvider::boot()
use Illuminate\Notifications\Events\NotificationFailed;

Event::listen(NotificationFailed::class, function ($event) {
    if ($event->channel === \App\Notifications\Channels\SmsikChannel::class) {
        Log::critical('SMS notification failed permanently', [
            'notifiable' => $event->notifiable->id,
            'notification' => get_class($event->notification),
            'exception' => $event->data['exception']->getMessage(),
        ]);
    }
});

Podsumowanie

  • ✅ Kanał SMS w app/Notifications/Channels/SmsikChannel.php
  • ✅ Notification z metodą toSmsik()
  • ✅ via() zwraca ['mail', SmsikChannel::class]
  • ✅ Kolejki (ShouldQueue) — nie blokuje requestu
  • ✅ Testy — Http::fake()
  • ✅ Obsługa błędów — NotificationFailed

Zarejestruj się bezpłatnie — 5 groszy na start.

Wyprobuj SMSIK bezplatnie

Rejestracja zajmuje 2 minuty. Otrzymasz 5 groszy na start.

Utworz darmowe konto