pusher http php Télécharger - pusher http php Téléchargement du code source

Bibliothèque PHP HTTP des canaux pusher

Bibliothèque PHP pour interagir avec l'API HTTP Pusher Channels.

Inscrivez-vous sur https://pusher.com et utilisez les informations d'identification de l'application dans votre application comme indiqué ci-dessous.

Pour signaler des problèmes, des bugs et des demandes de fonctionnalités, n'hésitez pas à ouvrir une pull request ou à ouvrir un problème. Si vous ne recevez pas de réponse dans les délais, n'hésitez pas à consulter notre portail d'assistance.

Installation

Vous pouvez obtenir la bibliothèque PHP Pusher Channels via un package composer appelé pusher-php-server . Voir https://packagist.org/packages/pusher/pusher-php-server

$ composer require pusher/pusher-php-server

Ou ajoutez à composer.json :

 "require" : {
    "pusher/pusher-php-server" : " ^7.2 "
}

puis exécutez composer update .

Plateformes prises en charge

PHP - prend en charge les versions PHP 7.3, 7.4, 8.0, 8.1, 8.2 et 8.3.
Laravel - version 8.29 et supérieure prend en charge les canaux Pusher en tant que backend de diffusion.
Autres frameworks PHP - pris en charge à condition que vous utilisiez une version prise en charge de PHP.

Constructeur de canaux pusher

Utilisez les informations d’identification de votre application Pusher Channels pour créer une nouvelle instance PusherPusher .

 $ app_id = ' YOUR_APP_ID ' ;
$ app_key = ' YOUR_APP_KEY ' ;
$ app_secret = ' YOUR_APP_SECRET ' ;
$ app_cluster = ' YOUR_APP_CLUSTER ' ;

$ pusher = new Pusher  Pusher ( $ app_key , $ app_secret , $ app_id , [ ' cluster ' => $ app_cluster ]);

Le quatrième paramètre est un tableau $options . Les options supplémentaires sont :

scheme - par exemple http ou https
host - l'hôte, par exemple api.pusherapp.com. Pas de barre oblique finale
port - le port http
path - un préfixe à ajouter à tous les chemins de requête. Ceci n'est utile que si vous exécutez la bibliothèque sur un point final que vous contrôlez vous-même (par exemple un proxy qui achemine en fonction du préfixe de chemin).
timeout - le délai d'attente HTTP
useTLS - option rapide pour utiliser le schéma https et le port 443.
cluster - spécifiez le cluster à partir duquel l'application est exécutée.
encryption_master_key_base64 - une clé de 32 caractères de long. Cette clé, ainsi que le nom du canal, sont utilisées pour dériver des clés de chiffrement par canal. Les clés par canal sont utilisées pour chiffrer les données d'événements sur les canaux chiffrés.

Par exemple, par défaut, les appels seront effectués via HTTPS. Pour utiliser du HTTP simple, vous pouvez définir useTLS sur false :

 $ options = [
  ' cluster ' => $ app_cluster ,
  ' useTLS ' => false
];

$ pusher = new Pusher  Pusher ( $ app_key , $ app_secret , $ app_id , $ options );

Configuration de la journalisation

L'approche recommandée en matière de journalisation consiste à utiliser un enregistreur compatible PSR-3 implémentant PsrLogLoggerInterface . L'objet Pusher implémente PsrLogLoggerAwareInterface , ce qui signifie que vous appelez setLogger(LoggerInterface $logger) pour définir l'instance de l'enregistreur.

 // where $logger implements `LoggerInterface`

$ pusher -> setLogger ( $ logger );

Client Guzzle personnalisé

Cette bibliothèque utilise Guzzle en interne pour effectuer des appels HTTP. Vous pouvez transmettre votre propre instance Guzzle au constructeur Pusher :

 $ custom_client = new GuzzleHttp  Client ();

$ pusher = new Pusher  Pusher (
    $ app_key ,
    $ app_secret ,
    $ app_id ,
    [],
    $ custom_client
);

Cela vous permet de passer votre propre middleware, voir les tests pour un exemple.

Publication/Déclenchement d'événements

Pour déclencher un événement sur un ou plusieurs canaux utilisez la fonction trigger .

Un seul canal

 $ pusher -> trigger ( ' my-channel ' , ' my_event ' , ' hello world ' );

Plusieurs canaux

 $ pusher -> trigger ([ ' channel-1 ' , ' channel-2 ' ], ' my_event ' , ' hello world ' );

Lots

Il est également possible d'envoyer plusieurs événements avec un seul appel API (max 10 événements par appel sur les clusters multi-locataires) :

 $ batch = [];
$ batch [] = [ ' channel ' => ' my-channel ' , ' name ' => ' my_event ' , ' data ' => [ ' hello ' => ' world ' ]];
$ batch [] = [ ' channel ' => ' my-channel ' , ' name ' => ' my_event ' , ' data ' => [ ' myname ' => ' bob ' ]];
$ pusher -> triggerBatch ( $ batch );

Interface asynchrone

trigger et triggerBatch ont des homologues asynchrones dans triggerAsync et triggerBatchAsync . Ces fonctions renvoient des promesses Guzzle qui peuvent être chaînées avec ->then :

 $ promise = $ pusher -> triggerAsync ([ ' channel-1 ' , ' channel-2 ' ], ' my_event ' , ' hello world ' );

$ promise -> then ( function ( $ result ) {
  // do something with $result
  return $ result ;
});

$ final_result = $ promise -> wait ();

Tableaux

Les tableaux sont automatiquement convertis au format JSON :

 $ array [ ' name ' ] = ' joe ' ;
$ array [ ' message_count ' ] = 23 ;

$ pusher -> trigger ( ' my_channel ' , ' my_event ' , $ array );

Le résultat de ceci sera :

 " {'name': 'joe', 'message_count': 23} "

Identifiant du socket

Afin d'éviter les doublons, vous pouvez éventuellement spécifier l'identifiant de socket de l'expéditeur lors du déclenchement d'un événement :

 $ pusher -> trigger ( ' my-channel ' , ' event ' , ' data ' , [ ' socket_id ' => $ socket_id ]);

 $ batch = [];
$ batch [] = [ ' channel ' => ' my-channel ' , ' name ' => ' my_event ' , ' data ' => [ ' hello ' => ' world ' ], [ ' socket_id ' => $ socket_id ]];
$ batch [] = [ ' channel ' => ' my-channel ' , ' name ' => ' my_event ' , ' data ' => [ ' myname ' => ' bob ' ], [ ' socket_id ' => $ socket_id ]];
$ pusher -> triggerBatch ( $ batch );

Récupérer les informations de la chaîne lors de la publication [EXPERIMENTAL]

Il est possible de demander des attributs sur les chaînes sur lesquelles ont été publiées avec le paramètre info :

 $ result = $ pusher -> trigger ( ' my-channel ' , ' my_event ' , ' hello world ' , [ ' info ' => ' subscription_count ' ]);
$ subscription_count = $ result -> channels [ ' my-channel ' ]-> subscription_count ;

 $ batch = [];
$ batch [] = [ ' channel ' => ' my-channel ' , ' name ' => ' my_event ' , ' data ' => [ ' hello ' => ' world ' ], ' info ' => ' subscription_count ' ];
$ batch [] = [ ' channel ' => ' presence-my-channel ' , ' name ' => ' my_event ' , ' data ' => [ ' myname ' => ' bob ' ], ' info ' => ' user_count,subscription_count ' ];
$ result = $ pusher -> triggerBatch ( $ batch );

foreach ( $ result -> batch as $ i => $ attributes ) {
  echo " channel: { $ batch [ $ i ][ ' channel ' ]} , name: { $ batch [ $ i ][ ' name ' ]}" ;
  if ( isset ( $ attributes -> subscription_count )) {
    echo " , subscription_count: { $ attributes -> subscription_count }" ;
  }
  if ( isset ( $ attributes -> user_count )) {
    echo " , user_count: { $ attributes -> user_count }" ;
  }
  echo PHP_EOL ;
}

Format JSON

Si vos données sont déjà encodées au format JSON, vous pouvez éviter une deuxième étape d'encodage en définissant le sixième argument sur vrai, comme ceci :

 $ pusher -> trigger ( ' my-channel ' , ' event ' , ' data ' , [], true );

Authentification des utilisateurs

Pour authentifier les utilisateurs sur les canaux Pusher de votre application, vous pouvez utiliser la fonction authenticateUser :

 $ pusher -> authenticateUser ( ' socket_id ' , ' user-id ' );

Pour plus d’informations, consultez Authentification des utilisateurs.

Autoriser les chaînes privées

Pour autoriser vos utilisateurs à accéder aux chaînes privées sur Pusher, vous pouvez utiliser la fonction authorizeChannel :

 $ pusher -> authorizeChannel ( ' private-my-channel ' , ' socket_id ' );

Pour plus d’informations, consultez autoriser les utilisateurs.

Autoriser les canaux de présence

L'utilisation des canaux de présence est similaire aux canaux privés, mais vous pouvez spécifier des données supplémentaires pour identifier cet utilisateur particulier :

 $ pusher -> authorizePresenceChannel ( ' presence-my-channel ' , ' socket_id ' , ' user_id ' , ' user_info ' );

Pour plus d’informations, consultez autoriser les utilisateurs.

Webhooks

Cette bibliothèque permet de vérifier que les webhooks que vous recevez de Pusher sont réellement de véritables webhooks de Pusher. Il fournit également une structure pour les stocker. Une méthode d'assistance appelée webhook permet cela. Transmettez les en-têtes et le corps de la requête, et elle renverra un objet Webhook avec vos événements vérifiés. Si la bibliothèque n'a pas pu valider la signature, une exception est levée à la place.

 $ webhook = $ pusher -> webhook ( $ request_headers , $ request_body );
$ number_of_events = count ( $ webhook -> get_events ());
$ time_received = $ webhook -> get_time_ms ();

Chiffrement de bout en bout

Cette bibliothèque prend en charge le cryptage de bout en bout de vos chaînes privées. Cela signifie que seuls vous et vos clients connectés pourrez lire vos messages. Pusher ne peut pas les décrypter. Vous pouvez activer cette fonctionnalité en suivant ces étapes :

Vous devez d'abord configurer des chaînes privées. Cela implique la création d'un point de terminaison d'autorisation sur votre serveur.
Ensuite, générez votre clé de cryptage principale de 32 octets, encodez-la en base64 et stockez-la en toute sécurité. C’est secret et vous ne devriez jamais le partager avec qui que ce soit. Pas même Pusher.
Pour générer une clé appropriée à partir d'une bonne source aléatoire, vous pouvez utiliser la commande openssl :
```
openssl rand -base64 32
```

Spécifiez votre clé de chiffrement principale lors de la création de votre client Pusher :

 $ pusher = new Pusher  Pusher (
    $ app_key ,
    $ app_secret ,
    $ app_id ,
    [
        ' cluster ' => $ app_cluster ,
        ' encryption_master_key_base64 ' => " <your base64 encoded master key> "
    ]
 );

Les chaînes sur lesquelles vous souhaitez utiliser le cryptage de bout en bout doivent être préfixées par private-encrypted- .
Abonnez-vous à ces chaînes dans votre client et le tour est joué ! Vous pouvez vérifier qu'il fonctionne en consultant la console de débogage sur https://dashboard.pusher.com/ et en voyant le texte chiffré brouillé.

Remarque importante : cela ne chiffrera pas les messages sur les canaux qui ne sont pas préfixés par private-encrypted- .

Limitation : vous ne pouvez pas déclencher un seul événement sur un mélange de canaux non chiffrés et chiffrés dans un appel à trigger , par exemple

 $ data [ ' name ' ] = ' joe ' ;
$ data [ ' message_count ' ] = 23 ;

$ pusher -> trigger ([ ' channel-1 ' , ' private-encrypted-channel-2 ' ], ' test_event ' , $ data );

Justification : les méthodes de cette bibliothèque correspondent directement aux requêtes API HTTP des canaux individuels. Si nous autorisions le déclenchement d'un seul événement sur plusieurs canaux (certains chiffrés, d'autres non chiffrés), cela nécessiterait deux requêtes API : une où l'événement est chiffré sur les canaux chiffrés et une où l'événement n'est pas chiffré pour les canaux non chiffrés.

Exemple de présence

Définissez d'abord le point de terminaison d'autorisation de canal dans votre application JS lors de la création de l'objet Pusher :

 var pusher = new Pusher ( "app_key" ,
  // ...
  channelAuthorization : {
    endpoint : "/presenceAuth.php" ,
  } ,
) ;

Ensuite, créez ce qui suit dans présenceAuth.php :

 <?php

header ( ' Content-Type: application/json ' );

if ( isset ( $ _SESSION [ ' user_id ' ])) {
  $ stmt = $ pdo -> prepare ( " SELECT * FROM `users` WHERE id = :id " );
  $ stmt -> bindValue ( ' :id ' , $ _SESSION [ ' user_id ' ], PDO :: PARAM_INT );
  $ stmt -> execute ();
  $ user = $ stmt -> fetch ();
} else {
  die ( json_encode ( ' no-one is logged in ' ));
}

$ pusher = new Pusher  Pusher ( $ key , $ secret , $ app_id );
$ presence_data = [ ' name ' => $ user [ ' name ' ]];

echo $ pusher -> authorizePresenceChannel ( $ _POST [ ' channel_name ' ], $ _POST [ ' socket_id ' ], $ user [ ' id ' ], $ presence_data );

Remarque : cela suppose que vous stockiez vos utilisateurs dans une table appelée users et que ces utilisateurs aient une colonne name . Cela suppose également que vous disposez d'un mécanisme de connexion qui stocke l' user_id de l'utilisateur connecté à la session.

Requêtes sur l'état de l'application

Obtenir des informations sur une chaîne

 $ pusher -> getChannelInfo ( $ name );

Il est également possible d'obtenir des informations sur un canal à partir de l'API HTTP Channels.

 $ info = $ pusher -> getChannelInfo ( ' channel-name ' );
$ channel_occupied = $ info -> occupied ;

Pour les canaux de présence, vous pouvez également demander le nombre d'utilisateurs distincts actuellement abonnés à ce canal (un même utilisateur peut être abonné plusieurs fois, mais ne comptera que pour un) :

 $ info = $ pusher -> getChannelInfo ( ' presence-channel-name ' , [ ' info ' => ' user_count ' ]);
$ user_count = $ info -> user_count ;

Si vous avez activé la possibilité d'interroger le subscription_count (le nombre de connexions actuellement souscrites à ce canal), vous pouvez interroger cette valeur comme suit :

 $ info = $ pusher -> getChannelInfo ( ' presence-channel-name ' , [ ' info ' => ' subscription_count ' ]);
$ subscription_count = $ info -> subscription_count ;

Obtenez une liste des canaux de candidature

 $ pusher -> getChannels ();

Il est également possible d'obtenir une liste de canaux pour une application à partir de l'API HTTP Channels.

 $ result = $ pusher -> getChannels ();
$ channel_count = count ( $ result -> channels ); // $channels is an Array

Obtenez une liste filtrée des canaux de candidature

 $ pusher -> getChannels ([ ' filter_by_prefix ' => ' some_filter ' ]);

Il est également possible d'obtenir une liste de chaînes en fonction de leur préfixe de nom. Pour ce faire, vous devez fournir un paramètre $options à l'appel. Dans l'exemple suivant, l'appel renverra une liste de tous les canaux avec un préfixe presence- . C'est une idée pour récupérer une liste de tous les canaux de présence.

 $ results = $ pusher -> getChannels ([ ' filter_by_prefix ' => ' presence- ' ]);
$ channel_count = count ( $ result -> channels ); // $channels is an Array

Cela peut également être réalisé en utilisant la fonction générique pusher->get :

 $ pusher -> get ( ' /channels ' , [ ' filter_by_prefix ' => ' presence- ' ]);

Obtenez une liste des canaux d'application avec le nombre d'abonnements

L'API HTTP renvoyant la liste des chaînes ne prend pas en charge le renvoi du nombre d'abonnements avec chaque chaîne. Au lieu de cela, vous pouvez récupérer ces données en parcourant chaque canal et en effectuant une autre requête. Attention : cette approche consomme (nombre de canaux + 1) messages !

 <?php
$ subscription_counts = [];
foreach ( $ pusher -> getChannels ()-> channels as $ channel => $ v ) {
  $ subscription_counts [ $ channel ] =
    $ pusher -> getChannelInfo (
      $ channel , [ ' info ' => ' subscription_count ' ]
    )-> subscription_count ;
}
var_dump ( $ subscription_counts );

Obtenir des informations utilisateur à partir d'un canal de présence

 $ results = $ pusher -> getPresenceUsers ( ' presence-channel-name ' );
$ users_count = count ( $ results -> users ); // $users is an Array

Cela peut également être réalisé en utilisant la fonction générique pusher->get :

 $ response = $ pusher -> get ( ' /channels/presence-channel-name/users ' );

La $response est au format :

Array (
	[body] => { " users " :[{ " id " :"a_user_id"}]}
	[status] => 200
	[result] => Array (
		[users] => Array (
			[ 0 ] => Array (
				[id] => a_user_id
			),
			/* Additional users */
		)
	)
)

Fonction d'obtention générique

 $ pusher -> get ( $ path , $ params );

Utilisé pour effectuer des requêtes GET sur l'API HTTP Channels. Gère l’authentification.

La réponse est un tableau associatif avec un index result . Le contenu de cet index dépend de la méthode HTTP appelée. Cependant, une propriété status permettant d'autoriser le code d'état HTTP est toujours présente et une propriété result sera définie si le code d'état indique un appel réussi à l'API.

 $ response = $ pusher -> get ( ' /channels ' );
$ http_status_code = $ response [ ' status ' ];
$ result = $ response [ ' result ' ];

Exécuter les tests

Nécessite phpunit.

Exécuter composer install
Allez dans le répertoire tests
Renommez config.example.php en config.php et remplacez les valeurs par des informations d'identification de canaux valides ou créez des variables d'environnement.
Certains tests nécessitent qu'un client soit connecté à l'application que vous avez définie dans la configuration ; vous pouvez le faire en ouvrant https://dashboard.pusher.com/apps/<YOUR_TEST_APP_ID>/getting_started dans le navigateur
Depuis le répertoire racine du projet, exécutez composer exec phpunit pour exécuter tous les tests.

Licence

Développer