فصل ۱: مقدمه‌ای بر Laravel Reverb¶

تاریخچه و اهمیت ارتباطات Real-Time در وب مدرن¶

ارتباطات real-time به کاربران امکان می‌دهد تا داده‌ها را به‌صورت آنی دریافت کنند، بدون نیاز به بارگذاری مجدد صفحه. این فناوری در اپلیکیشن‌هایی مانند چت، نوتیفیکیشن‌ها، داشبوردهای تحلیلی، و سیستم‌های همکاری آنلاین (مانند Google Docs) نقش کلیدی دارد. در گذشته، این قابلیت‌ها از طریق تکنیک‌هایی مانند AJAX polling یا long polling پیاده‌سازی می‌شدند که ناکارآمد بودند. با ظهور WebSockets در استاندارد HTML5، توسعه‌دهندگان توانستند ارتباطات دوطرفه و کم‌تأخیر بین سرور و کلاینت ایجاد کنند.

Laravel Reverb، معرفی‌شده در نسخه‌های اخیر لاراول (از جمله نسخه ۱۲)، یک راه‌حل native برای پیاده‌سازی WebSocket در اکوسیستم لاراول است. Reverb از پروتکل WebSocket برای انتقال پیام‌های real-time استفاده می‌کند و با سیستم broadcasting لاراول ادغام شده تا توسعه‌دهندگان بتوانند به‌راحتی برنامه‌های real-time بسازند.

چرا real-time مهم است؟¶

• تجربه کاربری بهتر: کاربران انتظار دارند که داده‌ها (مانند پیام‌های چت یا نوتیفیکیشن‌ها) بدون تأخیر نمایش داده شوند.
• کارایی بالا: WebSocket‌ها برخلاف HTTP polling، اتصال مداوم و کم‌هزینه‌ای را فراهم می‌کنند.
• کاربردهای متنوع: از بازی‌های آنلاین گرفته تا اپلیکیشن‌های مالی و همکاری تیمی.

مقایسه Reverb با ابزارهای مشابه¶

Reverb در مقایسه با ابزارهای دیگر مانند Pusher و Socket.io ویژگی‌های منحصربه‌فردی ارائه می‌دهد:

ویژگی	Laravel Reverb	Pusher	Socket.io
ادغام با لاراول	کاملاً native، با سیستم broadcasting	نیاز به تنظیمات اضافی	نیاز به تنظیمات دستی
زبان سرور	PHP (Laravel)	مستقل از فریم‌ورک	Node.js
مقیاس‌پذیری	پشتیبانی از Redis برای مقیاس افقی	مقیاس‌پذیری ابری قوی	نیاز به تنظیمات پیچیده
هزینه	رایگان (open-source)	مدل اشتراکی (پولی)	رایگان (نیاز به سرور Node.js)
پیچیدگی راه‌اندازی	ساده، با Artisan commands	ساده، اما وابسته به سرویس ابری	پیچیده‌تر، نیاز به دانش Node.js

مزایای Reverb:

• ادغام کامل با لاراول، بدون نیاز به سرویس‌های خارجی.
• استفاده از ابزارهای آشنا مانند Artisan و Laravel Echo.
• قابلیت اجرا روی سرورهای محلی یا ابری بدون هزینه اضافی.

معایب Reverb:

• هنوز در مراحل اولیه توسعه است و ممکن است در مقایسه با Pusher ویژگی‌های کمتری داشته باشد.
• برای پروژه‌های بسیار بزرگ، نیاز به تنظیمات اضافی (مانند Redis) دارد.

ادغام Reverb با سیستم Broadcasting لاراول¶

سیستم broadcasting لاراول امکان ارسال رویدادها (events) به کلاینت‌ها را از طریق کانال‌های عمومی، خصوصی، یا presence فراهم می‌کند. Reverb به‌عنوان یک درایور WebSocket به این سیستم متصل می‌شود و جایگزین درایورهای دیگر مانند Pusher می‌شود. این ادغام به توسعه‌دهندگان اجازه می‌دهد تا با استفاده از همان ساختار event-driven لاراول، پیام‌ها را به‌صورت real-time به کلاینت‌ها ارسال کنند.

اجزای اصلی ادغام:¶

1. Events: با استفاده از ShouldBroadcast interface، رویدادها برای broadcast تعریف می‌شوند.
2. Channels: کانال‌های عمومی (public)، خصوصی (private)، یا presence برای مدیریت دسترسی کاربران.
3. Laravel Echo: کتابخانه جاوااسکریپت برای مدیریت اتصالات WebSocket در سمت کلاینت.
4. Reverb Server: سرور WebSocket که پیام‌ها را بین سرور و کلاینت منتقل می‌کند.

پیش‌نیازها¶

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

• دانش پایه لاراول: آشنایی با مفاهیمی مانند routes، controllers، models، و middleware.
• PHP 8.2 یا بالاتر: لاراول ۱۲ به PHP 8.2+ نیاز دارد.
• Node.js و npm: برای نصب Laravel Echo و مدیریت پکیج‌های جاوااسکریپت.
• Composer: برای نصب پکیج‌های PHP.
• محیط توسعه: سرور محلی (مانند Laravel Herd یا Valet) یا محیط ابری (مانند Laravel Forge).

مثال عملی: ارسال یک پیام ساده با Reverb¶

در این بخش، یک مثال ساده از ارسال پیام real-time با Reverb پیاده‌سازی می‌کنیم. این پروژه شامل یک event است که پیام "Hello, Reverb!" را به یک کانال عمومی ارسال می‌کند و کلاینت آن را دریافت می‌کند. تغییرات بهینه: تمام configها از .env لود می‌شن.

مرحله ۱: نصب لاراول و Reverb¶

1. یک پروژه لاراول جدید بسازید:

composer create-project laravel/laravel laravel-reverb-example
cd laravel-reverb-example/
composer require laravel/reverb
php artisan install:broadcasting

1. فایل .env را به‌روزرسانی کنید (اینجا متغیرهای جدید VITE_ اضافه شدن – فقط مقادیر رو کپی کن و APP_KEY رو با php artisan key:generate --show جایگزین کن):

APP_NAME=Laravel
APP_ENV=local
APP_KEY=base64:your-generated-app-key-here  # با php artisan key:generate --show جایگزین کن
APP_DEBUG=true
APP_URL=http://localhost

# Broadcasting
BROADCAST_CONNECTION=reverb

# Reverb Backend Config
REVERB_APP_ID=my-reverb-app
REVERB_APP_KEY=your-generated-reverb-key-here  # با php artisan key:generate --show جایگزین کن (یا یک کلید ۳۲ کاراکتری رندوم)
REVERB_APP_SECRET=your-generated-reverb-secret-here  # یک secret ۴۴ کاراکتری رندوم (مثل base64)
REVERB_HOST=localhost
REVERB_PORT=8080
REVERB_SCHEME=http

# Reverb Frontend Config (برای Vite/Echo)
VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="${REVERB_HOST}"
VITE_REVERB_PORT="${REVERB_PORT}"
VITE_REVERB_SCHEME="${REVERB_SCHEME}"

نکته: برای REVERB_APP_KEY و SECRET، از دستور php artisan key:generate --show استفاده کن و خروجی رو کپی کن. اگر مشکلی داشتی، می‌تونی از openssl rand -base64 32 برای key و openssl rand -base64 44 برای secret استفاده کنی.

1. نصب Reverb:

php artisan reverb:install

مرحله ۲: ایجاد یک Event¶

یک event برای ارسال پیام ایجاد کنید:

php artisan make:event MessageSent

فایل app/Events/MessageSent.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 MessageSent implements ShouldBroadcast
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public $message;

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

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

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

مرحله ۳: تنظیم Laravel Echo در Frontend¶

1. Laravel Echo رو نصب کن (و pusher-js رو هم اگر نیاز بود، اما برای Reverb اختیاریه):

npm install --save laravel-echo pusher-js

1. فایل resources/js/bootstrap.js رو به این صورت بهینه کن (حالا از .env لود می‌کنه – هاردکد حذف شد):

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';
// window.Pusher = Pusher;  // اگر نیاز به Pusher داشتی، uncomment کن

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'reverb',
    key: import.meta.env.VITE_REVERB_APP_KEY,
    wsHost: import.meta.env.VITE_REVERB_HOST,
    wsPort: import.meta.env.VITE_REVERB_PORT ?? 80,
    wssPort: import.meta.env.VITE_REVERB_PORT ?? 443,
    forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
    enabledTransports: ['ws', 'wss'],
    authEndpoint: '/broadcasting/auth',
});

1. فایل resources/js/app.js رو بدون تغییر نگه دار:

import './bootstrap';

window.Echo.channel('public-channel')
    .listen('.message.sent', (e) => {
        console.log('New message:', e.message);
        alert('New message: ' + e.message);
    });

1. فایل resources/views/welcome.blade.php رو بدون تغییر نگه دار:

<!DOCTYPE html>
<html>
<head>
    <title>Laravel Reverb Example</title>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body>
    <h1>Welcome to Laravel Reverb</h1>
    <p>Open the console to see real-time messages.</p>
</body>
</html>

مرحله ۴: ارسال پیام از Backend¶

فایل routes/web.php رو به این صورت بهینه کن (redirect اضافه شد تا بعد از ارسال به صفحه اصلی برگرده):

<?php

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

Route::get('/', function () {
    return view('welcome');
});

Route::get('/send-message', function () {
    event(new MessageSent('Hello, Reverb!'));
    return redirect('/')->with('status', 'Message sent successfully!');
});

مرحله ۵: اجرای پروژه¶

1. سرور Reverb رو اجرا کن (و queue worker اگر event queueable باشه – در این مثال sync کار می‌کنه، اما برای بهینه‌سازی اضافه کردم):

php artisan reverb:start --debug  # --debug برای لاگ بیشتر
php artisan queue:work --verbose  # اگر event رو queueable کنی، این رو اجرا کن

1. سرور لاراول رو اجرا کن:

php artisan serve

1. فایل‌های جاوااسکریپت رو کامپایل کن (برای dev، از hot reload استفاده کن):

npm run dev  # برای توسعه (hot reload)
# یا npm run build  # برای production

1. به آدرس http://localhost:8000 برو و کنسول مرورگر (F12 > Console) رو باز کن.

2. به آدرس http://localhost:8000/send-message برو. بعد از redirect به صفحه اصلی، در کنسول و alert، پیام "Hello, Reverb!" نمایش داده می‌شه.

نکته عیب‌یابی: - اگر اتصال Echo fail شد، چک کن پورت ۸۰۸۰ باز باشه (firewall) و در کنسول مرورگر خطای WebSocket نباشه. - لاگ Reverb: tail -f storage/logs/laravel.log و کنسول Reverb. - اگر Vite کار نکرد، npm run dev رو در ترمینال جداگانه اجرا کن.

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

• یک فرم ساده به صفحه welcome.blade.php اضافه کنید تا کاربران بتوانند پیام‌های خود را وارد کرده و به کانال عمومی ارسال کنند.
• پیام‌های دریافتی را به‌جای alert، در یک لیست <ul> در صفحه نمایش دهید.

نکات پایانی فصل¶

• Reverb به‌عنوان بخشی از اکوسیستم لاراول، توسعه ارتباطات real-time را ساده‌تر کرده است.
• در فصل‌های بعدی، به مباحثی مانند کانال‌های خصوصی، احراز هویت، و مقیاس‌پذیری خواهیم پرداخت.
• برای اطلاعات بیشتر، به مستندات رسمی لاراول در laravel.com/docs/12.x/reverb مراجعه کنید.