flashNow() now persists for zero hops by default. This breaks BC.

Signed-off-by: Tim Lieberman <[email protected]>

docs/book/messages.md

@@ -38,15 +38,15 @@ interface FlashMessagesInterface
     public function flash(string $key, $value, int $hops = 1) : void;
 
     /**
-     * Set a flash value with the given key, but allow access during this request.
+     * Set a flash value with the given key, visible to the current request.
      *
-     * Flash values are generally accessible only on subsequent requests;
-     * using this method, you may make the value available during the current
-     * request as well.
+     * Values set with this method are visible *only* in the current request; if 
+     * you want values to be visible in subsequent requests, you may pass a 
+     * positive integer as the third argument.
      *
      * @param mixed $value
      */
-    public function flashNow(string $key, $value, int $hops = 1) : void;
+     public function flashNow(string $key, $value, int $hops = 0) : void;
 
     /**
      * Retrieve a flash value.
@@ -161,12 +161,27 @@ one.
 ## Accessing messages in the current request
 
 When you create a flash message, it is available _in the next request_, but not
-the _current request_. If you want access to it in the current request as well,
-use the `flashNow()` method instead of `flash()`:
+the _current request_. If you want access to it in the current request, use the 
+`flashNow()` method instead of `flash()`:
 
 ```php
 $flashMessages->flashNow($messageName, $messageValue);
 ```
 
-The signature of this method is the same as for `flash()`, and allows you to
-optionally provide a `$hops` value as well.
+By default, messages set via `flashNow()` are visible _only_ in the current
+request. If you want your message to visible on subsequent requests, you may
+pass a positive integer `$hops` as the third argument:
+
+```php
+// Message will be visible both in the current request, and the next.
+$flashMessages->flashNow($messageName, $messageValue, 1);
+```
+
+The above is equivalent to calling both `flash()` and `flashNow()` with the same
+name and value arguments:
+
+```php
+// Message will be visible both in the current request, and the next.
+$flashMessages->flashNow($messageName, $messageValue);
+$flashMessages->flash($messageName, $messageValue);
+```

src/FlashMessages.php

@@ -86,18 +86,15 @@ public function flash(string $key, $value, int $hops = 1): void
     }
 
     /**
-     * Set a flash value with the given key, but allow access during this request.
+     * Set a flash value with the given key, visible in the current request.
      *
-     * Flash values are generally accessible only on subsequent requests;
-     * using this method, you may make the value available during the current
-     * request as well.
-     *
-     * If you want the value to be visible only in the current request, you may
-     * pass zero as the third argument.
+     * Values set by flashNow are not visible on subsequent requests by default.
+     * If you want want your value to be visible in subsequent requests, you may
+     * set pass a positive integer as the third argument.
      *
      * @param mixed $value
      */
-    public function flashNow(string $key, $value, int $hops = 1): void
+    public function flashNow(string $key, $value, int $hops = 0): void
     {
         $this->currentMessages[$key] = $value;
         if ($hops > 0) {

src/FlashMessagesInterface.php

@@ -42,15 +42,15 @@ public static function createFromSession(
     public function flash(string $key, $value, int $hops = 1): void;
 
     /**
-     * Set a flash value with the given key, but allow access during this request.
+     * Set a flash value with the given key, visible to the current request.
      *
-     * Flash values are generally accessible only on subsequent requests;
-     * using this method, you may make the value available during the current
-     * request as well.
+     * Values set with this method are visible *only* in the current request; if
+     * you want values to be visible in subsequent requests, you may pass a
+     * positive integer as the third argument.
      *
      * @param mixed $value
      */
-    public function flashNow(string $key, $value, int $hops = 1): void;
+    public function flashNow(string $key, $value, int $hops = 0): void;
 
     /**
      * Retrieve a flash value.

test/FlashMessagesTest.php

@@ -154,7 +154,39 @@ public function testFlashingAValueMakesItAvailableInNextSessionButNotFlashMessag
         $this->assertSame([], $flash->getFlashes());
     }
 
-    public function testFlashNowMakesValueAvailableBothInNextSessionAndCurrentFlashMessages()
+    public function testFlashNowMakesValueAvailableInCurrentMessagesOnlyByDefault()
+    {
+        $this->session
+            ->expects($this->once())
+            ->method('has')
+            ->with(FlashMessagesInterface::FLASH_NEXT)
+            ->willReturn(false);
+        $this->session
+            ->expects($this->never())
+            ->method('get')
+            ->with(FlashMessagesInterface::FLASH_NEXT, [])
+            ->willReturn([]);
+        $this->session
+            ->expects($this->never())
+            ->method('set')
+            ->with(
+                FlashMessagesInterface::FLASH_NEXT,
+                [
+                    'test' => [
+                        'value' => 'value',
+                        'hops'  => 0,
+                    ],
+                ]
+            );
+
+        $flash = FlashMessages::createFromSession($this->session);
+        $flash->flashNow('test', 'value');
+
+        $this->assertSame('value', $flash->getFlash('test'));
+        $this->assertSame(['test' => 'value'], $flash->getFlashes());
+    }
+
+    public function testFlashNowCanMakeValueAvailableBothInNextSessionAndCurrentFlashMessages()
     {
         $this->session
             ->expects($this->once())
@@ -180,7 +212,7 @@ public function testFlashNowMakesValueAvailableBothInNextSessionAndCurrentFlashM
             );
 
         $flash = FlashMessages::createFromSession($this->session);
-        $flash->flashNow('test', 'value');
+        $flash->flashNow('test', 'value', 1);
 
         $this->assertSame('value', $flash->getFlash('test'));
         $this->assertSame(['test' => 'value'], $flash->getFlashes());