إشعارات Push باستخدام Notifire + FCM مع Laravel

إذا كنت تريد إرسال إشعارات فورية (Push Notifications) من مشروعك المبني على Laravel إلى تطبيقات الموبايل أو الويب، فأبسط وأسرع حل هو استخدام مكتبة Notifire.
الميزة الأساسية هنا هي أنك تبقى داخل نظام Laravel Notifications المعتاد، بدون الحاجة لحلول خارجية معقدة، مع الاستفادة من تكامل سلس مع خدمة Firebase Cloud Messaging (FCM).

ما هي Notifire ولماذا نستخدمها؟

Notifire هي مكتبة (Package) متخصصة في ربط Laravel مع خدمة FCM.
من خلالها يمكنك إرسال إشعارات بمحتوى بسيط أو متقدّم يشمل:

  • عنوان (Title)

  • نص (Body)

  • صورة (Image)

  • أيقونة (Icon)

  • صوت (Sound)

  • إجراءات (Actions)

كما توفر لك إدارة كاملة لرموز الأجهزة (FCM Tokens)، بما في ذلك تسجيلها وتخزينها بشكل منظم في قاعدة البيانات.

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

قبل البدء ستحتاج إلى:

  1. مشروع مفعّل على Firebase.

  2. تنزيل ملف Service Account وتخزينه في مكان آمن مثل storage/firebase.json.

  3. تفعيل Laravel Sanctum لأن تسجيل التوكنات يعتمد عليه.

خطوات التثبيت

التثبيت يتم عبر 3 أوامر فقط:

composer require devkandil/notifire
php artisan vendor:publish --provider="DevKandil\NotiFire\FcmServiceProvider"
php artisan migrate

إدارة الرموز (Tokens)

توفر المكتبة Trait يمكن إضافته إلى نموذج المستخدم لإدارة رموز FCM.

  • كل إشعار مرتبط بتوكن جهاز محدد.

  • إذا كان المستخدم يسجل الدخول من أكثر من جهاز، يُفضل إنشاء جدول مخصص للأجهزة.

تسجيل التوكن من الواجهة (Frontend)

تضيف Notifire مسارًا جاهزًا:

POST /fcm/token

هذا المسار مدمج مباشرة مع Sanctum.
كل جهاز (ويب أو موبايل) يولّد توكن من Firebase، ويرسله للسيرفر ليتم تخزينه وربطه بالمستخدم.

إرسال الإشعارات

يمكنك الإرسال بطريقتين:

  1. عبر الـ Facade مباشرة.

  2. أو باستخدام نظام Laravel Notifications الرسمي.

مثال للإرسال المباشر:

$ok = Fcm::withTitle('تنبيه جديد')
    ->withBody('يوجد تحديث في حسابك')
    ->sendNotification($token);

أفضل الممارسات

  • نفّذ الإرسال دائمًا عبر Queues لتجنب بطء التطبيق.

  • احفظ بيانات Firebase في مكان آمن بعيد عن Git.

  • أعد تهيئة أو إلغاء التوكنات التالفة أو بعد تسجيل الخروج.

  • استخدم Topics عند الحاجة لإرسال إشعارات لشرائح واسعة من المستخدمين.

أخطاء شائعة وحلولها

  • الإشعارات لا تصل: تحقق من صلاحيات Service Worker (في الويب) أو أعد تسجيل التوكن.

  • خطأ 401/403 عند /fcm/token: غالبًا مشكلة في Sanctum أو نقص في التوكن.

  • بطء الإرسال: استخدم Workers وفصل عملية الإرسال عن الـ UI.

الخلاصة

تجعل Notifire تكامل Laravel مع FCM تجربة سهلة واحترافية.
بمجرد إدارة التوكنات بشكل صحيح وربطها بالمستخدمين، ثم تفعيل Queues للإرسال، ستحصل على نظام إشعارات موثوق وسريع لتطبيقاتك على الموبايل والويب.