nimblephp/firebase

Standalone Firebase push notifications module for NimblePHP - FCM sending with device registry and delivery queue processed by cron

dev-main 2026-07-01 05:00 UTC

Requires

• php: >=8.3
• ext-curl: *
• ext-json: *
• ext-openssl: *
• krzysztofzylka/database-manager: >=1.1.22
• nimblephp/framework: >=0.4.14
• nimblephp/migrations: >=0.3.2

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

• Krzysztof Żyłka

Published on Packagist.org on 2026-07-01 05:03 UTC

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:

Zmienna	Znaczenie
FCM_CREDENTIALS_PATH	ścieżka do firebase-adminsdk.json (domyślnie /run/secrets/firebase-adminsdk.json)
FCM_PROJECT_ID	id projektu (gdy bez pliku)
FCM_CLIENT_EMAIL	client_email konta serwisowego
FCM_PRIVATE_KEY	private_key konta serwisowego

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