Yii Flash Messages: tips and best practices

Flash messages are a way to inform uses of actions that have just taken place in an application. Some common uses are to display action confirmation, warn users about potentially dangerous actions and so on.

flash message example (success)

Yii framework provides out of the box support for flash messages and they're very useful.

HEADS-UP: This post is about Yii 1.1.x! Things seem to be different in 2.0

For example, to inform users that a particular action has been successfully completed, you could do this:

<?php
// delete a model, for instance
$car = Car::findByPk(1);
if($car->delete()){
    Yii::app()->user->setFlash('success','The car was successfully deleted');
}else{
    // do something else, maybe display errors
}

To log a user out and display a flash message about it, you have to do something like:

<?php
    Yii::app()->user->logout();
    // you need a session to be open to display flash messages so, since we've just killed
    // the current session, we need to create a dummy session.
    Yii::app()->session->open();
    Yii::app()->user->setFlash('You have been successfully logged out');

more info

Flash messages are different from session data in that flash messages only last for one request/response cycle

• From my experience, it's better to place the code that displays flash messages inside the #content div, rather than inside the #container div and outside the #content div because then, if any messages get shown, only the content div will be shifted down, leaving any columns untouched.

Buttons and links in Flash-message divs

• If you are going to put extra actions in the Flash Message <div>s, a good principle to follow is: links for GET actions (mainly redirecting and viewing data, i.e. no side-effects) and buttons for POST actions (actions that will change the state of the system, for example creating or deleting a model).

• If you're using different coloured flash messages to convey different messages, this is one suggestion of a pattern to follow:

  • Success Messages to tell the user that an action has been successfully completed; include here links and/or buttons for actions that usually follow the operation the user has just done;
  • Error Messages to tell the user that his/her previous action didn't succeed for some reason (inform the reason and maybe offer a button inside the flash div containing links to help pages or buttons to suggest possible actions);

• Warning messages to tell the user that he/she should double check he has made the correct decision (think of how compilers used to warn us when we used to perform variable assignment inside an if statement?) While not strictly wrong, that was probably not what you had in mind.

• Notices to show the user some other links/actions he/she might want to might after completing an action and/or say something that's not terribly important and, if missed, will not cause any harm.

Do keep in mind that you don't necessarily need to employ only one flash message per page; You could very well display both a success (green) and a notice/suggestion (blue) flash message on the same screen.