1: <?php
2: /**
3: * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
4: * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
5: *
6: * Licensed under The MIT License
7: * For full copyright and license information, please see the LICENSE.txt
8: * Redistributions of files must retain the above copyright notice.
9: *
10: * @copyright Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
11: * @link https://cakephp.org CakePHP(tm) Project
12: * @since 3.0.0
13: * @license https://opensource.org/licenses/mit-license.php MIT License
14: */
15: namespace Cake\View\Helper;
16:
17: use Cake\View\Helper;
18: use UnexpectedValueException;
19:
20: /**
21: * FlashHelper class to render flash messages.
22: *
23: * After setting messages in your controllers with FlashComponent, you can use
24: * this class to output your flash messages in your views.
25: */
26: class FlashHelper extends Helper
27: {
28:
29: /**
30: * Used to render the message set in FlashComponent::set()
31: *
32: * In your template file: $this->Flash->render('somekey');
33: * Will default to flash if no param is passed
34: *
35: * You can pass additional information into the flash message generation. This allows you
36: * to consolidate all the parameters for a given type of flash message into the view.
37: *
38: * ```
39: * echo $this->Flash->render('flash', ['params' => ['name' => $user['User']['name']]]);
40: * ```
41: *
42: * This would pass the current user's name into the flash message, so you could create personalized
43: * messages without the controller needing access to that data.
44: *
45: * Lastly you can choose the element that is used for rendering the flash message. Using
46: * custom elements allows you to fully customize how flash messages are generated.
47: *
48: * ```
49: * echo $this->Flash->render('flash', ['element' => 'my_custom_element']);
50: * ```
51: *
52: * If you want to use an element from a plugin for rendering your flash message
53: * you can use the dot notation for the plugin's element name:
54: *
55: * ```
56: * echo $this->Flash->render('flash', [
57: * 'element' => 'MyPlugin.my_custom_element',
58: * ]);
59: * ```
60: *
61: * If you have several messages stored in the Session, each message will be rendered in its own
62: * element.
63: *
64: * @param string $key The [Flash.]key you are rendering in the view.
65: * @param array $options Additional options to use for the creation of this flash message.
66: * Supports the 'params', and 'element' keys that are used in the helper.
67: * @return string|null Rendered flash message or null if flash key does not exist
68: * in session.
69: * @throws \UnexpectedValueException If value for flash settings key is not an array.
70: */
71: public function render($key = 'flash', array $options = [])
72: {
73: $session = $this->_View->getRequest()->getSession();
74:
75: if (!$session->check("Flash.$key")) {
76: return null;
77: }
78:
79: $flash = $session->read("Flash.$key");
80: if (!is_array($flash)) {
81: throw new UnexpectedValueException(sprintf(
82: 'Value for flash setting key "%s" must be an array.',
83: $key
84: ));
85: }
86: $session->delete("Flash.$key");
87:
88: $out = '';
89: foreach ($flash as $message) {
90: $message = $options + $message;
91: $out .= $this->_View->element($message['element'], $message);
92: }
93:
94: return $out;
95: }
96:
97: /**
98: * Event listeners.
99: *
100: * @return array
101: */
102: public function implementedEvents()
103: {
104: return [];
105: }
106: }
107: