إتقان الوقت الفعلي مع Laravel Echo: دليل تعليمي شامل

أصبحت ميزات الوقت الفعلي جزءًا لا غنى عنه في تطبيقات الويب الحديثة، حيث تعزز تجربة المستخدم من خلال التحديثات الفورية والإشعارات والعناصر التفاعلية. Laravel، بقدراته القوية على البث، يجعل دمج هذه الميزات أسهل من أي وقت مضى. في قلب نظام الوقت الفعلي في Laravel توجد مكتبة Laravel Echo، وهي مكتبة JavaScript قوية تجعل الاشتراك في القنوات والاستماع إلى الأحداث أمرًا سهلاً.

سيرشدك هذا البرنامج التعليمي خطوة بخطوة خلال إعداد Laravel Echo وتكوين تطبيق Laravel الخاص بك للبث، وتنفيذ وظائف الوقت الفعلي.

ما هو Laravel Echo؟ #

Laravel Echo هي مكتبة JavaScript تعمل على تبسيط عملية دمج WebSockets في تطبيقات Laravel الخاصة بك. توفر واجهة برمجة تطبيقات نظيفة ومعبرة للاستماع إلى الأحداث التي يبثها تطبيق Laravel الخاص بك عبر خادم WebSocket (مثل Pusher أو Ably أو إعداد Redis/Socket.io مخصص).

لماذا تستخدم Laravel Echo؟

• تبسيط تفاعل WebSocket: لا حاجة لإدارة اتصالات WebSocket الأولية.
• التكامل مع Laravel Broadcasting: يعمل بسلاسة مع نظام بث الأحداث المدمج في Laravel.
• المصادقة: يتعامل مع مصادقة القنوات الخاصة والوجودية تلقائيًا.
• المرونة: يدعم العديد من برامج تشغيل البث.
• واجهة برمجة تطبيقات موحدة: توفر واجهة برمجة تطبيقات متسقة لخدمات WebSocket الخلفية المختلفة.

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

قبل أن نبدأ، تأكد من توفر ما يلي:

• مشروع Laravel 10+ جديد.
• Composer مثبت عالميًا.
• Node.js و NPM (أو Yarn) مثبتان على نظامك.
• فهم أساسي لأحداث وقوائم انتظار Laravel.

الخطوة 1: إعداد الواجهة الخلفية - تكوين بث Laravel #

يعمل Laravel Echo جنبًا إلى جنب مع نظام البث في Laravel. أولاً، دعنا نكوّن الواجهة الخلفية لتطبيقك.

1.1 تمكين BroadcastServiceProvider #

افتح config/app.php وأزل التعليق عن سطر App\Providers\BroadcastServiceProvider::class:

'providers' => [
    // ...
    App\Providers\BroadcastServiceProvider::class,
],

1.2 تكوين برنامج تشغيل البث #

يدعم Laravel العديد من برامج تشغيل البث خارج الصندوق. سنستخدم Pusher كمثال نظرًا لسهولة إعداده.

قم بتحديث ملف .env الخاص بك:

BROADCAST_DRIVER=pusher

PUSHER_APP_ID=YOUR_PUSHER_APP_ID
PUSHER_APP_KEY=YOUR_PUSHER_APP_KEY
PUSHER_APP_SECRET=YOUR_PUSHER_APP_SECRET
PUSHER_HOST=
PUSHER_PORT=443
PUSHER_SCHEME=https
PUSHER_APP_CLUSTER=YOUR_PUSHER_APP_CLUSTER

MIX_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
MIX_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"

استبدل YOUR_PUSHER_APP_ID و YOUR_PUSHER_APP_KEY و YOUR_PUSHER_APP_SECRET و YOUR_PUSHER_APP_CLUSTER ببيانات اعتماد تطبيق Pusher الفعلية الخاصة بك. إذا لم يكن لديك حساب Pusher، فقم بالتسجيل في pusher.com.

1.3 تثبيت Pusher PHP SDK #

قم بتثبيت Pusher PHP SDK عبر Composer:

composer require pusher/pusher-php-server

الخطوة 2: إنشاء وبث حدث #

الآن، دعنا ننشئ حدثًا سيبثه تطبيق Laravel الخاص بنا.

2.1 إنشاء الحدث #

php artisan make:event NewMessage

سيؤدي هذا إلى إنشاء ملف app/Events/NewMessage.php.

2.2 تطبيق ShouldBroadcast #

افتح app/Events/NewMessage.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 NewMessage implements ShouldBroadcast
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public $message;
    public $user;

    /**
     * إنشاء مثيل حدث جديد.
     *
     * @return void
     */
    public function __construct($message, $user)
    {
        $this->message = $message;
        $this->user = $user;
    }

    /**
     * الحصول على القنوات التي يجب أن يبث عليها الحدث.
     *
     * @return array<int, \Illuminate\Broadcasting\Channel>
     */
    public function broadcastOn(): array
    {
        // البث إلى قناة عامة تسمى 'chat'
        return [new Channel('chat')];
    }

    /**
     * اسم بث الحدث.
     *
     * @return string
     */
    public function broadcastAs(): string
    {
        return 'message.new';
    }

    /**
     * الحصول على البيانات التي سيتم بثها.
     *
     * @return array
     */
    public function broadcastWith(): array
    {
        return [
            'message' => $this->message,
            'user' => $this->user,
            'time' => now()->toDateTimeString(),
        ];
    }
}

• ShouldBroadcast: تخبر هذه الواجهة Laravel أن هذا الحدث يجب أن يتم بثه.
• broadcastOn(): تحدد القناة (القنوات) التي سيتم بث الحدث عليها. هنا، نستخدم قناة عامة تسمى chat.
• broadcastAs(): تحدد الاسم المخصص للحدث المبثوث، والذي يكون افتراضيًا هو اسم فئة الحدث. غالبًا ما يكون من الأوضح تعريف اسم مخصص.
• broadcastWith(): (اختياري) تخصيص الحمولة التي يتم بثها مع الحدث.

2.3 إرسال الحدث #

يمكنك إرسال هذا الحدث من أي مكان في تطبيق Laravel الخاص بك، على سبيل المثال، من وحدة تحكم (Controller):

<?php

namespace App\Http\Controllers;

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

class ChatController extends Controller
{
    public function sendMessage(Request $request)
    {
        $message = $request->input('message');
        $user = auth()->user()->name ?? 'Guest'; // مثال لمستخدم

        event(new NewMessage($message, $user));

        return response()->json(['status' => 'تم إرسال الرسالة!']);
    }
}

تأكد من تحديد مسار (route) لطريقة وحدة التحكم هذه.

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

الآن، دعنا نكوّن جانب العميل للاستماع إلى هذه الأحداث.

3.1 تثبيت Laravel Echo و Pusher JS #

استخدم NPM (أو Yarn) لتثبيت الحزم الضرورية:

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

3.2 تكوين Echo في bootstrap.js (أو ما شابه) #

غالبًا ما تأتي تطبيقات Laravel بملف resources/js/bootstrap.js لتكوين JavaScript العام. افتح هذا الملف وأضف/عدّل تكوين Echo:

import Echo from 'laravel-echo';

import Pusher from 'pusher-js';
window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'pusher',
    key: import.meta.env.VITE_PUSHER_APP_KEY, // لـ Vite
    // key: process.env.MIX_PUSHER_APP_KEY, // لـ Laravel Mix
    cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER ?? 'mt1', // لـ Vite
    // cluster: process.env.MIX_PUSHER_APP_CLUSTER ?? 'mt1', // لـ Laravel Mix
    forceTLS: true
});

ملاحظة حول import.meta.env مقابل process.env:

• إذا كنت تستخدم Vite (افتراضي Laravel 9+)، فاستخدم import.meta.env.VITE_... للمتغيرات البيئية.
• إذا كنت تستخدم Laravel Mix (إصدارات Laravel الأقدم)، فاستخدم process.env.MIX_....

3.3 تجميع الأصول الخاصة بك #

بعد تعديل bootstrap.js، تحتاج إلى تجميع أصولك:

npm run dev
# أو للإنتاج
npm run build

الخطوة 4: الاستماع إلى الأحداث #

مع تكوين Echo، يمكنك الآن الاستماع إلى الأحداث من جانب العميل.

4.1 الاستماع إلى القنوات العامة #

القنوات العامة مفتوحة لأي شخص يتصل بخادم البث الخاص بك. يبث حدث NewMessage الخاص بنا إلى قناة chat، وهي قناة عامة افتراضيًا.

يمكنك الاستماع إليها بهذه الطريقة في JavaScript الخاص بك (على سبيل المثال، في مكون Vue، ملف JS مخصص، أو حتى داخل وسم <script> في ملف Blade الخاص بك):

// تأكد من أن Echo متاح (على سبيل المثال، بعد تحميل المستند أو في خطاف mounted لإطار عمل)
window.Echo.channel('chat')
    .listen('.message.new', (e) => { // استخدم . لاسم broadcastAs المخصص
        console.log('تم استلام رسالة جديدة:', e.message, 'من', e.user, 'في', e.time);
        // قم بتحديث واجهة المستخدم الخاصة بك هنا، على سبيل المثال، قم بإضافة الرسالة إلى مربع الدردشة
        alert(`رسالة جديدة من ${e.user}: ${e.message}`);
    });

console.log('جارٍ الاستماع للرسائل الجديدة على قناة الدردشة...');

لاحظ أننا نستمع إلى .message.new. إذا لم تحدد broadcastAs()، فستستمع مباشرة إلى اسم فئة الحدث، على سبيل المثال، .NewMessage.

4.2 الاستماع إلى القنوات الخاصة #

تتطلب القنوات الخاصة مصادقة. فقط المستخدمون المصرح لهم بالاستماع إلى قناة معينة يمكنهم تلقي الأحداث عليها. يستخدم هذا عادةً للإشعارات الخاصة بالمستخدم أو الدردشات الجماعية.

4.2.1 تعريف ترخيص القناة الخاصة

افتح routes/channels.php. هذا الملف هو المكان الذي تحدد فيه منطق ترخيص القناة الخاص بك. يتضمن افتراضيًا مثالاً:

<?php

use Illuminate\Support\Facades\Broadcast;

Broadcast::channel('App.Models.User.{id}', function ($user, $id) {
    return (int) $user->id === (int) $id;
});

// مثال: قناة خاصة لإشعارات مستخدم معين
Broadcast::channel('user.{id}', function ($user, $id) {
    return (int) $user->id === (int) $id;
});

// مثال: قناة خاصة لمحادثة معينة
// Broadcast::channel('conversation.{id}', function ($user, $id) {
//     // تحقق مما إذا كان المستخدم مشاركًا في المحادثة
//     return $user->conversations->contains($id);
// });

بالنسبة لقناة خاصة user.{id}، سيتم تنفيذ الدالة عند محاولة Echo الاشتراك في تلك القناة. إذا أعادت الدالة true، يكون المستخدم مصرحًا له؛ وإلا، يتم رفض الوصول. يتعامل نظام البث في Laravel تلقائيًا مع نقطة نهاية المصادقة /broadcasting/auth.

4.2.2 البث إلى قناة خاصة

قم بتعديل طريقة broadcastOn() في الحدث الخاص بك لإرجاع مثيل PrivateChannel:

// app/Events/NewMessage.php
// ...
use Illuminate\Broadcasting\PrivateChannel;

class NewMessage implements ShouldBroadcast
{
    // ...

    public function broadcastOn(): array
    {
        // البث إلى قناة خاصة خاصة بمستخدم
        return [new PrivateChannel('user.' . $this->user->id)];
    }
}

4.2.3 الاستماع إلى قناة خاصة

على جانب العميل، استخدم Echo.private():

// بافتراض أن لديك مستخدمًا مصادقًا بمعرف
const userId = YOUR_AUTHENTICATED_USER_ID;

window.Echo.private(`user.${userId}`)
    .listen('.message.new', (e) => {
        console.log('تم استلام رسالة خاصة:', e.message, 'من', e.user);
        alert(`رسالة خاصة جديدة لك من ${e.user}: ${e.message}`);
    })
    .error((error) => {
        console.error('خطأ Pusher:', error);
    });

console.log(`جارٍ الاستماع للرسائل الخاصة على قناة user.${userId}...`);

4.3 الاستماع إلى قنوات الوجود (Presence Channels) #

قنوات الوجود هي نوع من القنوات الخاصة التي تخبرك تلقائيًا بمن هو مشترك حاليًا في القناة. هذا مفيد لميزات مثل قوائم