README

... is a small php-library to wrap Apple (APNS) and Google (FCM) Push-Notifications into a simple syntax.

Examples:

Android

use ricwein\PushNotification\{PushNotification, Message, Handler};

$message = new Message('message', 'title', ['payload' => 'data']);
$fcm = new Handler\FCM('ExampleGooglePushToken12345678987654321');

$push = new PushNotification(['fcm' => $fcm]);
$push->send($message, ['<device-token>' => 'fcm']);

iOS

NOTE: The APNS Handler uses the new apple push servers, which require HTTP2. Therefore, curl with HTTP2 support must be installed.

use ricwein\PushNotification\{PushNotification, Message, Handler, Config};
use Pushok\AuthProvider;

$message = new Message('message', 'title', ['payload' => 'data']);
$apns = new Handler\APNS(AuthProvider\Token::create([
    'key_id' => 'AAAABBBBCC', // The Key ID obtained from Apple developer account
    'team_id' => 'DDDDEEEEFF', // The Team ID obtained from Apple developer account
    'app_bundle_id' => 'com.app.Test', // The bundle ID for app obtained from Apple developer account
    'private_key_path' => __DIR__ . '/private_key.p8', // Path to private key
    'private_key_secret' => null // Private key secret
]), Config::ENV_PRODUCTION);

$push = new PushNotification(['apns' => $apns]);
$push->send($message, ['<device-token>' => 'apns']);

mixed

Sending messages to multiple devices of difference operating systems is also simple:

use ricwein\PushNotification\{PushNotification, Message, Handler, Config};

$message = new Message('message', 'title');
$fcm = new Handler\FCM('ExampleGooglePushToken12345678987654321');
$apns = new Handler\APNS($authToken, Config::ENV_PRODUCTION);

$push = new PushNotification(['apns' => $apns, 'fcm' => $fcm]);
$push->send($message, [
    '<ios-device-token1>' => 'apns',
    '<ios-device-token2>' => 'apns',
    '<android-device-token1>' => 'fcm',
    '<android-device-token2>' => 'fcm',
]);

single message / single handler

For single handler messages it's possible to inline the handler into the device-destination array. The handler is then freed automatically after the message was send.

use ricwein\PushNotification\{PushNotification, Message, Handler};

$result = (new PushNotification)->send(new Message($body,$title), [
    '<device-token>' => new Handler\<APNS/FCM/etc.>(...$config);
]);

usage

This class uses the root-namespace ricwein\PushNotification.

init

The libraries main class is called PushNotification and requires an array of available push-handlers for the constructor. It's possible to set an ID as the handlers array key, to allow assigning devices to the handler later on.

Available push-handler are:

Apple: PushNotification\Handler\APNS
Google: PushNotification\Handler\FCM

They're all extending PushNotification\Handler

configuration

Since all push-settings are push-handler specific, the settings are directly applied in the handler constructors.

APNS:

 new APNS(
    \Pushok\AuthProviderInterface $authProvider, /* @see https://github.com/edamov/pushok/blob/master/README.md#getting-started */
    string $environment /* (Config::ENV_PRODUCTION / Config::ENV_DEVELOPMENT / Config::ENV_CUSTOM) */
)

FCM:

 new FCM(
    string $token,
    ?string $caCertPath = null,
    string $url = self::FCM_ENDPOINT,
    int $timeout = 10
)

It's also possible to have multiple push-handlers with different configurations like:

use ricwein\PushNotification\{PushNotification, Message, Handler, Config};

// @see https://github.com/edamov/pushok
$apnsProd = new Handler\APNS($tokenProd, Config::ENV_PRODUCTION);
$apnsDev = new Handler\APNS($tokenDev, Config::ENV_DEVELOPMENT);

$message = new Message('message', 'title');
$push = new PushNotification(['prod' => $apnsProd, 'dev' => $apnsDev]);

$push->send($message, [
    '<ios-device-token1>' => 'prod',
    '<ios-device-token2>' => 'dev',
]);

sending

Sending is either available for a message object or a raw payload.

A message object is translated into a native push-notification message with body and title for FCM or APNS before sending.
A raw payload (array) is sent 'as it is' which might not be a good idea, if you want to mix APNS and FCM in one request.

use ricwein\PushNotification\{Message, Config};

$devices = [...];

$message = new Message('body', 'title');
$message->setSound('test.aiff')->setBadge(2)->setPriority(Config::PRIORITY_NORMAL);
$push->send($message, $devices);

/* OR */

$payload = [...];
$push->sendRaw($payload, $devices);

error handling

The PushNotification::send() method returns an Result object. This usually contains an array of per device errors. If everything succeeded, the entry is null. You can fetch failed device-messages with:

$result = $push->send($message, [...]);
$errors = $result->getFailed();

Errors are handled as Exceptions, so it's possible to just throw them. To simply just throw the first error if one occurred, call:

$push->send($message, [...])->throwOnFirstException();

Be aware: Sometimes other failures than usage-errors occur. APNS and FCM can respond with explicit reasons, which will be handled as ResponseReasonException. It's a good idea to not just throw them (away), but handle them other ways. E.g. you might want to delete or update device-tokens which were marked as invalid.

use \ricwein\PushNotification\Exceptions\ResponseReasonException;

foreach($result->getFailed() as $token => $error) {
    if ($error instanceof ResponseReasonException) {
        if ($error->isInvalidDeviceToken()) {
            // $token was invalid
        } elseif ($error->isRateLimited()) {
            // the $token device got too many notifications and is currently rate-limited => better wait some time before sending again.
        }       

    }
}

ricwein / push-notifications

Maintainers

Details