[BC] add urgency and topic + TTL for each notification

Author: Minishlink

README.md

@@ -88,45 +88,59 @@ $webPush = new WebPush($apiKeys);
 $webPush->sendNotification($endpoint, null, null, null, true);
 ```
 
-### Payload length and security
-Payload will be encrypted by the library. The maximum payload length is 4078 bytes (or ASCII characters).
-
-However, when you encrypt a string of a certain length, the resulting string will always have the same length,
-no matter how many times you encrypt the initial string. This can make attackers guess the content of the payload.
-In order to circumvent this, this library can add some null padding to the initial payload, so that all the input of the encryption process
-will have the same length. This way, all the output of the encryption process will also have the same length and attackers won't be able to 
-guess the content of your payload. The downside of this approach is that you will use more bandwidth than if you didn't pad the string.
-That's why the library provides the option to disable this security measure:
+### Notification options
+Each notification can have a specific Time To Live, urgency, and topic.
+You can change the default options with `setDefaultOptions()` or in the constructor:
 
 ```php
 <?php
 
 use Minishlink\WebPush\WebPush;
 
-$webPush = new WebPush();
-$webPush->setAutomaticPadding(false); // disable automatic padding
+$defaultOptions = array(
+    'TTL' => 300, // defaults to 4 weeks
+    'urgency' => 'normal',
+    'topic' => 'new_event',
+);
+
+// for every notifications
+$webPush = new WebPush(array(), $defaultOptions);
+$webPush->setDefaultOptions($defaultOptions);
+
+// or for one notification
+$webPush->sendNotification($endpoint, $payload, $userPublicKey, $userAuthToken, true, array('TTL' => 5000));
 ```
 
-### Time To Live
+#### TTL
 Time To Live (TTL, in seconds) is how long a push message is retained by the push service (eg. Mozilla) in case the user browser 
 is not yet accessible (eg. is not connected). You may want to use a very long time for important notifications. The default TTL is 4 weeks. 
 However, if you send multiple nonessential notifications, set a TTL of 0: the push notification will be delivered only 
 if the user is currently connected. For other cases, you should use a minimum of one day if your users have multiple time 
 zones, and if they don't several hours will suffice.
 
+#### urgency
+Urgency can be either "very-low", "low", "normal", or "high". If the browser vendor has implemented this feature, it will save battery life on mobile devices (cf. [protocol](https://tools.ietf.org/html/draft-ietf-webpush-protocol-08#section-5.3)). 
+
+#### topic
+Similar to the old `collapse_key` on legacy GCM servers, this string will make the vendor show to the user only the last notification of this topic (cf. [protocol]((cf. [protocol](https://tools.ietf.org/html/draft-ietf-webpush-protocol-08#section-5.4)))).
+
+### Payload length and security
+Payload will be encrypted by the library. The maximum payload length is 4078 bytes (or ASCII characters).
+
+However, when you encrypt a string of a certain length, the resulting string will always have the same length,
+no matter how many times you encrypt the initial string. This can make attackers guess the content of the payload.
+In order to circumvent this, this library can add some null padding to the initial payload, so that all the input of the encryption process
+will have the same length. This way, all the output of the encryption process will also have the same length and attackers won't be able to 
+guess the content of your payload. The downside of this approach is that you will use more bandwidth than if you didn't pad the string.
+That's why the library provides the option to disable this security measure:
+
 ```php
 <?php
 
 use Minishlink\WebPush\WebPush;
 
-$webPush = new WebPush(); // default TTL is 4 weeks
-// send some important notifications...
-
-$webPush->setTTL(3600);
-// send some not so important notifications
-
-$webPush->setTTL(0);
-// send some trivial notifications
+$webPush = new WebPush();
+$webPush->setAutomaticPadding(false); // disable automatic padding
 ```
 
 ### Changing the browser client
@@ -141,7 +155,7 @@ use Minishlink\WebPush\WebPush;
 
 $client = new \Buzz\Client\Curl();
 $timeout = 20; // seconds
-$webPush = new WebPush(array(), null, $timeout, $client);
+$webPush = new WebPush(array(), array(), $timeout, $client);
 ```
 
 You have access to the inner browser if you want to configure it further.

src/Notification.php

@@ -25,12 +25,16 @@ class Notification
     /** @var string */
     private $userAuthToken;
 
-    public function __construct($endpoint, $payload, $userPublicKey, $userAuthToken)
+    /** @var array Options : TTL, urgency, topic **/
+    private $options;
+
+    public function __construct($endpoint, $payload, $userPublicKey, $userAuthToken, $options)
     {
         $this->endpoint = $endpoint;
         $this->payload = $payload;
         $this->userPublicKey = $userPublicKey;
         $this->userAuthToken = $userAuthToken;
+        $this->options = $options;
     }
 
     /**
@@ -64,4 +68,19 @@ public function getUserAuthToken()
     {
         return $this->userAuthToken;
     }
+
+    /**
+     * @param array $defaultOptions
+     * @return array
+     */
+    public function getOptions(array $defaultOptions = array())
+    {
+        $options = $this->options;
+        $options['TTL'] = array_key_exists('TTL', $options) ?  $options['TTL'] : $defaultOptions['TTL'];
+        $options['urgency'] = array_key_exists('urgency', $options) ? $options['urgency'] : $defaultOptions['urgency'];
+        $options['topic'] = array_key_exists('topic', $options) ? $options['topic'] : $defaultOptions['topic'];
+
+        return $options;
+    }
+
 }

src/WebPush.php

@@ -35,8 +35,8 @@ class WebPush
         'GCM' => self::GCM_URL,
     );
 
-    /** @var int Time To Live of notifications */
-    private $TTL;
+    /** @var array Default options : TTL, urgency, topic */
+    private $defaultOptions;
 
     /** @var bool Automatic padding of payloads, if disabled, trade security for bandwidth */
     private $automaticPadding = true;
@@ -48,14 +48,14 @@ class WebPush
      * WebPush constructor.
      *
      * @param array $apiKeys Some servers needs authentication. Provide your API keys here. (eg. array('GCM' => 'GCM_API_KEY'))
-     * @param int|null $TTL Time To Live of notifications, default being 4 weeks.
+     * @param array $defaultOptions TTL, urgency, topic
      * @param int|null $timeout Timeout of POST request
      * @param AbstractClient|null $client
      */
-    public function __construct(array $apiKeys = array(), $TTL = 2419200, $timeout = 30, AbstractClient $client = null)
+    public function __construct(array $apiKeys = array(), $defaultOptions = array(), $timeout = 30, AbstractClient $client = null)
     {
         $this->apiKeys = $apiKeys;
-        $this->TTL = $TTL;
+        $this->setDefaultOptions($defaultOptions);
 
         $client = isset($client) ? $client : new MultiCurl();
         $client->setTimeout($timeout);
@@ -72,17 +72,13 @@ public function __construct(array $apiKeys = array(), $TTL = 2419200, $timeout =
      * @param string|null $userPublicKey
      * @param string|null $userAuthToken
      * @param bool $flush If you want to flush directly (usually when you send only one notification)
-     *
+     * @param array $options Array with several options tied to this notification. If not set, will use the default options that you can set in the WebPush object.
      * @return array|bool Return an array of information if $flush is set to true and the queued requests has failed.
      *                    Else return true.
      * @throws \ErrorException
      */
-    public function sendNotification($endpoint, $payload = null, $userPublicKey = null, $userAuthToken = null, $flush = false)
+    public function sendNotification($endpoint, $payload = null, $userPublicKey = null, $userAuthToken = null, $flush = false, $options = array())
     {
-        if (isset($userAuthToken) && is_bool($userAuthToken)) {
-            throw new \ErrorException('The API has changed: sendNotification now takes the optional user auth token as parameter.');
-        }
-
         if(isset($payload)) {
             if (strlen($payload) > Encryption::MAX_PAYLOAD_LENGTH) {
                 throw new \ErrorException('Size of payload must not be greater than '.Encryption::MAX_PAYLOAD_LENGTH.' octets.');
@@ -93,7 +89,7 @@ public function sendNotification($endpoint, $payload = null, $userPublicKey = nu
 
         // sort notification by server type
         $type = $this->sortEndpoint($endpoint);
-        $this->notificationsByServerType[$type][] = new Notification($endpoint, $payload, $userPublicKey, $userAuthToken);
+        $this->notificationsByServerType[$type][] = new Notification($endpoint, $payload, $userPublicKey, $userAuthToken, $options);
 
         if ($flush) {
             $res = $this->flush();
@@ -190,6 +186,7 @@ private function prepareAndSend(array $notifications, $serverType)
             $payload = $notification->getPayload();
             $userPublicKey = $notification->getUserPublicKey();
             $userAuthToken = $notification->getUserAuthToken();
+            $options = $notification->getOptions($this->getDefaultOptions());
 
             if (isset($payload) && isset($userPublicKey) && isset($userAuthToken)) {
                 $encrypted = Encryption::encrypt($payload, $userPublicKey, $userAuthToken, $this->nativePayloadEncryptionSupport);
@@ -200,19 +197,27 @@ private function prepareAndSend(array $notifications, $serverType)
                     'Content-Encoding' => 'aesgcm',
                     'Encryption' => 'keyid="p256dh";salt="'.$encrypted['salt'].'"',
                     'Crypto-Key' => 'keyid="p256dh";dh="'.$encrypted['localPublicKey'].'"',
-                    'TTL' => $this->TTL,
                 );
 
                 $content = $encrypted['cipherText'];
             } else {
                 $headers = array(
                     'Content-Length' => 0,
-                    'TTL' => $this->TTL,
                 );
 
                 $content = '';
             }
 
+            $headers['TTL'] = $options['TTL'];
+
+            if (isset($options['urgency'])) {
+                $headers['Urgency'] = $options['urgency'];
+            }
+
+            if (isset($options['topic'])) {
+                $headers['Topic'] = $options['topic'];
+            }
+
             if ($serverType === 'GCM') {
                 $headers['Authorization'] = 'key='.$this->apiKeys['GCM'];
             }
@@ -278,42 +283,40 @@ public function setBrowser($browser)
     }
 
     /**
-     * @return int
+     * @return boolean
      */
-    public function getTTL()
+    public function isAutomaticPadding()
     {
-        return $this->TTL;
+        return $this->automaticPadding;
     }
 
     /**
-     * @param int $TTL
+     * @param boolean $automaticPadding
      *
      * @return WebPush
      */
-    public function setTTL($TTL)
+    public function setAutomaticPadding($automaticPadding)
     {
-        $this->TTL = $TTL;
+        $this->automaticPadding = $automaticPadding;
 
         return $this;
     }
 
     /**
-     * @return boolean
+     * @return array
      */
-    public function isAutomaticPadding()
+    public function getDefaultOptions()
     {
-        return $this->automaticPadding;
+        return $this->defaultOptions;
     }
 
     /**
-     * @param boolean $automaticPadding
-     *
-     * @return WebPush
+     * @param array $defaultOptions Keys 'TTL' (Time To Live, defaults 4 weeks), 'urgency', and 'topic'
      */
-    public function setAutomaticPadding($automaticPadding)
+    public function setDefaultOptions(array $defaultOptions)
     {
-        $this->automaticPadding = $automaticPadding;
-
-        return $this;
+        $this->defaultOptions['TTL'] = array_key_exists('TTL', $defaultOptions) ? $defaultOptions['TTL'] : 2419200;
+        $this->defaultOptions['urgency'] = array_key_exists('urgency', $defaultOptions) ? $defaultOptions['urgency'] : null;
+        $this->defaultOptions['topic'] = array_key_exists('topic', $defaultOptions) ? $defaultOptions['topic'] : null;
     }
 }