PushNotifier

PushNotifier est un package PHP puissant et flexible (compatible avec tout framework ou application brute) pour l'envoi de notifications push via Firebase Cloud Messaging (FCM) v1. Construit avec une architecture robuste et orientée contrat (interfaces), il simplifie l'authentification et l'envoi de notifications, vous permettant d'intégrer des notifications fiables en quelques minutes.

📦 Installation

composer require andydefer/push-notifier

🚀 Démarrage Rapide

1. Obtenir les identifiants Firebase

1. Allez dans la Console Firebase.
2. Sélectionnez votre projet.
3. Allez dans Paramètres du projet > Comptes de service.
4. Cliquez sur Générer une nouvelle clé privée pour télécharger le fichier JSON du compte de service.
5. Placez ce fichier dans un endroit sécurisé de votre projet (par exemple, storage/app/firebase-credentials.json).

2. Envoyer votre première notification

<?php

require 'vendor/autoload.php';

use Andydefer\PushNotifier\Core\NotificationFactory;

// 1. Créer une factory
$factory = new NotificationFactory();

// 2. Créer un service Firebase à partir du fichier JSON
$firebaseService = $factory->makeFirebaseServiceFromJsonFile(
    __DIR__ . '/storage/firebase-credentials.json'
);

// 3. Envoyer une notification simple
$deviceToken = 'votre_token_appareil_fcm';

$response = $firebaseService->sendInfo(
    $deviceToken,
    'Bonjour !',
    'Ceci est ma première notification push.'
);

if ($response->success) {
    echo "Notification envoyée avec succès ! ID : " . $response->messageId;
} else {
    echo "Échec de l'envoi : " . $response->errorMessage;
}

🔗 Architecture et Concepts Clés

Le package est construit autour de plusieurs concepts puissants pour garantir flexibilité, testabilité et fiabilité dans n'importe quel environnement PHP.

1. La Factory comme Point d'Entrée Unique

La classe NotificationFactory est le point d'entrée principal. Elle centralise la création de vos services et vous permet d'injecter vos propres implémentations des composants de bas niveau (client HTTP, fournisseur d'auth). C'est le cœur de l'injection de dépendances du package.

$factory = new NotificationFactory();

// Créer un service de différentes manières
$service = $factory->makeFirebaseServiceFromJsonFile($jsonPath);
$service = $factory->makeFirebaseServiceFromJsonString($jsonContent);
$service = $factory->makeFirebaseServiceFromArray($configArray);
$service = $factory->makeFirebaseServiceFromEnv($_ENV);

2. Contrats pour la Flexibilité (Interfaces)

Le package est défini par des contrats (interfaces). Cela vous permet de remplacer n'importe quel composant interne par votre propre logique sans modifier le cœur du package.

• HttpClientInterface: Pour utiliser un client HTTP différent.
• AuthProviderInterface: Pour gérer l'authentification Firebase d'une manière différente.
• PayloadBuilderInterface: Pour construire le payload FCM selon vos propres besoins (optionnel, une implémentation par défaut est fournie).

// Exemple : Utiliser un client HTTP personnalisé
use App\Services\MyCustomHttpClient;

$factory = new NotificationFactory(
    new MyCustomHttpClient() // Injecté ici
);
$service = $factory->makeFirebaseServiceFromJsonFile($jsonPath);

3. DTOs pour la Clarté et la Cohérence

Toutes les données manipulées par le package sont encapsulées dans des DTOs (Data Transfer Objects).

• FirebaseConfigData : Contient la configuration Firebase.
• FcmMessageData : Représente le message à envoyer, avec une structure simple : type (string en SCREAMING_SNAKE_CASE) et data (array avec clés en camelCase, valeurs must be strings).
• FcmResponseData : Représente la réponse de l'API FCM.
• HttpResponseData : Encapsule une réponse HTTP brute.

4. Exceptions Spécifiques

Le package lance des exceptions spécifiques pour chaque type d'erreur.

• FcmSendException: Levée lors d'un échec d'envoi.
• FirebaseAuthException: Levée en cas de problème d'authentification.
• InvalidConfigurationException: Levée si la configuration Firebase est invalide.

📧 Création de Messages

Le DTO FcmMessageData a une structure simple et flexible :

• type : string en SCREAMING_SNAKE_CASE (libre choix)
• data : array avec clés en camelCase (valeurs must be strings)

Types de Notifications Prédéfinis

use Andydefer\PushNotifier\Dtos\FcmMessageData;

// Notification d'information (title et body uniquement)
$info = FcmMessageData::info('Mise à jour', 'Nouvelle version disponible.');

// Notification silencieuse (avec connected: true par défaut)
$ping = FcmMessageData::ping();

Messages Personnalisés

Pour tous les autres types, utilisez la méthode make() :

$message = FcmMessageData::make(
    type: 'CHAT_MESSAGE',
    data: [
        'title' => 'Nouveau message',
        'body' => 'Vous avez reçu un message',
        'senderId' => '123',
        'senderName' => 'Jean',
        'conversationId' => '456'
    ]
);

🛠️ Utilisation Avancée

Envoyer à plusieurs appareils

$tokens = ['token1', 'token2', 'token3'];
$message = FcmMessageData::make('PROMO', [
    'title' => 'Promo Flash',
    'body' => '-50% sur tout !'
]);

$results = $firebaseService->sendMulticast($tokens, $message);

foreach ($results as $token => $response) {
    if ($response->success) {
        // Succès
    } else if ($response->isInvalidToken()) {
        // Token invalide, à supprimer
    }
}

Valider un token

if ($firebaseService->validateToken($deviceToken)) {
    // Token valide
} else {
    // Token invalide, à supprimer
}

Analyser les réponses d'erreur

try {
    $response = $firebaseService->send($token, $message);
} catch (FcmSendException $e) {
    $errorResponse = FcmResponseData::fromError(
        $e->getErrorCode() ?? 'UNKNOWN',
        $e->getMessage(),
        $e->getStatusCode()
    );

    if ($errorResponse->isInvalidToken()) {
        // Marquer le token comme invalide
    } elseif ($errorResponse->isQuotaExceeded()) {
        // Gérer le dépassement de quota
    }
}

⚙️ Configuration

Méthodes de Configuration

// Via fichier JSON (recommandé)
$service = $factory->makeFirebaseServiceFromJsonFile('/path/to/credentials.json');

// Via chaîne JSON
$jsonContent = file_get_contents('/path/to/credentials.json');
$service = $factory->makeFirebaseServiceFromJsonString($jsonContent);

// Via tableau PHP
$config = [
    'project_id' => 'votre-projet-id',
    'client_email' => 'firebase-adminsdk-xxx@...',
    'private_key' => "-----BEGIN PRIVATE KEY-----\nMII...\n-----END PRIVATE KEY-----\n",
];
$service = $factory->makeFirebaseServiceFromArray($config);

// Via variables d'environnement
$service = $factory->makeFirebaseServiceFromEnv($_ENV);

🧪 Tests

# Exécuter tous les tests
composer test

# Exécuter les tests avec couverture
composer test-coverage

📚 API Complète

NotificationFactory

Méthode	Description
__construct(?HttpClientInterface, ?AuthProviderInterface)	Constructeur avec injection optionnelle.
makeFirebaseServiceFromJsonFile(string $path): FirebaseService	Crée un service depuis un fichier JSON.
makeFirebaseServiceFromJsonString(string $json): FirebaseService	Crée un service depuis une chaîne JSON.
makeFirebaseServiceFromArray(array $config): FirebaseService	Crée un service depuis un tableau.
makeFirebaseServiceFromEnv(array $env): FirebaseService	Crée un service depuis les variables d'env.
makeFirebaseService(FirebaseConfigData $config): FirebaseService	Crée un service depuis un DTO.

FirebaseService

Méthode	Description
send(string $token, FcmMessageData $message): FcmResponseData	Envoie une notification.
sendMulticast(array $tokens, FcmMessageData $message): array	Envoie à plusieurs appareils.
sendInfo(string $token, string $title, string $body): FcmResponseData	Envoie une notification "INFO".
ping(string $token): FcmResponseData	Envoie une notification silencieuse "PING".
validateToken(string $token): bool	Vérifie si un token est valide.

FcmMessageData

Méthode Statique	Description
make(string $type, array $data = []): self	Crée un message personnalisé.
info(string $title, string $body): self	Crée un message "INFO".
ping(): self	Crée un message "PING" avec ['connected' => 'true'].

FcmResponseData

Méthode	Description
fromFcmResponse(array $response, int $statusCode): self	Crée depuis une réponse FCM.
fromError(string $code, string $message, ?int $statusCode): self	Crée depuis une erreur.
isInvalidToken(): bool	Vérifie si le token est invalide.
isQuotaExceeded(): bool	Vérifie si le quota est dépassé.
isAuthError(): bool	Vérifie s'il s'agit d'une erreur d'authentification.

🤝 Contribution

Les contributions sont les bienvenues !

1. Forkez le projet
2. Créez une branche (git checkout -b feature/ma-fonctionnalite)
3. Commitez (git commit -m 'Ajoute une fonctionnalité')
4. Poussez (git push origin feature/ma-fonctionnalite)
5. Ouvrez une Pull Request

📄 Licence

MIT

---

PushNotifier - Des notifications push simples et fiables avec PHP et Firebase. 🚀