إتقان Laravel Echo: بناء تطبيقات الوقت الفعلي بسهولة
كان بناء ميزات الوقت الفعلي مثل الدردشة المباشرة والإشعارات ولوحات المعلومات الديناميكية مهمة معقدة في السابق، وغالبًا ما كانت تتطلب تطبيقات WebSocket معقدة. بفضل Laravel، وتحديداً Laravel Echo، تم تبسيط هذه العملية بشكل كبير. Laravel Echo هي مكتبة JavaScript قوية توفر واجهة برمجة تطبيقات نظيفة وأنيقة للاشتراك في القنوات والاستماع إلى الأحداث التي يبثها تطبيق Laravel الخاص بك.
في هذا الدليل التفصيلي، سنتعمق في Laravel Echo، لتغطية إعدادها، وتكوينها، واستخدامها العملي لإضافة إمكانيات الوقت الفعلي إلى مشاريع Laravel الخاصة بك.
ما هو Laravel Echo؟ #
Laravel Echo هي مكتبة JavaScript من جانب العميل تتكامل بسلاسة مع نظام البث في Laravel. إنها تتيح لك الاشتراك بسهولة في قنوات مختلفة (عامة، خاصة، حضور) والتفاعل مع الأحداث التي تبثها الواجهة الخلفية لتطبيقك. تدعم Echo برامج تشغيل WebSocket الشائعة مثل Pusher وAbly وRedis (عبر laravel-websockets أو Soketi)، مما يجرّد تعقيدات برمجة WebSocket ذات المستوى المنخفض.
المتطلبات الأساسية #
قبل أن نبدأ، تأكد من توفر ما يلي:
- تطبيق Laravel يعمل (يوصى بالإصدار 8.x أو أعلى).
- Node.js و npm/Yarn مثبتان.
- Composer مثبت.
- حساب خدمة بث (على سبيل المثال، Pusher، Ably). لهذا الدليل، سنستخدم Pusher.
الخطوة 1: إعداد الواجهة الخلفية (Laravel Broadcasting) #
أولاً، نحتاج إلى تهيئة تطبيق Laravel الخاص بنا لبث الأحداث.
1. تثبيت Pusher PHP SDK #
قم بتثبيت Pusher PHP SDK عبر Composer:
composer require pusher/pusher-php-server
2. تهيئة برنامج تشغيل البث #
افتح ملف .env وقم بتعيين BROADCAST_DRIVER إلى pusher:
BROADCAST_DRIVER=pusher
PUSHER_APP_ID=YOUR_APP_ID
PUSHER_APP_KEY=YOUR_APP_KEY
PUSHER_APP_SECRET=YOUR_APP_SECRET
PUSHER_APP_CLUSTER=YOUR_APP_CLUSTER
استبدل YOUR_APP_ID وYOUR_APP_KEY وYOUR_APP_SECRET وYOUR_APP_CLUSTER ببيانات اعتماد تطبيق Pusher الفعلية الخاصة بك. يمكنك العثور عليها في لوحة تحكم Pusher الخاصة بك.
3. إلغاء التعليق عن مزود خدمة البث #
افتح config/app.php وقم بإلغاء التعليق عن السطر App\Providers\BroadcastServiceProvider::class:
'providers' => [
// مزودو الخدمة الآخرون...
App\Providers\BroadcastServiceProvider::class,
],
يحتوي هذا المزود على المنطق الضروري لتسجيل مسارات وخدمات البث.
4. تشغيل الهجرات (اختياري، للمصادقة) #
إذا كنت تخطط لاستخدام القنوات الخاصة أو قنوات الحضور (التي تتطلب المصادقة)، فتأكد من أن لديك جدول users ونموذج User، والذي يتم إعداده عادةً بشكل افتراضي في مشاريع Laravel الجديدة. إذا لم يكن كذلك، قم بتشغيل:
php artisan migrate
الخطوة 2: إعداد الواجهة الأمامية (Laravel Echo) #
الآن، دعنا نُعد Laravel Echo في الواجهة الأمامية (JavaScript).
1. تثبيت Laravel Echo و Pusher JS #
قم بتثبيت حزم npm الضرورية:
npm install --save-dev laravel-echo pusher-js
2. تهيئة Echo #
افتح resources/js/bootstrap.js (أو resources/js/app.js إذا كنت تفضل) وأضف الكود التالي لتهيئة Laravel Echo. يتم تحميل هذا الملف عادةً بواسطة تخطيط app.blade.php الخاص بك.
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,
cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER ?? 'mt1',
wsHost: import.meta.env.VITE_PUSHER_HOST ? import.meta.env.VITE_PUSHER_HOST : `ws-${import.meta.env.VITE_PUSHER_APP_CLUSTER}.pusher.com`,
wsPort: import.meta.env.VITE_PUSHER_PORT ?? 80,
wssPort: import.meta.env.VITE_PUSHER_PORT ?? 443,
forceTLS: (import.meta.env.VITE_PUSHER_SCHEME ?? 'https') === 'https',
enabledTransports: ['ws', 'wss'],
});
يقوم هذا الكود بتهيئة Echo لاستخدام Pusher مع بيانات الاعتماد من ملف .env الخاص بك (والتي يكشفها Vite عبر import.meta.env).
3. تجميع الأصول #
قم بتشغيل عملية البناء لتجميع أصول JavaScript:
npm run dev
# أو للإنتاج
npm run build
تأكد من تضمين resources/js/app.js (أو bootstrap.js إذا تم استيراده هناك) في ملف تخطيط Blade الخاص بك:
<head>
<!-- ... -->
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
الخطوة 3: إنشاء وبث الأحداث #
الآن بعد إعداد Echo، دعنا ننشئ حدثًا ونبثه.
1. إنشاء حدث #
قم بإنشاء حدث جديد باستخدام أمر Artisan:
php artisan make:event NewMessage
2. تطبيق ShouldBroadcast
#
افتح app/Events/NewMessage.php واجعله يطبق الواجهة ShouldBroadcast. أيضاً، قم بتعريف طريقة broadcastOn لتحديد القناة (القنوات) التي سيتم بث هذا الحدث عليها.
<?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 $username;
/**
* Create a new event instance.
*
* @return void
*/
public function __construct($message, $username = 'Guest')
{
$this->message = $message;
$this->username = $username;
}
/**
* Get the channels the event should broadcast on.
*
* @return \Illuminate\Broadcasting\Channel|array
*/
public function broadcastOn()
{
return new Channel('chat'); // قناة عامة باسم 'chat'
}
/**
* The event's broadcast name.
*
* @return string
*/
public function broadcastAs()
{
return 'message.new'; // اسم حدث بث مخصص (اختياري)
}
/**
* Get the data to broadcast.
*
* @return array
*/
public function broadcastWith()
{
return [
'message' => $this->message,
'user' => $this->username,
'time' => now()->toDateTimeString()
];
}
}
ShouldBroadcast: تخبر هذه الواجهة Laravel أن هذا الحدث يجب أن يتم بثه.broadcastOn(): تحدد هذه الطريقة القناة (القنوات) التي سيتم بث الحدث عليها. هنا، نستخدمChannelعامة باسمchat.broadcastAs()(اختياري): يسمح لك بتخصيص اسم الحدث من جانب العميل. إذا تم حذفه، فسيتم استخدام اسم الفئة بالكامل (App.Events.NewMessage).broadcastWith()(اختياري): يسمح لك بتحديد البيانات من الحدث التي يجب بثها. إذا تم حذفه، فسيتم بث جميع الخصائص العامة للحدث.
3. إرسال الحدث #
يمكنك إرسال هذا الحدث من أي مكان في تطبيق Laravel الخاص بك (على سبيل المثال، متحكم، خدمة، أو وظيفة):
<?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');
$username = auth()->user() ? auth()->user()->name : 'Guest';
NewMessage::dispatch($message, $username);
return response()->json(['status' => 'تم إرسال الرسالة!']);
}
}
الخطوة 4: الاستماع إلى الأحداث (الواجهة الأمامية) #
الآن، دعنا نكتب كود JavaScript للاستماع إلى هذه الأحداث باستخدام Laravel Echo.
1. القنوات العامة (Public Channels) #
القنوات العامة هي الأبسط. يمكن لأي شخص الاشتراك فيها دون مصادقة.
// في ملف JavaScript الخاص بك (على سبيل المثال، resources/js/app.js أو مكون Vue/React)
Echo.channel('chat')
.listen('message.new', (e) => {
console.log('تم استلام رسالة جديدة:', e.message, 'من', e.user);
// أضف الرسالة إلى واجهة مستخدم الدردشة الخاصة بك
const messagesContainer = document.getElementById('messages');
if (messagesContainer) {
const messageElement = document.createElement('div');
messageElement.textContent = `${e.user} (${e.time}): ${e.message}`;
messagesContainer.appendChild(messageElement);
}
});
console.log('جاري الاستماع لرسائل جديدة على قناة الدردشة...');
هنا، Echo.channel('chat') يشترك في القناة العامة 'chat'، و.listen('message.new', ...) يسجل دالة رد اتصال لحدث message.new (اسم broadcastAs المخصص لدينا).
2. القنوات الخاصة (Private Channels) #
القنوات الخاصة مؤمنة وتتطلب مصادقة. يمكن للمستخدمين المصادق عليهم والمخولين بالاستماع إلى قناة معينة فقط القيام بذلك. هذا مثالي للإشعارات الخاصة بالمستخدم.
أولاً، قم بتعديل الحدث الخاص بك لاستخدام PrivateChannel:
// app/Events/NewMessage.php (مثال لرسالة خاصة بالمستخدم)
use Illuminate\Broadcasting\PrivateChannel;
// ...
public function broadcastOn()
{
return new PrivateChannel('users.' . $this->userId); // مثال: قناة خاصة لمعرف مستخدم محدد
}
// أضف خاصية للمنشئ لـ userId
public $userId;
public function __construct($message, $userId)
{
$this->message = $message;
$this->userId = $userId;
}
بعد ذلك، قم بتعريف دالة رد اتصال للتصريح في routes/channels.php. يتم تحميل هذا الملف بواسطة BroadcastServiceProvider.
// routes/channels.php
use Illuminate\Support\Facades\Broadcast;
Broadcast::channel('users.{userId}', function ($user, $userId) {
return (int) $user->id === (int) $userId;
});
تضمن دالة رد الاتصال هذه أن User الذي يتطابق معرفه مع $userId فقط هو من يمكنه الاشتراك في قناة users.{userId}.
أخيراً، استمع من جانب العميل:
// بافتراض أن لديك current_user_id متاحًا في الواجهة الأمامية الخاصة بك
const userId = document.querySelector('meta[name="user-id"]').getAttribute('content'); // مثال: الحصول على معرف المستخدم من علامة meta
if (userId) {
Echo.private(`users.${userId}`)
.listen('message.new', (e) => {
console.log('رسالة خاصة للمستخدم', userId, ':', e.message);
// التعامل مع الرسالة الخاصة، على سبيل المثال، إظهار إشعار
});
console.log(`جاري الاستماع لرسائل خاصة على قناة users.${userId}...`);
}
3. قنوات الحضور (Presence Channels) #
قنوات الحضور هي نوع متخصص من القنوات الخاصة التي تُعلمك بمن يشترك حاليًا في القناة. هذا مثالي لميزات مثل قوائم
