Flash messages API

Instantiate a flash message

Creating a flash message is achieved by instantiating an object of class \TYPO3\CMS\Core\Messaging\FlashMessage:

EXT:some_extension/Classes/Controller/SomeController.php
use TYPO3\CMS\Core\Messaging\FlashMessage;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;

// FlashMessage($message, $title = '', $severity = ContextualFeedbackSeverity::OK, $storeInSession = false)
$message = GeneralUtility::makeInstance(FlashMessage::class,
   'My message text',
   'Message Header',
   ContextualFeedbackSeverity::WARNING,
   true
);
$message

The text of the message

$title

[optional] the header

$severity

[optional] the severity (default: ContextualFeedbackSeverity::OK)

$storeInSession

[optional] true: store in the session or false: store only in the \TYPO3\CMS\Core\Messaging\FlashMessageQueue object. Storage in the session should be used if you need the message to be still present after a redirection (default: false).

Flash messages severities

Changed in version 12.0.

The severity is defined by using the \TYPO3\CMS\Core\Type\ContextualFeedbackSeverity enumeration:

  • ContextualFeedbackSeverity::NOTICE for notifications

  • ContextualFeedbackSeverity::INFO for information messages

  • ContextualFeedbackSeverity::OK for success messages

  • ContextualFeedbackSeverity::WARNING for warnings

  • ContextualFeedbackSeverity::ERROR for errors

Deprecated since version 12.0: In TYPO3 versions up to 11.5 class constants from \TYPO3\CMS\Core\Messaging\FlashMessage must be used:

  • FlashMessage::NOTICE for notifications

  • FlashMessage::INFO for information messages

  • FlashMessage::OK for success messages

  • FlashMessage::WARNING for warnings

  • FlashMessage::ERROR for errors

One can also use the class constants of FlashMessage if an extension should remain compatible with TYPO3 v12 and older versions.

The class constants will be removed in a future version of TYPO3.

Add a flash message to the queue

In backend modules you can then make that message appear on top of the module after a page refresh or the rendering of the next page request or render it on your own where ever you want.

This example adds the flash message at the top of modules when rendering the next request:

EXT:my_extension/Classes/Controller/SomeController.php
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Core\Messaging\FlashMessageService;

$flashMessageService = GeneralUtility::makeInstance(FlashMessageService::class);
$messageQueue = $flashMessageService->getMessageQueueByIdentifier();
$messageQueue->addMessage($message);

The message is added to the queue and then the template class calls \TYPO3\CMS\Core\Messaging\FlashMessageQueue::renderFlashMessages() which renders all messages from the queue as inline flash messages. Here's how such a message looks like in a module:

../../_images/FlashMessagesExample.png

A typical (success) message shown at the top of a module

This shows flash messages with 2 types of rendering mechanisms:

  • several flash messages are displayed inline

  • and an additional flash message ("Record count") is rendered as top-right notification (which automatically disappear after a short delay).

New in version 12.0: FlashMessageQueue::NOTIFICATION_QUEUE has been added in TYPO3 v12 to provide a simple mechanism to add flash messages (from PHP code) to be displayed as notifications on the top-right edge of the backend. Previously, this had to be implemented in JavaScript (e.g. Notification.success()), which is also still possible, see JavaScript-based flash messages (Notification API).

Use the FlashMessageQueue::NOTIFICATION_QUEUE to submit a flash message as top-right notifications, instead of inline:

EXT:my_extension/Classes/Controller/MyController.php
use TYPO3\CMS\Core\Messaging\FlashMessage;
use TYPO3\CMS\Core\Messaging\FlashMessageQueue;
use TYPO3\CMS\Core\Messaging\FlashMessageService;
use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$flashMessageService = GeneralUtility::makeInstance(FlashMessageService::class);
$notificationQueue = $flashMessageService->getMessageQueueByIdentifier(
    FlashMessageQueue::NOTIFICATION_QUEUE
);
$flashMessage = GeneralUtility::makeInstance(
    FlashMessage::class,
    'I am a message rendered as notification',
    'Hooray!',
    ContextualFeedbackSeverity::OK
);
$notificationQueue->enqueue($flashMessage);

The recommended way to show flash messages is to use the Fluid ViewHelper <f:flashMessages />. This ViewHelper works in any context because it use the FlashMessageRendererResolver class to find the correct renderer for the current context.