Flash messages are short-lived messages that are written during one request and consumed during a later request.

They are commonly used after a redirect:

• “Your profile has been saved.”
• “Please sign in before continuing.”
• “That item has been removed from your basket.”

¶Create a Flash object

Flash works with a SessionStoreInterface.

use GT\Session\Flash;
use GT\Session\Session;

function example(Session $session):void {
	$flash = new Flash($session->getStore("flash", true));
}

Using a dedicated flash store keeps flash message data away from other session data.

¶Put a message

$flash->put("success", "Your profile has been saved.");

Internally, messages are stored in a queue under queue.<name>.

¶Consume a message

$flashStore = $session->getStore("flash", true);
$flash = new Flash($flashStore);

if($flashStore->contains("queue.success")) {
	$message = $flash->consume("success");

	if($message) {
		echo $message->message;
	}
}

consume() removes one message from the queue and returns a FlashMessage.

FlashMessage has two read-only properties:

• name
• message

¶Multiple messages with the same name

Messages with the same name are queued in order.

$flash->put("notice", "First message");
$flash->put("notice", "Second message");

echo $flash->consume("notice")?->message; // First message
echo $flash->consume("notice")?->message; // Second message
echo $flash->consume("notice")?->message; // null

When an existing queue is empty, consume() removes the queue from the session and returns null.

[!IMPORTANT] consume() expects the named queue to exist. If we are not sure a message has been queued, check the underlying flash store with contains("queue.<name>") before consuming it.

¶A redirect example

use GT\Session\Flash;
use GT\Session\Session;

function do_save(Session $session):void {
	$flash = new Flash($session->getStore("flash", true));
	$flash->put("success", "Saved.");

	header("Location: /account");
}

function go(Session $session):void {
	$flashStore = $session->getStore("flash", true);
	$flash = new Flash($flashStore);

	if(!$flashStore->contains("queue.success")) {
		return;
	}

	$message = $flash->consume("success");

	if($message) {
		echo $message->message;
	}
}

[!NOTE] WebEngine applications often redirect after do_*() functions. Flash messages fit that flow because the message can be written before the redirect and displayed on the next page load.

---

Next, see the class-level summary in the API reference.