Flashing Messages

Flash messages are used to notify the user about the state of actions he/she made or simply show information to the users. These kind of messages can be generated using this component.

Adapters

This component makes use of adapters to define the behavior of the messages after being passed to the Flasher:

Adapter	Description	API
Direct	Directly outputs the messages passed to the flasher	Phalcon\Flash\Direct
Session	Temporarily stores the messages in session, then messages can be printed in the next request	Phalcon\Flash\Session

Usage

Usually the Flash Messaging service is requested from the services container, if you’re using Phalcon\DI\FactoryDefault then Phalcon\Flash\Direct is automatically registered as “flash” service:

//Set up the flash service
$di->set('flash', function() {
    return new \Phalcon\Flash\Direct();
});

This way, you can use it in controllers or views by injecting the service in the required scope:

class PostsController extends \Phalcon\Mvc\Controller
{

    public function indexAction()
    {

    }

    public function saveAction()
    {
        $this->flash->success("The post was correctly saved!");
    }

}

There are four built-in message types supported:

$this->flash->error("too bad! the form had errors");
$this->flash->success("yes!, everything went very smoothly");
$this->flash->notice("this a very important information");
$this->flash->warning("best check yo self, you're not looking too good.");

You can add messages with your own types:

$this->flash->message("debug", "this is debug message, you don't say");

Printing Messages

Messages sent to the flash service are automatically formatted with html:

<div class="errorMessage">too bad! the form had errors</div>
<div class="successMessage">yes!, everything went very smoothly</div>
<div class="noticeMessage">this a very important information</div>
<div class="warningMessage">best check yo self, you're not looking too good.</div>

As you can see, CSS classes are added automatically to the DIVs. These classes allow you to define the graphical presentation of the messages in the browser. The CSS classes can be overridden, for example, if you’re using Twitter bootstrap, classes can be configured as:

//Register the flash service with custom CSS classes
$di->set('flash', function(){
    $flash = new \Phalcon\Flash\Direct(array(
        'error' => 'alert alert-error',
        'success' => 'alert alert-success',
        'notice' => 'alert alert-info',
    ));
    return $flash;
});

Then the messages would be printed as follows:

<div class="alert alert-error">too bad! the form had errors</div>
<div class="alert alert-success">yes!, everything went very smoothly</div>
<div class="alert alert-info">this a very important information</div>

Implicit Flush vs. Session

Depending on the adapter used to send the messages, it could be producing output directly, or be temporarily storing the messages in session to be shown later. When should you use each? That usually depends on the type of redirection you do after sending the messages. For example, if you make a “forward” is not necessary to store the messages in session, but if you do a HTTP redirect then, they need to be stored in session:

class ContactController extends \Phalcon\Mvc\Controller
{

    public function indexAction()
    {

    }

    public function saveAction()
    {

        //store the post

        //Using direct flash
        $this->flash->success("Your information was stored correctly!");

        //Forward to the index action
        return $this->dispatcher->forward(array("action" => "index"));
    }

}

Or using a HTTP redirection:

class ContactController extends \Phalcon\Mvc\Controller
{

    public function indexAction()
    {

    }

    public function saveAction()
    {

        //store the post

        //Using session flash
        $this->flashSession->success("Your information was stored correctly!");

        //Make a full HTTP redirection
        return $this->response->redirect("contact/index");
    }

}

In this case you need to manually print the messages in the corresponding view:

<!-- app/views/contact/index.phtml -->

<p><?php $this->flashSession->output() ?></p>

The attribute ‘flashSession’ is how the flash was previously set into the dependency injection container. You need to start the session first to successfully use the flashSession messenger.