[BC] Rename sendNotification and add sendOneNotification (#218)

* [BC] Rename sendNotification and add sendOneNotification

* Fix doc Phpdoc

Author: Minishlink

README.md

@@ -71,7 +71,7 @@ $webPush = new WebPush();
 
 // send multiple notifications with payload
 foreach ($notifications as $notification) {
-    $webPush->sendNotification(
+    $webPush->queueNotification(
         $notification['subscription'],
         $notification['payload'] // optional (defaults null)
     );
@@ -93,12 +93,11 @@ foreach ($webPush->flush() as $report) {
 
 /**
  * send one notification and flush directly
- * @var \Generator<MessageSentReport> $sent
+ * @var MessageSentReport $report
  */
-$sent = $webPush->sendNotification(
+$report = $webPush->sendOneNotification(
     $notifications[0]['subscription'],
-    $notifications[0]['payload'], // optional (defaults null)
-    true // optional (defaults false)
+    $notifications[0]['payload'] // optional (defaults null)
 );
 ```
 
@@ -132,7 +131,7 @@ $auth = [
 ];
 
 $webPush = new WebPush($auth);
-$webPush->sendNotification(...);
+$webPush->queueNotification(...);
 ```
 
 In order to generate the uncompressed public and secret key, encoded in Base64, enter the following in your Linux bash:
@@ -184,7 +183,7 @@ $webPush = new WebPush([], $defaultOptions);
 $webPush->setDefaultOptions($defaultOptions);
 
 // or for one notification
-$webPush->sendNotification($subscription, $payload, $flush, ['TTL' => 5000]);
+$webPush->sendOneNotification($subscription, $payload, ['TTL' => 5000]);
 ```
 
 #### TTL
@@ -208,8 +207,9 @@ it as a parameter : `$webPush->flush($batchSize)`.
 
 ### Server errors
 You can see what the browser vendor's server sends back in case it encountered an error (push subscription expiration, wrong parameters...).
-`sendNotification()` (with `$flush` as `true`) and `flush()` **always** returns a [`\Generator`](http://php.net/manual/en/language.generators.php) with [`MessageSentReport`](https://github.com/web-push-libs/web-push-php/blob/master/src/MessageSentReport.php) objects, even if you just send one notification.
-To loop through the results, just pass it into `foreach`. You can also use [`iterator_to_array`](http://php.net/manual/en/function.iterator-to-array.php) to check the contents while debugging.
+
+* `sendOneNotification()` returns a [`MessageSentReport`](https://github.com/web-push-libs/web-push-php/blob/master/src/MessageSentReport.php)
+* `flush()` returns a [`\Generator`](http://php.net/manual/en/language.generators.php) with [`MessageSentReport`](https://github.com/web-push-libs/web-push-php/blob/master/src/MessageSentReport.php) objects. To loop through the results, just pass it into `foreach`. You can also use [`iterator_to_array`](http://php.net/manual/en/function.iterator-to-array.php) to check the contents while debugging.
 
 ```php
 <?php
@@ -346,7 +346,7 @@ require __DIR__ . '/path/to/vendor/autoload.php';
 ```
 
 ### I must use PHP 5.4 or 5.5. What can I do?
-You won't be able to send any payload, so you'll only be able to use `sendNotification($subscription)`.
+You won't be able to send any payload, so you'll only be able to use `sendOneNotification($subscription)` or `queueNotification($subscription)`.
 Install the library with `composer` using `--ignore-platform-reqs`.
 The workaround for getting the payload is to fetch it in the service worker ([example](https://github.com/Minishlink/physbook/blob/2ed8b9a8a217446c9747e9191a50d6312651125d/web/service-worker.js#L75)). 
 

src/WebPush.php

@@ -102,20 +102,16 @@ public function __construct(array $auth = [], array $defaultOptions = [], ?int $
     }
 
     /**
-     * Send a notification.
+     * Queue a notification. Will be sent when flush() is called.
      *
      * @param SubscriptionInterface $subscription
-     * @param string|null $payload If you want to send an array, json_encode it
-     * @param bool $flush If you want to flush directly (usually when you send only one notification)
+     * @param string|null $payload If you want to send an array or object, json_encode it
      * @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
      * @param array $auth Use this auth details instead of what you provided when creating WebPush
      *
-     * @return \Generator|MessageSentReport[]|true 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(SubscriptionInterface $subscription, ?string $payload = null, bool $flush = false, array $options = [], array $auth = [])
+    public function queueNotification(SubscriptionInterface $subscription, ?string $payload = null, array $options = [], array $auth = []): void
     {
         if (isset($payload)) {
             if (Utils::safeStrlen($payload) > Encryption::MAX_PAYLOAD_LENGTH) {
@@ -135,8 +131,20 @@ public function sendNotification(SubscriptionInterface $subscription, ?string $p
         }
 
         $this->notifications[] = new Notification($subscription, $payload, $options, $auth);
+    }
 
-        return false !== $flush ? $this->flush() : true;
+    /**
+     * @param SubscriptionInterface $subscription
+     * @param string|null $payload If you want to send an array or object, json_encode it
+     * @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
+     * @param array $auth Use this auth details instead of what you provided when creating WebPush
+     * @return MessageSentReport
+     * @throws \ErrorException
+     */
+    public function sendOneNotification(SubscriptionInterface $subscription, ?string $payload = null, array $options = [], array $auth = []): MessageSentReport
+    {
+        $this->queueNotification($subscription, $payload, $options, $auth);
+        return $this->flush()->current();
     }
 
     /**

tests/PushServiceTest.php

@@ -177,13 +177,9 @@ protected function createClosureTest($browserId, $browserVersion, $options)
                 $subscription = new Subscription($endpoint, $p256dh, $auth, $contentEncoding);
 
                 try {
-                    $sendResp = $this->webPush->sendNotification($subscription, $payload, true);
-                    $this->assertInstanceOf(\Generator::class, $sendResp);
-
-                    /** @var \Minishlink\WebPush\MessageSentReport $report */
-	                foreach ($sendResp as $report) {
-                    	$this->assertTrue($report->isSuccess());
-                    }
+                    $report = $this->webPush->sendOneNotification($subscription, $payload);
+                    $this->assertInstanceOf(\Minishlink\WebPush\MessageSentReport::class, $report);
+                    $this->assertTrue($report->isSuccess());
 
                     $dataString = json_encode([
                         'testSuiteId' => self::$testSuiteId,

tests/WebPushTest.php

@@ -93,13 +93,10 @@ public function notificationProvider(): array
      * @param string $payload
      * @throws ErrorException
      */
-    public function testSendNotification($subscription, $payload)
+    public function testSendOneNotification($subscription, $payload)
     {
-        $reports = $this->webPush->sendNotification($subscription, $payload, true);
-
-        foreach ($reports as $report) {
-            $this->assertTrue($report->isSuccess());
-        }
+        $report = $this->webPush->sendOneNotification($subscription, $payload);
+        $this->assertTrue($report->isSuccess());
     }
 
     /**
@@ -114,7 +111,7 @@ public function testSendNotificationBatch()
         $notifications = array_fill(0, $total, $notifications[0]);
 
         foreach ($notifications as $notification) {
-            $this->webPush->sendNotification($notification[0], $notification[1]);
+            $this->webPush->queueNotification($notification[0], $notification[1]);
         }
 
         $reports = $this->webPush->flush($batchSize);
@@ -127,16 +124,15 @@ public function testSendNotificationBatch()
     /**
      * @throws ErrorException
      */
-    public function testSendNotificationWithTooBigPayload()
+    public function testSendOneNotificationWithTooBigPayload()
     {
         $this->expectException('ErrorException');
         $this->expectExceptionMessage('Size of payload must not be greater than 4078 octets.');
 
         $subscription = new Subscription(self::$endpoints['standard'], self::$keys['standard']);
-        $this->webPush->sendNotification(
+        $this->webPush->sendOneNotification(
             $subscription,
-            str_repeat('test', 1020),
-            true
+            str_repeat('test', 1020)
         );
     }
 
@@ -146,14 +142,14 @@ public function testSendNotificationWithTooBigPayload()
     public function testFlush() {
 	    $subscription = new Subscription(self::$endpoints['standard']);
 
-	    $this->webPush->sendNotification($subscription);
-	    $this->assertNotEmpty(iterator_to_array($this->webPush->flush()));
+	    $report = $this->webPush->sendOneNotification($subscription);
+	    $this->assertFalse($report->isSuccess()); // it doesn't have VAPID
 
 	    // queue has been reset
 	    $this->assertEmpty(iterator_to_array($this->webPush->flush()));
 
-	    $this->webPush->sendNotification($subscription);
-	    $this->assertNotEmpty(iterator_to_array($this->webPush->flush()));
+        $report = $this->webPush->sendOneNotification($subscription);
+        $this->assertFalse($report->isSuccess());  // it doesn't have VAPID
 
 	    $nonExistantSubscription = Subscription::create([
 		    'endpoint'        => 'https://fcm.googleapis.com/fcm/send/fCd2-8nXJhU:APA91bGi2uaqFXGft4qdolwyRUcUPCL1XV_jWy1tpCRqnu4sk7ojUpC5gnq1PTncbCdMq9RCVQIIFIU9BjzScvjrDqpsI7J-K_3xYW8xo1xSNCfge1RvJ6Xs8RGL_Sw7JtbCyG1_EVgWDc22on1r_jozD8vsFbB0Fg',
@@ -163,9 +159,9 @@ public function testFlush() {
 	    ]);
 
 	    // test multiple requests
-	    $this->webPush->sendNotification($nonExistantSubscription, json_encode(['test' => 1]));
-	    $this->webPush->sendNotification($nonExistantSubscription, json_encode(['test' => 2]));
-	    $this->webPush->sendNotification($nonExistantSubscription, json_encode(['test' => 3]));
+	    $this->webPush->queueNotification($nonExistantSubscription, json_encode(['test' => 1]));
+	    $this->webPush->queueNotification($nonExistantSubscription, json_encode(['test' => 2]));
+	    $this->webPush->queueNotification($nonExistantSubscription, json_encode(['test' => 3]));
 
 	    /** @var \Minishlink\WebPush\MessageSentReport $report */
 	    foreach ($this->webPush->flush() as $report) {
@@ -187,10 +183,10 @@ public function testFlushEmpty(): void {
 	public function testCount(): void {
 		$subscription = new Subscription(self::$endpoints['standard']);
 
-		$this->webPush->sendNotification($subscription);
-		$this->webPush->sendNotification($subscription);
-		$this->webPush->sendNotification($subscription);
-		$this->webPush->sendNotification($subscription);
+		$this->webPush->queueNotification($subscription);
+		$this->webPush->queueNotification($subscription);
+		$this->webPush->queueNotification($subscription);
+		$this->webPush->queueNotification($subscription);
 
 		$this->assertEquals(4, $this->webPush->countPendingNotifications());
     }