README

Samodzielny moduł powiadomień push dla NimblePHP oparty na Firebase Cloud Messaging (FCM HTTP v1). Moduł trzyma własny stan (rejestr urządzeń + kolejka wysyłki), a wysyłkę realizuje worker cron — nie wymaga żadnego innego modułu poza framework i migrations.

Instalacja

composer require nimblephp/firebase

Migracje (module_firebase_device, module_firebase_delivery) uruchamiają się przez Module::onUpdate() (grupa module_firebase) podczas aktualizacji aplikacji.

Konfiguracja (env)

Konto serwisowe Firebase Admin SDK — plik albo wartości inline:

Użycie

Rejestracja urządzenia (z kontrolera)

$device = $this->loadModel(\NimblePHP\Firebase\ModuleFirebaseDeviceModel::class);

$deviceId = $device->register([
    'installation_id' => $installationId, // unikalny per instalacja
    'token' => $fcmToken,
    'platform' => 'android',
]);

register() robi upsert po installation_id (aktualizuje token, reaktywuje). Powiązanie urządzenia z użytkownikiem to zadanie aplikacji — trzymaj mapowanie user ↔ device_id (lub installation_id) we własnej tabeli. Moduł celowo nie zna pojęcia konta.

Kolejkowanie powiadomienia

$delivery = $this->loadModel(\NimblePHP\Firebase\ModuleFirebaseDeliveryModel::class);

// pojedyncze urządzenie
$delivery->enqueue($deviceId, 'Tytuł', 'Treść', ['key' => 'value'], priority: 2);

// wiele urządzeń naraz (id urządzeń ustalasz po swojej stronie)
$service = new \NimblePHP\Firebase\PushService();
$service->enqueueForDevices($delivery, [$deviceId1, $deviceId2], 'Tytuł', 'Treść');

Wysyłka (dwustopniowy cron)

Wysyłka jest rozdzielona, żeby wolne wywołania HTTP do FCM nie blokowały kolejki:

1. Dispatcher #[Cron('* * * * *')] (dispatchQueueCron) — co minutę zmienia wpisy new → queued i dorzuca jedno lekkie zadanie na dostarczenie (Cron::addJob). Same INSERT-y, więc nawet duży backlog rozrzuca się szybko.
2. Zadanie wysyłki (sendDeliveryJob(id)) — wykonuje pojedyncze wywołanie FCM, ustawia status (sent/failed/invalid) i deaktywuje urządzenie z nieważnym tokenem. Krótkie, nie przetrzymuje kolejki.

Statusy dostarczenia: new → queued → sent | failed | invalid.

Wysyłka bezpośrednia (bez kolejki)

(new \NimblePHP\Firebase\FcmService())->sendToDevice(
    $fcmToken,
    ['title' => 'Tytuł', 'body' => 'Treść', 'priority' => 2],
    ['key' => 'value']
);

Klasy

• FcmService — transport FCM v1 (OAuth2 JWT RS256, bez zależności zewnętrznych)
• ModuleFirebaseDeviceModel — rejestr urządzeń (register, getByInstallationId, deactivate) + cron czyszczący
• ModuleFirebaseDeliveryModel — kolejka wysyłki (enqueue) + dispatcher cron + sendDeliveryJob
• PushService — fan-out po liście urządzeń + dispatch/wysyłka kolejki
• FcmDeliveryException / FirebaseException