Notify Server Client (Laravel)

پکیج لاراول برای اتصال به Notification Server (ارسال اعلان از طریق ربات‌های Bale/Telegram).

نصب

سپس:

composer require webazin/notify-server-client
php artisan vendor:publish --tag=notify-server-config

تنظیمات (.env)

NOTIFY_SERVER_URL=https://notify.example.com
NOTIFY_SERVER_TOKEN=1|abcdef1234567890abcdef1234567890abcdef
NOTIFY_SERVER_TIMEOUT=10
NOTIFY_SERVER_RETRY_TIMES=2
NOTIFY_SERVER_RETRY_SLEEP=200
NOTIFY_SERVER_THROW_ON_FAILURE=true

استفاده مستقیم (Facade)

use Webazin\NotifyServer\Facades\NotifyServer;

// ارسال اعلان
$result = NotifyServer::send(
    title: 'سفارش شما ثبت شد',
    message: 'سفارش شماره ۱۰۲۳ با موفقیت ثبت شد.',
    type: 'success',
    payload: ['order_id' => 1023, 'amount' => 250000],
);
// $result['notification_id']

// تولید کد اتصال برای کاربر جدید
$code = NotifyServer::generateConnectionCode();
// $code['code'], $code['expires_at']

یا با dependency injection:

use Webazin\NotifyServer\NotifyServerClient;

class OrderController
{
    public function store(NotifyServerClient $notify)
    {
        // ...
        $notify->send('سفارش ثبت شد', 'سفارش شما با موفقیت ثبت شد.', 'success');
    }
}

استفاده به‌صورت Notification Channel لاراول (پیشنهادی)

با این روش می‌توانید از سیستم استاندارد Notification لاراول استفاده کنید (صف‌بندی خودکار، ShouldQueue و غیره).

۱. ساخت کلاس Notification

<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;
use Webazin\NotifyServer\Notifications\NotifyServerMessage;

class OrderCreated extends Notification implements ShouldQueue
{
    use Queueable;

    public function __construct(protected int $orderId, protected int $amount)
    {
    }

    public function via(object $notifiable): array
    {
        return ['notify-server'];
    }

    public function toNotifyServer(object $notifiable): NotifyServerMessage
    {
        return NotifyServerMessage::create(
            title: 'سفارش شما ثبت شد',
            message: "سفارش شماره {$this->orderId} با موفقیت ثبت شد."
        )
            ->success()
            ->payload([
                'order_id' => $this->orderId,
                'amount' => $this->amount,
            ]);
    }
}

۲. ارسال

use App\Notifications\OrderCreated;
use Illuminate\Support\Facades\Notification;

Notification::route('notify-server', null)
    ->notify(new OrderCreated($order->id, $order->amount));

// یا روی یک مدل Notifiable (User و غیره) که trait Notifiable دارد:
$user->notify(new OrderCreated($order->id, $order->amount));

توجه: چون سرور اعلان بر اساس Client (توکن) عمل می‌کند نه شناسه‌ی کاربر، معمولاً نیازی به routeNotificationForNotifyServer نیست؛ خود سرور برای همه‌ی Chat‌های فعال Client ارسال می‌کند.

جریان اتصال کاربر

use Webazin\NotifyServer\Facades\NotifyServer;

$connection = NotifyServer::generateConnectionCode();

// نمایش $connection['code'] به کاربر و درخواست ارسال آن به ربات Bale/Telegram
// کد ۵ دقیقه اعتبار دارد

مدیریت خطا

اگر NOTIFY_SERVER_THROW_ON_FAILURE=true باشد (پیش‌فرض)، در صورت بروز خطای HTTP یا خطای اعتبارسنجی، اکسپشن Webazin\NotifyServer\Exceptions\NotifyServerException پرتاب می‌شود:

use Webazin\NotifyServer\Exceptions\NotifyServerException;

try {
    NotifyServer::send('عنوان', 'متن اعلان');
} catch (NotifyServerException $e) {
    logger()->error('ارسال اعلان ناموفق بود', [
        'status' => $e->status(),
        'message' => $e->getMessage(),
        'errors' => $e->errors(),
    ]);
}

اگر مقدار را false بگذارید، متدها هیچ اکسپشنی پرتاب نمی‌کنند و پاسخ خام JSON سرور (شامل message/errors در صورت خطا) را برمی‌گردانند.

نکات مهم بر اساس رفتار سرور

• ارسال آسنکرون است؛ send() فقط notification_id برمی‌گرداند و ارسال واقعی توسط Queue Worker سمت سرور انجام می‌شود.
• اگر Client هیچ Chat فعالی نداشته باشد، اعلان در دیتابیس سرور ثبت می‌شود ولی پیامی برای کسی ارسال نمی‌شود (بدون خطا).
• فیلدهای channel و priority سمت API قابل تنظیم نیستند.
• type باید یکی از مقادیر info, success, warning, error باشد (در کلاینت هم اعتبارسنجی می‌شود تا خطای ۴۲۲ زودتر مشخص شود).