CakePHP flash messages 2.0

This is a topic often discussed. What is the best approach?
While I might not have the best, I sure have a fully working one since 2008 and CakePHP1.3. I still use it in all 2.x apps.
It is easy and does not require a lot of overhead.

Basically, it enhances the core one with the following features

• Different types possible (now in 2.x kind of in the core, as well, using elements)
• Multiple flash messages per type possible (with a max limit to avoid session flushing)
• Transient messages (via Configure) and real ones (via Session)
• Transient ones can also be fired from the views (to display some hint/info for this page) – although one should try to stick to the controller

Demo

sandbox/examples/messages

How does it work?

We attach the Common Component and the Common Helper to the AppController:

public $components = array(..., 'Tools.Common');
public $helpers = array(..., 'Tools.Common');

In our layouts we need to switch the default output to ours:

echo $this->Common->flash();

And we can use `em:

public function add() {
    ...
    if ($this->Entry->save()) {
        $this->Common->flashMessage('The Entry has been saved.', 'success');
    } else {
        $this->Common->flashMessage('The Entry could not be saved. Please check the form.', 'error');
    }
}

Styling

We style our flashmessages via CSS

div.flash-messages {
    width: 90%;
}
div.flash-messages div {
    padding: 10px;
    padding-left:40px;
}
div.flash-messages div.error {
    width:100%; border-style: solid; border-width:1px; border-color:#B84D17; 
    margin-right:2px; color:#000000; margin-bottom:8px;
    background: url(/img/css/layout/icon_error.gif) left center no-repeat;
    background-color:#F7C6A5;
}
div.flash-messages div.warning {
    width:100%; border-style: solid; border-width:1px; border-color:#D0C130; 
    margin-right:2px; color:#000000; margin-bottom:8px;
    background: url(/img/css/layout/icon_warning.gif) left center no-repeat;
    background-color:#F6F3A4;
}
div.flash-messages div.success {
    width:100%; border-style: solid; border-width:1px; border-color:#009900; 
    margin-right:2px; color:#000000; margin-bottom:8px;
    background: url(/img/css/layout/icon_success.gif) left center no-repeat;
    background-color:#A5F7A8;
}
div.flash-messages div.info {
    width:100%; border-style: solid; border-width:1px; border-color:#cccccc; 
    margin-right:2px; color:#000000; margin-bottom:8px;
    background: url(/img/css/layout/icon_info.gif) left center no-repeat;
    background-color:#ffffff;
}

Or any other layout for that matter. The images are small icons and also optional, of course 🙂

Transient flash messages

You can also put flash messages on top that are not stored in session but Configure (for this request only).
This can be useful if you don’t intend to redirect and don’t want them to show up if that happens.

From your controller:

$this->Common->transientFlashMessage('This page is currently being redesigned', 'info');

Or from your view ctp (even elements, blocks or the layout if it happens prior to the flash message output):

$this->Common->addFlashMessage('This page is under maintenance. It may be broken!', 'warning');

Output in a specific order or only specific types

You can filter the output, both in order and types:

// Using Common helper
echo $this->Common->flash(array('warning', 'error'));

In this case it would only output the warning and error messages, in this order (Usually the order is "error, warning, success, info").

Details

For details please the Wiki page.

Outview

It would probably be nice to add element support at some point. This would allow an easier approach to customization of those messages.

There are also quite a few CakePHP core tickets open regarding flash message enhancements – see this or this which might even lead to an own component for it some day.
But until then my approach will still be used in all my xx apps 🙂
So in 3.x there will be a Flash component and Flash helper to provide a clean way to produce flash messages. If they provide the same features my implementation currently does, will have to be investigated. But it will use templating which will sure be nice.

Update 2014-12

A FlashComponent and FlashHelper now replace the current way of handling flash messages. This helps to ease migration to 3.x at some point, as there this is also extracted from the Session classes.
As syntactic sugar you can directly use the types as methods now:

// Normal
$this->Flash->message('Yeah', 'success');

// Possible now
$this->Flash->success('Yeah');

// Same with
$this->Flash->warning('Careful');
$this->Flash->error('o_O');
$this->Flash->info('Some information');

2015-01 CakePHP 3

The documentation for 3.x can be found in the repo itself now: Docs. Check it out!

2016-10 CakePHP 3.3+

If you don’t want to have an own type "auth" for the AuthComponent flash error message, simply load your AuthComponent like this:

$this->loadComponent('Auth', 
    ['flash' => ['key' => 'flash', 'element' => 'error']]);

2020-03

This article is now replaced by the new one from 2020.