فصل ۲: نصب و راه‌اندازی اولیه¶

در این فصل، مراحل نصب و راه‌اندازی اولیه Laravel Reverb در یک پروژه لاراول نسخه ۱۲ را بررسی می‌کنیم. هدف این است که بتوانید سرور Reverb را نصب کرده، تنظیمات اولیه را انجام دهید، و اتصال WebSocket را با یک ابزار ساده تست کنید. این فصل بر پایه مستندات رسمی لاراول ۱۲.x و بهترین شیوه‌های توسعه تنظیم شده است.

نصب Reverb با Artisan Commands¶

Laravel Reverb به‌عنوان یک پکیج رسمی لاراول ارائه شده و نصب آن از طریق Composer و دستورات Artisan بسیار ساده است. مراحل زیر را دنبال کنید:

1. نصب پکیج Reverb:

ابتدا مطمئن شوید که یک پروژه لاراول نسخه ۱۲ دارید. اگر پروژه‌ای ندارید، با دستور زیر یک پروژه جدید بسازید:

composer create-project laravel/laravel reverb-project
cd reverb-project

1. نصب پکیج broadcasting و Reverb:

برای فعال کردن سیستم broadcasting و نصب Reverb، از دستورات زیر استفاده کنید:

composer require laravel/reverb
php artisan install:broadcasting
php artisan reverb:install

• دستور install:broadcasting تنظیمات اولیه سیستم broadcasting لاراول را در پروژه شما اعمال می‌کند.

• دستور reverb:install فایل‌های تنظیمات Reverb (مانند config/reverb.php) و به‌روزرسانی‌های لازم در فایل‌های پروژه (مانند .env) را اضافه می‌کند.

• بررسی نصب:

پس از اجرای دستورات بالا، فایل config/reverb.php ایجاد می‌شود که شامل تنظیمات پیش‌فرض Reverb است. همچنین، فایل .env شما با متغیرهای مربوط به Reverb به‌روزرسانی می‌شود.

تنظیمات اولیه فایل .env¶

فایل .env برای پیکربندی اتصال به سرور Reverb و احراز هویت کلاینت‌ها استفاده می‌شود. پس از اجرای reverb:install، متغیرهای زیر به فایل .env اضافه می‌شوند. این مقادیر را بررسی و در صورت نیاز ویرایش کنید:

BROADCAST_CONNECTION=reverb
REVERB_APP_ID=my-reverb-app
REVERB_APP_KEY=your-app-key
REVERB_APP_SECRET=your-app-secret
REVERB_HOST=localhost
REVERB_PORT=8080
REVERB_SCHEME=http

توضیح متغیرها:¶

• BROADCAST_CONNECTION=reverb: مشخص می‌کند که Reverb به‌عنوان درایور broadcasting استفاده شود.
• REVERB_APP_ID: شناسه منحصربه‌فرد برنامه شما. می‌توانید آن را تغییر دهید، اما باید با تنظیمات کلاینت (مانند Laravel Echo) همخوانی داشته باشد.
• REVERB_APP_KEY و REVERB_APP_SECRET: برای احراز هویت اتصالات WebSocket استفاده می‌شوند. این مقادیر را امن نگه دارید و در محیط تولید از مقادیر تصادفی و پیچیده استفاده کنید.
• REVERB_HOST و REVERB_PORT: آدرس و پورت سرور Reverb. در محیط محلی، معمولاً localhost:8080 است.
• REVERB_SCHEME: پروتکل اتصال (http یا https). در محیط تولید، از https برای امنیت بیشتر استفاده کنید.

نکته: اگر چندین اپلیکیشن از یک سرور Reverb استفاده می‌کنند، باید REVERB_APP_ID منحصربه‌فرد برای هر اپلیکیشن تنظیم شود.

راه‌اندازی سرور Reverb¶

برای اجرای سرور Reverb، از دستور زیر استفاده کنید:

php artisan reverb:start

این دستور سرور WebSocket را روی localhost:8080 (یا پورت مشخص‌شده در .env) راه‌اندازی می‌کند. خروجی مشابه زیر را مشاهده خواهید کرد:

Starting Laravel Reverb...
Server running on [http://localhost:8080].
Press Ctrl+C to stop the server

گزینه‌های اضافی:¶

• حالت دیباگ: برای مشاهده لاگ‌های دقیق‌تر، از گزینه --debug استفاده کنید:

php artisan reverb:start --debug

• مشخص کردن هاست و پورت: اگر نیاز به تغییر هاست یا پورت دارید، می‌توانید از گزینه‌های --host و --port استفاده کنید:

php artisan reverb:start --host=127.0.0.1 --port=9000

نکته: در محیط توسعه، مطمئن شوید که پورت انتخاب‌شده (مثلاً 8080) توسط برنامه دیگری اشغال نشده است.

تست اولیه اتصال با ابزارهای ساده¶

برای اطمینان از کارکرد صحیح سرور Reverb، می‌توانید اتصال WebSocket را با یک ابزار ساده مانند wscat یا یک کلاینت WebSocket در مرورگر تست کنید.

مرحله ۱: نصب ابزار wscat¶

ابزار wscat یک کلاینت خط فرمان برای تست WebSocket است. آن را با npm نصب کنید:

npm install -g wscat

مرحله ۲: اتصال به سرور Reverb¶

سرور Reverb را اجرا کنید (php artisan reverb:start) و در ترمینال دیگری، دستور زیر را اجرا کنید:

wscat -c ws://localhost:8080/app/your-app-key?protocol=7&client=js
# Example
wscat -c ws://127.0.0.1:8484/app/cpcjylkqykmpqjnhuj4s

• ws://localhost:8080: آدرس سرور Reverb (اگر از https استفاده می‌کنید، از wss:// استفاده کنید).
• /app/your-app-key: endpoint استاندارد Reverb که از REVERB_APP_KEY در .env استفاده می‌کند.
• protocol=7&client=js: پارامترهای موردنیاز برای سازگاری با پروتکل WebSocket.

اگر اتصال موفق باشد، خروجی زیر را در ترمینال خواهید دید:

Connected (press CTRL+C to quit)

مرحله ۳: ارسال پیام تستی¶

برای تست ارسال پیام، یک event ساده ایجاد می‌کنیم و آن را از طریق Reverb broadcast می‌کنیم.

1. ایجاد یک Event: یک event جدید بسازید:

php artisan make:event TestMessage

فایل app/Events/TestMessage.php را به صورت زیر ویرایش کنید:

<?php

namespace App\Events;

use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class TestMessage implements ShouldBroadcast
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public $message;

    public function __construct($message)
    {
        $this->message = $message;
    }

    public function broadcastOn()
    {
        return new Channel('test-channel');
    }

    public function broadcastAs()
    {
        return 'test.message';
    }
}

1. ایجاد Route برای ارسال پیام:

فایل routes/web.php را به‌روزرسانی کنید:

<?php

use App\Events\TestMessage;
use Illuminate\Support\Facades\Route;

Route::get('/send-test', function () {
    event(new TestMessage('Test message from Reverb!'));
    return 'Test message sent!';
});

1. اتصال به کانال با wscat:

در wscat، به کانال عمومی متصل شوید:

wscat -c ws://localhost:8080/app/your-app-key?protocol=7&client=js

سپس پیام زیر را برای subscription به کانال ارسال کنید:

{"command":"subscribe","identifier":"{\"channel\":\"test-channel\"}"}

1. ارسال پیام و بررسی: مرورگر را باز کنید و به آدرس http://localhost:8000/send-test بروید. در ترمینال wscat، باید پیام زیر را دریافت کنید:

{"type":"message","event":"test.message","data":{"message":"Test message from Reverb!"}}

تست با مرورگر¶

برای تست در مرورگر، می‌توانید یک کلاینت ساده JavaScript بنویسید:

<!DOCTYPE html>
<html>
<head>
    <title>Reverb Test</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
</head>
<body>
    <h1>Test Laravel Reverb</h1>
    <button onclick="sendTestMessage()">Send Test Message</button>
    <p id="messages"></p>

    <script>
        const ws = new WebSocket('ws://localhost:8080/app/your-app-key?protocol=7&client=js');

        ws.onopen = () => {
            ws.send(JSON.stringify({
                command: 'subscribe',
                identifier: JSON.stringify({ channel: 'test-channel' })
            }));
        };

        ws.onmessage = (event) => {
            const data = JSON.parse(event.data);
            if (data.type === 'message') {
                $('#messages').append(`<p>${data.data.message}</p>`);
            }
        };

        function sendTestMessage() {
            $.get('/send-test');
        }
    </script>
</body>
</html>

1. فایل بالا را در resources/views/welcome.blade.php قرار دهید.
2. سرور لاراول را اجرا کنید: php artisan serve
3. به http://localhost:8000 بروید، دکمه را کلیک کنید، و پیام را در صفحه ببینید.

نکات و بهترین شیوه‌ها¶

• امنیت: در محیط تولید، REVERB_APP_KEY و REVERB_APP_SECRET را با مقادیر تصادفی و امن جایگزین کنید (مثلاً با php artisan key:generate).
• فایروال: مطمئن شوید که پورت 8080 (یا پورت انتخاب‌شده) در فایروال باز است.
• ابزارهای تست: علاوه بر wscat، می‌توانید از افزونه‌های مرورگر مانند "Simple WebSocket Client" برای تست استفاده کنید.

تمرین پیشنهادی¶

• یک فرم ساده به صفحه welcome.blade.php اضافه کنید تا کاربران بتوانند پیام‌های سفارشی ارسال کنند و در کانال عمومی نمایش داده شوند.
• سرور Reverb را با گزینه --debug اجرا کنید و لاگ‌های اتصال را بررسی کنید.

منابع¶

• مستندات رسمی لاراول: laravel.com/docs/12.x/reverb
• مستندات WebSocket: developer.mozilla.org/en-US/docs/Web/API/WebSocket

در فصل بعدی، به پیکربندی پیشرفته‌تر Reverb و مدیریت چندین اپلیکیشن خواهیم پرداخت.