إطلاق العنان للوقت الحقيقي: دليل شامل لـ Laravel Reverb

إطلاق العنان للوقت الحقيقي: دليل شامل لـ Laravel Reverb #

Laravel Reverb هو خادم WebSocket قوي ومباشر لتطبيقات Laravel، مصمم لجعل ميزات الوقت الحقيقي مثل الدردشة المباشرة، الإشعارات، ولوحات التحكم التفاعلية أسهل من أي وقت مضى. تم بناء Reverb على قمة WebSockets، ويوفر حلاً عالي الأداء، قابل للتوسع، ومستضاف ذاتياً، مما يحرر المطورين من الاعتماد فقط على خدمات الطرف الثالث مثل Pusher أو Ably.

في هذا الدليل المفصل، سنتناول إعداد Laravel Reverb في تطبيقك، بث الأحداث، والاستماع إليها على الواجهة الأمامية باستخدام Laravel Echo.

لماذا Laravel Reverb؟ #

قبل Reverb، كانت إمكانيات البث في Laravel تعتمد بشكل أساسي على خدمات خارجية. ورغم فعاليتها، كانت هذه الخدمات غالباً ما تضيف تكاليف إضافية، تعقيدات في الإعداد، واعتمادات خارجية. يغير Reverb هذا من خلال توفير:

• استضافة ذاتية: تحكم كامل في بنية الوقت الحقيقي التحتية الخاصة بك.
• أداء عالٍ: محسن للسرعة والكفاءة، مستفيداً من WebSockets الأصلية.
• قابلية التوسع: مصمم للتعامل مع حجم كبير من الاتصالات والرسائل.
• بساطة: تكامل سلس مع نظام البث الحالي في Laravel.
• فعالية التكلفة: يلغي رسوم الاشتراك المتكررة لخدمات الوقت الحقيقي.

المتطلبات الأساسية #

لمتابعة هذا الدليل، ستحتاج إلى:

• تطبيق Laravel 10.x (أو أحدث) جديد أو موجود.
• PHP 8.2 أو أحدث.
• Composer مثبت.
• Node.js و NPM/Yarn مثبتين.

الخطوة 1: التثبيت والتكوين #

أولاً، لنقم بتثبيت Laravel Reverb عبر Composer:

composer require laravel/reverb

بعد التثبيت، انشر ملف تكوين Reverb:

php artisan reverb:install

سيقوم هذا الأمر بنشر ملف config/reverb.php وتحديث ملف .env الخاص بك بمتغيرات Reverb الأساسية.

الخطوة 2: تكوين متغيرات البيئة #

افتح ملف .env الخاص بك وتأكد من تعيين المتغيرات التالية بشكل صحيح. يقوم Reverb تلقائياً بملء هذه المتغيرات أثناء reverb:install، ولكن من الجيد مراجعتها.

BROADCAST_CONNECTION=reverb

REVERB_APP_ID=your-app-id
REVERB_APP_KEY=your-app-key
REVERB_APP_SECRET=your-app-secret
REVERB_HOST="0.0.0.0" # أو عنوان IP العام الخاص بك إذا كنت تصل من الخارج
REVERB_PORT=8080
REVERB_SCHEME=http # استخدم https إذا كان لديك إعداد SSL لـ Reverb
REVERB_TLS_CERTIFICATE=""
REVERB_TLS_KEY=""
REVERB_TLS_PASSPHRASE=""

• REVERB_APP_ID, REVERB_APP_KEY, REVERB_APP_SECRET: هذه هي بيانات الاعتماد الفريدة التي تم إنشاؤها لتطبيقك.
• REVERB_HOST: 0.0.0.0 يسمح لـ Reverb بالاستماع على جميع واجهات الشبكة المتاحة. للتطوير المحلي، قد يكون 127.0.0.1 أو localhost كافياً. للإنتاج، استخدم عنوان IP العام للخادم أو النطاق.
• REVERB_PORT: المنفذ الذي سيستمع عليه Reverb. 8080 شائع.
• REVERB_SCHEME: اضبطه على https إذا كنت تقدم Reverb عبر SSL (موصى به بشدة للإنتاج). ستحتاج أيضاً إلى تكوين REVERB_TLS_CERTIFICATE و REVERB_TLS_KEY.

الخطوة 3: إعداد الواجهة الأمامية مع Laravel Echo #

على الواجهة الأمامية، يتم استخدام Laravel Echo للاشتراك في القنوات والاستماع للأحداث. ستحتاج إلى laravel-echo و pusher-js (الذي يستخدمه Reverb داخلياً لبروتوكوله من جانب العميل).

npm install laravel-echo pusher-js
# أو
yarn add laravel-echo pusher-js

بعد ذلك، قم بتكوين Laravel Echo في ملف resources/js/bootstrap.js الخاص بك (أو نقطة إدخال مماثلة). تأكد من إزالة التعليق وتعديل كتلة تكوين Echo:

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'reverb', // تم التغيير من 'pusher' إلى 'reverb'
    key: import.meta.env.VITE_REVERB_APP_KEY,
    wsHost: import.meta.env.VITE_REVERB_HOST,
    wsPort: import.meta.env.VITE_REVERB_PORT ?? 8080,
    wssPort: import.meta.env.VITE_REVERB_PORT ?? 8080,
    forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
    enabledTransports: ['ws', 'wss'],
});

ستحتاج أيضاً إلى عرض متغيرات بيئة Reverb للواجهة الأمامية الخاصة بك. قم بتحديث ملف .env الخاص بك مع بادئات VITE_:

VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="${REVERB_HOST}"
VITE_REVERB_PORT="${REVERB_PORT}"
VITE_REVERB_SCHEME="${REVERB_SCHEME}" # مثل http أو https

تذكر تشغيل npm run dev (أو npm run build للإنتاج) لتجميع الأصول الخاصة بك بعد هذه التغييرات.

الخطوة 4: بدء تشغيل خادم Reverb #

مع تكوين كل شيء، يمكنك الآن بدء تشغيل خادم Reverb:

php artisan reverb:start

لبيئات الإنتاج، يجب عليك استخدام مدير عمليات مثل Supervisor للحفاظ على Reverb قيد التشغيل وإعادة تشغيله تلقائياً في حالة تعطل.

الخطوة 5: بث الأحداث من الواجهة الخلفية (Backend) #

لإرسال بيانات الوقت الحقيقي من الواجهة الخلفية لـ Laravel، ستستخدم أحداث قابلة للبث.

إنشاء حدث قابل للبث #

قم بإنشاء حدث جديد:

php artisan make:event MessageSent

افتح app/Events/MessageSent.php وقم بتنفيذ واجهة ShouldBroadcast. حدد البيانات التي تريد بثها والقناة (القنوات) التي يجب إرسالها إليها.

<?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 $username;
    public $message;

    /**
     * Create a new event instance.
     */
    public function __construct(string $username, string $message)
    {
        $this->username = $username;
        $this->message = $message;
    }

    /**
     * Get the channels the event should broadcast on.
     *
     * @return array<int, \Illuminate\Broadcasting\Channel>
     */
    public function broadcastOn(): array
    {
        return [
            new Channel('chat'), // قناة عامة (Public channel)
            // new PrivateChannel('user.'.$this->userId), // قناة خاصة لمستخدمين محددين (Private channel)
        ];
    }

    /**
     * The event's broadcast name.
     *
     * @return string
     */
    public function broadcastAs(): string
    {
        return 'message.sent';
    }

    /**
     * Get the data to broadcast.
     *
     * @return array
     */
    public function broadcastWith(): array
    {
        return [
            'username' => $this->username,
            'message' => $this->message,
            'timestamp' => now()->toDateTimeString(),
        ];
    }
}

• broadcastOn(): يحدد القنوات. Channel للقنوات العامة، PrivateChannel للمستخدمين المصادق عليهم.
• broadcastAs(): يخصص اسم الحدث على الواجهة الأمامية (الافتراضي هو اسم فئة الحدث).
• broadcastWith(): يحدد حمولة البيانات المرسلة مع الحدث.

تشغيل الحدث #

يمكنك تشغيل هذا الحدث من Controller أو خدمة أو أي مكان مناسب:

<?php

namespace App\Http\Controllers;

use App\Events\MessageSent;
use Illuminate\Http\Request;

class ChatController extends Controller
{
    public function sendMessage(Request $request)
    {
        $username = $request->input('username', 'Guest');
        $message = $request->input('message');

        event(new MessageSent($username, $message));

        return response()->json(['status' => 'Message sent!']);
    }
}

تأكد من وجود مسار محدد لطريقة Controller هذه:

// routes/web.php or routes/api.php
Route::post('/send-message', [ChatController::class, 'sendMessage']);

الخطوة 6: الاستماع للأحداث على الواجهة الأمامية (Frontend) #

الآن، لنستمع لحدث message.sent على قناة chat باستخدام Laravel Echo. يمكنك إضافة هذا إلى ملف resources/js/app.js الخاص بك أو مكون Vue/React محدد.

// resources/js/app.js أو في سكربت مكون

// الاستماع لأحداث القناة العامة
window.Echo.channel('chat')
    .listen('.message.sent', (e) => { // لاحظ النقطة الرائدة لـ broadcastAs()
        console.log('New message:', e.username, e.message, e.timestamp);
        // أضف منطقاً لعرض الرسالة في واجهة المستخدم الخاصة بك
        const messagesDiv = document.getElementById('messages');
        if (messagesDiv) {
            const newMessage = document.createElement('p');
            newMessage.textContent = `${e.username} (${e.timestamp}): ${e.message}`;
            messagesDiv.appendChild(newMessage);
        }
    });

// إذا كنت تستخدم قنوات خاصة، تأكد من إعداد middleware المصادقة على الواجهة الخلفية
// واستخدم:
// window.Echo.private('user.1')
//     .listen('MessageSent', (e) => {
//         console.log('Private message for user 1:', e);
//     });

console.log('Listening for chat messages...');

هام: إذا استخدمت broadcastAs() في حدثك، تذكر أن تسبقه بنقطة (.) لاسم الحدث عند الاستماع في الواجهة الأمامية (على سبيل المثال، .message.sent). إذا لم تستخدم broadcastAs()، فاستمع مباشرة إلى اسم الفئة (على سبيل المثال، 'MessageSent').

التكوين المتقدم والتوسع #

يوفر ملف config/reverb.php الخاص بـ Reverb خيارات تكوين متنوعة:

• apps: تحديد تطبيقات متعددة بمفاتيح وأسرار مختلفة.
• pulses: تكوين فحوصات السلامة (health checks) و نبضات القلب (heartbeats).
• webhooks: إرسال webhooks إلى تطبيقك لأحداث مثل الاشتراك/إلغاء الاشتراك في القناة.
• scaling: يدعم Reverb Redis للتوسع الأفقي عبر عدة مثيلات Reverb. هذا أمر بالغ الأهمية لتطبيقات ذات حركة مرور عالية. لتمكينه، تأكد من تثبيت وتكوين Redis، ثم قم بإزالة التعليق عن قسم scaling في reverb.php واضبط enabled على true.

الخلاصة #

يوفر Laravel Reverb حلاً قوياً ومتكاملاً لإضافة إمكانيات الوقت الحقيقي إلى تطبيقات Laravel الخاصة بك. من خلال استضافة خادم WebSocket الخاص بك، تحصل على مزيد من التحكم، وتقليل التكاليف المحتملة، وتبسيط سير عمل التطوير الخاص بك. احتضن Reverb لبناء تجارب مستخدم أكثر ديناميكية وتفاعلية بقوة Laravel!