Merge 3513492 into 460b5ad

docs/book/messages.md

@@ -136,6 +136,10 @@ the flash message will persist for. The default value is `1`, indicating a
 single hop. This value is provided when you call `flash()` as an optional third
 argument.
 
+The `$hops` value passed to `flash()` must be greater than zero. Passing a value
+less than one will result in `flash()` throwing an exception of type
+`Mezzio\Flash\Exception\InvalidHopsValueException`.
+
 To have a message persist for three "hops", you might call `flash()` as follows:
 
 ```php
@@ -169,4 +173,10 @@ $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.
+optionally provide a `$hops` value as well. Unlike `flash()`, `flashNow()` will
+accept a value of zero for `$hops`, which is useful if you want your message to
+be visible _exclusively_ in the current request.
+
+```php
+$flashMessages->flashNow($messageName, 'One night (request) only!', 0);
+```

src/FlashMessages.php

@@ -92,12 +92,17 @@ public function flash(string $key, $value, int $hops = 1): void
      * 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.
+     *
      * @param mixed $value
      */
     public function flashNow(string $key, $value, int $hops = 1): void
     {
         $this->currentMessages[$key] = $value;
-        $this->flash($key, $value, $hops);
+        if ($hops > 0) {
+            $this->flash($key, $value, $hops);
+        }
     }
 
     /**

test/FlashMessagesTest.php

@@ -365,6 +365,24 @@ public function testCreationAggregatesThrowsExceptionIfInvalidNumberOfHops()
                 $this->anything()
             );
 
+        $flash = FlashMessages::createFromSession($this->session);
+        $flash->flash('test', 'value', 0);
+    }
+
+    public function testFlashNowAcceptsZeroHops()
+    {
+        $flash = FlashMessages::createFromSession($this->session);
+        $flash->flashNow('test', 'value', 0);
+
+        $this->assertSame('value', $flash->getFlash('test'));
+    }
+
+    public function testFlashNowWithZeroHopsShouldNotSetValueToSession()
+    {
+        $this->session
+            ->expects($this->never())
+            ->method('set');
+
         $flash = FlashMessages::createFromSession($this->session);
         $flash->flashNow('test', 'value', 0);
     }