【CakePHP】フラッシュメッセージの動きを把握し、よくあるトラブルと戦う。

最近、ささみの燻製にはまりつつある常時減量中のfukasawaです。こんにちは。
スモークチーズみたいな味で、食べごたえもあって美味しいです。どこのスーパーにも置いているわけではないようなのですが、サラダチキンに飽きてしまった方は見かけたら是非試してみてください。

さて、CakePHPには１回限りの通知をユーザに表示するフラッシュメッセージという機能があります。例えば、ユーザがブログ記事を投稿した際に「投稿完了しました。」のようなメッセージを表示する際に便利な機能なのですが、使用していると「関係のない画面にメッセージが表示された」とか「メッセージを表示して欲しいタイミングで表示されない」といったトラブルに悩まされることがあります。 そのようなトラブルに遭遇した際、フラッシュメッセージの動きを把握していないと何処に原因があるのかを特定できず、解決するまでに時間がかかってしまったりといった状況に陥りがちです。
今回はそのようなトラブルに備えるべく、フラッシュメッセージの動きと、よくあるトラブルにどう対処したらよいかをザックリと見てみたいと思います。

※CakePHP バージョン2.6.3 を使用して検証しています。

1. フラッシュメッセージの基本的な動きについて

フラッシュメッセージは「メッセージのセット」→「セットされたメッセージの表示（＆削除）」がワンセットになっています。

サンプルを見てみましょう。

1.SessionComponent::setFlash()を使用しメッセージをセット

【Controller】

public $components = array('Session'); // SessionComponentを使用するように設定

...

$this->Session->setFlash('登録が完了しました！'); //メッセージをセット

2.セットしたメッセージを SessionHelper::flash() を使用して取り出す。

【View】

<?php echo $this->Session->flash();   //メッセージを取り出して表示 ?>

SessionHelper::flash()の役目はメッセージを取り出すところまでです。取り出したメッセージを表示するときはecho()等で出力してあげる必要があります。（バージョン1.2以前は勝手にecho()してくれていました。）

2. セットされたメッセージはどこに格納されるのか

SessionComponentとSessionHelperを使用しているのでお察しのことと思いますが、セッションに"Message.●●●"というキーで格納されます。

フラッシュメッセージという名前で内部の処理が若干隠蔽されているように感じますが、中ではCakeSessionを使用してセッションにメッセージを書き込んだり、読み込んだりといった事をしています。
なので、例えばSessionComponent::setFlash()で設定したメッセージを2回以上使い回したい場合などは、SessionHelper::flash()で消されてしまう前にCakeSession::read()でセットしたメッセージを読み込むといった事ができなくも無いのです。（あまりしないとは思いますが。）

3. フラッシュメッセージの引数

フラッシュメッセージの引数についても簡単に見ておきます。

SessionComponent::setFlash()

SessionComponent::setFlash(string $message, string $element = 'default', array $params = array(), string $key = 'flash')

$message	セットしたいメッセージ文
$element	どのエレメントを使用してメッセージを表示するか ("test_element"を指定すると、/app/View/Elements/test_element.ctpが使用されます。)
$params	SessionHelper::flash()に渡すパラメータを指定します。 $params['test_val'] という値を格納しておくと、$elementで指定したエレメント内で $test_val という形で参照できます。 SessionHelper::flash()では下記のパラメータを指定することができるのですが、setFlash()のタイミングで事前にセットしておくことができます。 $params['params']['class'] $params['params']['plugin']
$key	メッセージのキーを設定。（デフォルトは'flash'） ※例えば"regist"という値を$keyに指定すると"Message.regist"というキーでセッションにメッセージが格納されます

SessionHelper::flash()

SessionHelper::flash(string $key = 'flash', array $params = array())

$key	メッセージのキーを指定。対になるSessionComponent::setFlash()で指定した$keyと同じ値を指定します。
$params	パラメータを指定 $params['element'] : 使用するエレメントを指定。 $params['params']：追加のパラメータを指定します。SessionComponent::setFlash()で$paramsを指定していた場合はマージされます $params['params']['class'] : エレメントにデフォルト値の'default'が指定されている場合、flash()すると '<div id="' . $key . 'Message" class="' . $class . '">' . $message . '</div>' という形式でメッセージが出力されます。この$classに指定するクラス名を指定します。 $params['params']['plugin']: プラグインの中のエレメントを使用したい場合に指定します。 例えば、下記のような引数を渡してflash()を実行した場合、/app/Plugin/Test/View/Elements/test_element.ctpというエレメントが使用されます。 $this->Session->flash('flash', array('element' => 'test_element', 'params' => array('plugin' => 'Test') );
※SessionComponent::setFlash()の引数で $element $params['params']['class'] $params['params']['plugin'] を指定していても、SessionHelper::flash()の$paramsで $params['element'] $params['params']['class'] $params['params']['plugin'] を指定している場合は、それぞれの値で上書きされるので注意が必要です。

4. よくあるトラブルと解決の観点

ありそうなトラブルと、解決の観点についてざっくりと見てみます。

フラッシュメッセージは基本的に"Message.●●●"というキーでセッション中に格納されているので、デバッガを使用している人はデバッガで、プリントデバッグ派の人はdebug($this->session->read("Message.●●●"))等でセットされている値を追いながら対処することになると思います。

関係の無い画面でメッセージが表示されてしまう

メッセージが表示されない

異なるエレメントを使用して出力されている

まとめ

ルールを決めて使用することで、トラブルも事前に回避できそうです。