إتقان Laravel Echo: تواصل فوري في تطبيقات Laravel الخاصة بك
في مشهد الويب الديناميكي اليوم، لم تعد الميزات في الوقت الفعلي مثل الإشعارات المباشرة وتطبيقات الدردشة ولوحات التحكم التفاعلية رفاهية بل أصبحت توقعات. توفر Laravel، ببيئتها القوية، حلاً أنيقًا لبناء هذه الميزات: Laravel Echo.
Laravel Echo هي مكتبة JavaScript تجعل من السهل بشكل لا يصدق الاشتراك في القنوات والاستماع إلى الأحداث التي تبثها تطبيق Laravel الخاص بك. إنها تعمل كغلاف من جانب العميل حول WebSockets، مما يسمح لك بالتفاعل مع الأحداث من جانب الخادم مباشرة في تطبيق الواجهة الأمامية الخاص بك دون الحاجة إلى الاستقصاء المستمر (polling).
سيرشدك هذا البرنامج التعليمي الشامل خلال إعداد واستخدام Laravel Echo لإضافة إمكانيات الوقت الفعلي إلى مشاريع Laravel الخاصة بك.
1. المتطلبات الأساسية #
قبل أن نبدأ، تأكد من توفر ما يلي:
- مشروع Laravel يعمل (يوصى بالإصدار 8 أو أعلى).
- Node.js و npm (أو Yarn) مثبتين على جهازك.
- Composer مثبت عالمياً.
- فهم أساسي لأحداث وقوائم انتظار Laravel.
- مشغل/خدمة WebSocket (مثل Pusher، Ably، أو حل مستضاف ذاتياً مثل Redis مع Laravel WebSockets).
2. إعداد البث في Laravel #
يتكامل نظام البث في Laravel بسلاسة مع Echo. أولاً، نحتاج إلى تهيئة الواجهة الخلفية (Backend).
2.1. تهيئة مشغل البث (Broadcast Driver) #
افتح ملف .env وقم بتعيين BROADCAST_DRIVER. لهذا البرنامج التعليمي، سنستخدم Pusher، وهو خيار شائع وسهل البدء. إذا كنت تفضل ذلك، يمكنك استخدام Ably، Redis (مع حزمة laravel-websockets)، أو مشغل مخصص.
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_APP_CLUSTER=your-pusher-app-cluster
استبدل القيم النائبة ببيانات اعتماد Pusher الفعلية الخاصة بك، والتي يمكنك الحصول عليها عن طريق إنشاء حساب مجاني على Pusher.com.
2.2. تثبيت Pusher PHP SDK #
إذا كنت تستخدم Pusher، فقم بتثبيت Pusher PHP SDK عبر Composer:
composer require pusher/pusher-php-server
بالنسبة لـ Ably، ستكون composer require ably/ably-php.
2.3. إلغاء التعليق عن مزود خدمة البث (Broadcast Service Provider) #
في config/app.php، تأكد من إلغاء التعليق عن App\Providers\BroadcastServiceProvider::class. يسجل هذا المزود مسارات البث وعمليات رد الاتصال الخاصة بالتصريح.
// config/app.php
'providers' => [
// ...
App\Providers\BroadcastServiceProvider::class,
],
3. تثبيت وتهيئة Laravel Echo #
الآن، لنقم بإعداد مكتبة JavaScript من جانب العميل.
3.1. تثبيت Echo وعميل WebSocket #
قم بتثبيت Laravel Echo وعميل WebSocket الذي اخترته (مثل pusher-js لـ Pusher، ably لـ Ably، أو لا شيء إذا كنت تستخدم laravel-websockets مع المشغل الافتراضي).
npm install --save-dev laravel-echo pusher-js
# أو لـ Ably:
npm install --save-dev laravel-echo ably
3.2. تهيئة Echo في bootstrap.js
#
افتح resources/js/bootstrap.js (أو resources/js/app.js إذا كنت تفضل وضعه هناك) وقم بإلغاء التعليق عن/إضافة تهيئة Laravel Echo. تأكد من تحديثه باستخدام BROADCAST_DRIVER وبيانات الاعتماد الخاصة بك.
// resources/js/bootstrap.js
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, // أو process.env.MIX_PUSHER_APP_KEY لـ Mix
cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER ?? 'mt1',
forceTLS: true
});
// إذا كنت تستخدم Laravel Mix بدلاً من Vite، استخدم process.env.MIX_...
// key: process.env.MIX_PUSHER_APP_KEY,
// cluster: process.env.MIX_PUSHER_APP_CLUSTER,
إذا كنت تستخدم Vite، فتأكد من أن متغيرات .env الخاصة بك مسبوقة بـ VITE_.
3.3. تجميع الأصول (Assets) #
قم بتجميع أصول الواجهة الأمامية الخاصة بك للتأكد من تضمين Echo في حزمة JavaScript الخاصة بتطبيقك:
npm run dev
# أو للإنتاج:
npm run build
تأكد من أن تخطيط Blade الخاص بك يتضمن resources/js/app.js أو ما شابه ذلك.
<head>
<!-- ... -->
@vite('resources/js/app.js') <!-- إذا كنت تستخدم Vite -->
<!-- أو <script src="{{ mix('js/app.js') }}"></script> إذا كنت تستخدم Mix -->
</head>
4. بث الأحداث من Laravel #
الآن بعد أن تم إعداد Echo، لنقم بإنشاء حدث وبثه.
4.1. إنشاء حدث #
أنشئ حدثاً جديداً باستخدام أمر Artisan:
php artisan make:event OrderShipped
4.2. تنفيذ ShouldBroadcast
#
افتح فئة الحدث OrderShipped وقم بتنفيذ واجهة ShouldBroadcast. يخبر هذا Laravel ببث هذا الحدث.
// app/Events/OrderShipped.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 OrderShipped implements ShouldBroadcast
{
use Dispatchable, InteractsWithSockets, SerializesModels;
public $orderId;
public $userName;
/**
* إنشاء مثيل حدث جديد.
*
* @return void
*/
public function __construct($orderId, $userName)
{
$this->orderId = $orderId;
$this->userName = $userName;
}
/**
* الحصول على القنوات التي يجب أن يُبث الحدث عليها.
*
* @return array<int, \Illuminate\Broadcasting\Channel>
*/
public function broadcastOn(): array
{
return [
new Channel('orders'), // قناة عامة (Public Channel)
// new PrivateChannel('users.' . $this->userId), // مثال قناة خاصة (Private Channel)
];
}
/**
* اسم بث الحدث.
*
* @return string
*/
public function broadcastAs(): string
{
return 'order-shipped';
}
}
ShouldBroadcast: الواجهة الأساسية التي تحدد الحدث للبث.$orderId,$userName: خصائص عامة سيتم تسلسلها وتوفيرها للمستمع في الواجهة الأمامية.broadcastOn(): تحدد القنوات التي سيبث هذا الحدث عليها. هنا، نستخدم قناة عامةChannel('orders').broadcastAs(): (اختياري) تخصيص اسم الحدث الذي سيستمع إليه Echo. إذا تم حذفه، سيستمع Echo إلى اسم الفئة (مثال:App.Events.OrderShipped).
4.3. إرسال الحدث #
يمكنك إرسال هذا الحدث من أي مكان في تطبيق Laravel الخاص بك، على سبيل المثال، من وحدة تحكم أو خدمة:
// app/Http/Controllers/OrderController.php
namespace App\Http\Controllers;
use App\Events\OrderShipped;
use Illuminate\Http\Request;
class OrderController extends Controller
{
public function shipOrder(Request $request, $orderId)
{
// منطق شحن الطلب...
$userName = $request->user()->name ?? 'Guest';
event(new OrderShipped($orderId, $userName));
return response()->json(['message' => 'تم شحن الطلب وبث الحدث!']);
}
}
5. الاستماع إلى الأحداث باستخدام Laravel Echo #
الآن، لنقم بإعداد الواجهة الأمامية للاستماع لحدث OrderShipped.
5.1. القنوات العامة (.channel(), .listen())
#
القنوات العامة مفتوحة للجميع. لا يلزم أي تصريح. في ملف JavaScript (مثال: مكون Vue، سكريبت JS عادي، أو مباشرة في app.js):
// resources/js/app.js أو طريقة مكون Vue
// تأكد من تهيئة Echo قبل الاستماع
if (typeof window.Echo !== 'undefined') {
window.Echo.channel('orders')
.listen('order-shipped', (e) => {
console.log('تم استلام حدث شحن الطلب:', e);
alert(`تم شحن الطلب رقم #${e.orderId} بواسطة ${e.userName}!`);
// تحديث الواجهة هنا
});
console.log('يتم الاستماع لأحداث order-shipped على قناة
