diff --git a/docs/book/messages.md b/docs/book/messages.md index 0de9475..1aecc2b 100644 --- a/docs/book/messages.md +++ b/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); +``` diff --git a/src/FlashMessages.php b/src/FlashMessages.php index c2d65ec..e910f88 100644 --- a/src/FlashMessages.php +++ b/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); + } } /** diff --git a/test/FlashMessagesTest.php b/test/FlashMessagesTest.php index 530f9bc..a16fcdf 100644 --- a/test/FlashMessagesTest.php +++ b/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); }