README

Відправка SMS-сповіщень через turbosms.ua у Laravel.

🇬🇧 Documentation in English

Можливості

• Відправка SMS через TurboSMS API
• Перевизначення відправника для кожного повідомлення
• Відкладена відправка (планування)
• Тестовий режим — імітація без реального надсилання
• Отримання балансу рахунку
• Подія NotificationFailed при помилках

Вимоги

Встановлення

composer require fomvasss/laravel-notification-channel-turbo-sms

Налаштування

Додайте конфігурацію у config/services.php:

'turbosms' => [
    'api_token'       => env('TURBOSMS_API_TOKEN'),
    'sender'          => env('TURBOSMS_SENDER', 'TAXI'),
    'is_test'         => env('TURBOSMS_IS_TEST', false),

    // Необов'язково:
    'timeout'         => env('TURBOSMS_TIMEOUT', 15),
    'connect_timeout' => env('TURBOSMS_CONNECT_TIMEOUT', 10),
],

.env:

TURBOSMS_API_TOKEN=your_api_token_here
TURBOSMS_SENDER=TAXI
TURBOSMS_IS_TEST=false

Безкоштовні тестові відправники: TAXI, AKCIYA, BEAUTY, Best-offer, Best-Shop, BonusShop, IT Alarm, MAGAZIN, Dostavka24, SERVIS TAXI, BRAND

Використання

1. Створіть клас сповіщення

use Illuminate\Notifications\Notification;
use NotificationChannels\TurboSms\TurboSmsChannel;
use NotificationChannels\TurboSms\TurboSmsMessage;

class OrderShipped extends Notification
{
    public function __construct(private Order $order) {}

    public function via(mixed $notifiable): array
    {
        return [TurboSmsChannel::class];
    }

    public function toTurboSms(mixed $notifiable): TurboSmsMessage
    {
        return TurboSmsMessage::create("Ваше замовлення #{$this->order->id} відправлено!")
            ->from('MyShop');  // необов'язково: перевизначити відправника
    }
}

2. Додайте метод маршрутизації до моделі

// app/Models/User.php

public function routeNotificationForTurboSms(): string
{
    return $this->phone; // напр. '380991234567'
}

3. Надішліть сповіщення

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

// або через фасад:
Notification::send($users, new OrderShipped($order));

Методи повідомлення

Приклад:

TurboSmsMessage::create('Привіт!')
    ->from('BRAND')
    ->time(time() + 3600)  // відправити через 1 годину
    ->test(false);

Пряме використання API

Можна використовувати TurboSmsApi напряму через сервіс-контейнер:

Отримати баланс:

$balance = app(\NotificationChannels\TurboSms\TurboSmsApi::class)->getBalance();
// float|null — напр. 123.45

Відправити повідомлення:

use NotificationChannels\TurboSms\TurboSmsApi;
use NotificationChannels\TurboSms\TurboSmsMessage;

$result = app(TurboSmsApi::class)->sendMessage(
    '380991234567',
    TurboSmsMessage::create('Привіт від Laravel!')
);

// Повертає:
// [
//   'success' => true,
//   'result'  => [...],   // дані відповіді API
//   'info'    => 'TurboSMS response status: OK',
// ]

Обробка помилок

При невдалій відправці канал генерує подію Illuminate\Notifications\Events\NotificationFailed.

use Illuminate\Notifications\Events\NotificationFailed;
use Illuminate\Support\Facades\Event;

Event::listen(NotificationFailed::class, function (NotificationFailed $event) {
    // $event->notifiable   — модель отримувача
    // $event->notification — об'єкт сповіщення
    // $event->data['exception'] — виняток
    logger()->error('TurboSMS помилка: ' . $event->data['message']);
});

Підтримка проекту

Якщо пакет вам корисний — підтримайте розробку:

USDT TRC20: THLgp6DxiAtbNHvgnKV56vk1L38UuUagKf

Changelog

Дивіться CHANGELOG.

Безпека

Повідомляйте про вразливості на fomvasss@gmail.com, а не через публічний issue.

Участь у розробці

Дивіться CONTRIBUTING.

Автори

• fomvasss
• Всі учасники

Ліцензія

MIT — дивіться LICENSE.md.