diff --git a/docs/book/messages.md b/docs/book/messages.md index 0de9475..733a5a0 100644 --- a/docs/book/messages.md +++ b/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); +``` diff --git a/src/FlashMessages.php b/src/FlashMessages.php index e910f88..f53defb 100644 --- a/src/FlashMessages.php +++ b/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) { diff --git a/src/FlashMessagesInterface.php b/src/FlashMessagesInterface.php index dfc1ceb..9e1f248 100644 --- a/src/FlashMessagesInterface.php +++ b/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. diff --git a/test/FlashMessagesTest.php b/test/FlashMessagesTest.php index ce2627f..a0eafa5 100644 --- a/test/FlashMessagesTest.php +++ b/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());