A CakePHP Flash plugin for more powerful flash messages
PHP Shell
Latest commit 577d583 Feb 17, 2017 @dereuromark gitignore

README.md

CakePHP Flash Plugin

Build Status Coverage Status Latest Stable Version Minimum PHP Version License Total Downloads Coding Standards

A plugin for more powerful flash messages in your CakePHP apps.

This branch is for CakePHP 3.x

Features

  • AJAX header support
  • Limit of messages per stack key
  • Transient flash message support (non persistent, current request only)
  • By default 4 types (one more): error, warning, success, info
  • Ordered output (error, warning, success, info) and output filtering per type

Install

Run

composer require dereuromark/cakephp-flash

Setup

Enable the plugin in your config/bootstrap.php or call

bin/cake plugin load Flash

You can simply modify the existing config entries in your config/app.php:

    'Flash' => [
        ...
    ],

Include the component

In your AppController:

public function initialize() {
    parent::initialize();

    $this->loadComponent('Flash.Flash');
}

Include the helper

public function initialize() {
    $this->loadHelper('Flash.Flash');
}

Your layout does not need any modification, the included helper call is the same as with the core one:

<?= $this->Flash->render() ?>

Usage

Anywhere in your controller layer you can now use

$this->Flash->success('Yeah');
// or
$this->Flash->error('Oh <b>NO</b>', ['escape' => false]);

For transient messages:

$this->Flash->transientMessage('I am not persisted in session');

In your view you can also add transient flash messages:

$this->Flash->addTransientMessage('Only for this request');
$this->Flash->addTransientMessage('Oh oh', ['type' => 'error']);

Note: Do not try to add anything in the layout below the render() call as that would not be included anymore.

If you want to just output a message anywhere in your template (like a warning block):

echo $this->message('Hey, I am an info block');

Rendering each type in a separate process

The following would only render (and remove) the error messages:

<?= $this->Flash->render('flash', ['types' => ['error']]) ?>

Customization

Component Options

Option Description
limit Max message limit per key (first in, first out), defaults to 10.
headerKey Header key for AJAX responses, set to empty string to deactivate AJAX response.

as well as the CakePHP core component options.

Helper Options

Option Description
limit Max message limit per key (first in, first out), defaults to 10.
order Order of output, types default to ['error', 'warning', 'success', 'info'], all others are rendered last.

Flash layouts

You should have default.ctp, error.ctp, warning.ctp, success.ctp, and info.ctp templates.

The src/Template/Element/Flash/error.ctp could look like this:

<?php
if (!isset($params['escape']) || $params['escape'] !== false) {
    $message = h($message);
}
?>
<div class="alert alert-danger"><?= $message ?></div>

You can copy and adjust the existing ones from the tests/TestApp/Template/Element/Flash/ folder (bootstrap) or from the cakephp/app repo (foundation).