دورة لارافيل إيكو

المقدمة #

لارافيل إيكو هو مكتبة جافاسكريبت تسهّل الاشتراك في القنوات والاستماع إلى الأحداث التي يبثها تطبيقك في لارافيل. تُجرد الإضافة تفاصيل الـ WebSocket الخلفية (Pusher، Socket.io، Laravel WebSockets…) وتوفّر واجهة برمجة تطبيقات نظيفة وسهلة الاستخدام.

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

• مشروع لارافيل 9 أو أحدث
• Composer مثبت
• Node.js و npm (أو Yarn)
• حساب على Pusher أو حزمة Laravel WebSockets مثبتة محلياً

1. تثبيت الحزم المطلوبة #

# جانب الخادم (Laravel)
composer require pusher/pusher-php-server
composer require beyondcode/laravel-websockets --dev   # اختيارية، لاستبدال Pusher ذاتيًا

# جانب العميل (JavaScript)
npm install --save laravel-echo pusher-js   # أو socket.io-client إذا تفضّل Socket.io

2. إعداد البث (Broadcasting) #

عدّل الملف config/broadcasting.php:

'connections' => [
    'pusher' => [
        'driver' => 'pusher',
        'key' => env('PUSHER_APP_KEY'),
        'secret' => env('PUSHER_APP_SECRET'),
        'app_id' => env('PUSHER_APP_ID'),
        'options' => [
            'cluster' => env('PUSHER_APP_CLUSTER'),
            'useTLS' => true,
            // إذا استخدمت Laravel WebSockets ضع المضيف والمنفذ:
            // 'host' => '127.0.0.1',
            // 'port' => 6001,
            // 'encrypted' => true,
        ],
    ],
    // اتصالات أخرى …
];

أضف المتغيّرات المقابلة في ملف .env:

BROADCAST_DRIVER=pusher
PUSHER_APP_ID=your-app-id
PUSHER_APP_KEY=your-key
PUSHER_APP_SECRET=your-secret
PUSHER_APP_CLUSTER=mt1   # أو الكلاستر الخاص بك

إذا كنت تستخدم Laravel WebSockets احتفظ بنفس المفاتيح – الحزمة تحاكي واجهة برمجة تطبيقات Pusher.

3. نشر وتشغيل Laravel WebSockets (اختياري) #

php artisan vendor:publish --provider="BeyondCode\LaravelWebSockets\WebSocketsServiceProvider" --tag="config"
php artisan websockets:serve

سيستمع الخادم على 127.0.0.1:6001 افتراضياً.

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

php artisan make:event NewMessage

حرّر الحدث المولّد (app/Events/NewMessage.php):

use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;

class NewMessage implements ShouldBroadcast
{
    use InteractsWithSockets;

    public $message;
    public $userId;

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

    public function broadcastOn()
    {
        return new PrivateChannel('chat.' . $this->userId);
    }
}

ثم شغّل الحدث من أي مكان في التطبيق:

event(new NewMessage('مرحبًا بالعالم!', auth()->id()));

5. إعداد Echo على الواجهة الأمامية #

أنشئ ملف جافاسكريبت، مثل resources/js/echo.js:

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

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'pusher',
    key: process.env.MIX_PUSHER_APP_KEY,
    cluster: process.env.MIX_PUSHER_APP_CLUSTER,
    wsHost: process.env.MIX_ECHO_HOST || window.location.hostname,
    wsPort: 6001,               // 443 إذا استخدمت TLS
    wssPort: 6001,
    forceTLS: false,            // true إذا كان الموقع HTTPS
    enabledTransports: ['ws', 'wss'],
});

أضف المتغيّرات إلى ملف .env (و webpack.mix.js إذا تستخدم Mix):

MIX_PUSHER_APP_KEY=${PUSHER_APP_KEY}
MIX_PUSHER_APP_CLUSTER=${PUSHER_APP_CLUSTER}
MIX_ECHO_HOST=127.0.0.1   # اختياري، إذا استخدمت WebSockets ذاتيًا

ثم جرّب تجميع الأصول:

npm run dev   # أو npm run prod

6. الاستماع للحدث في المتصفح #

window.Echo.private(`chat.${userId}`)
    .listen('NewMessage', (e) => {
        console.log('رسالة جديدة:', e.message);
        // حدّث واجهة المستخدم هنا
    });

تأكد من أن المستخدم مصادقٌ – Echo يرسل ملفات تعريف الارتباط الخاصة بجلسة لارافيل لتفويض القنوات الخاصة.

7. نصائح لتصحيح الأخطاء #

• شغّل php artisan queue:work إذا كان الحدث يستخدم ShouldBroadcastNow (ليس ضرورياً إذا استخدمنا ShouldBroadcast).
• راقب وحدة التحكم في المتصفح لأية Authentication error – غالبًا ما تكون بسبب عدم تسجيل BroadcastServiceProvider أو عدم تطابق الـ CSRF Token.
• إذا استخدمت WebSockets ذاتيًا، افتح http://localhost:6001 – ستظهر لوحة تحكم (متوفرة مع الحزمة).
• استخدم الأمر php artisan broadcast:channel لاختبار صلاحية القناة.

الخاتمة #

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