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:      * Used to render the message set in FlashComponent::set()
 30:      *
 31:      * In your template file: $this->Flash->render('somekey');
 32:      * Will default to flash if no param is passed
 33:      *
 34:      * You can pass additional information into the flash message generation. This allows you
 35:      * to consolidate all the parameters for a given type of flash message into the view.
 36:      *
 37:      * ```
 38:      * echo $this->Flash->render('flash', ['params' => ['name' => $user['User']['name']]]);
 39:      * ```
 40:      *
 41:      * This would pass the current user's name into the flash message, so you could create personalized
 42:      * messages without the controller needing access to that data.
 43:      *
 44:      * Lastly you can choose the element that is used for rendering the flash message. Using
 45:      * custom elements allows you to fully customize how flash messages are generated.
 46:      *
 47:      * ```
 48:      * echo $this->Flash->render('flash', ['element' => 'my_custom_element']);
 49:      * ```
 50:      *
 51:      * If you want to use an element from a plugin for rendering your flash message
 52:      * you can use the dot notation for the plugin's element name:
 53:      *
 54:      * ```
 55:      * echo $this->Flash->render('flash', [
 56:      *   'element' => 'MyPlugin.my_custom_element',
 57:      * ]);
 58:      * ```
 59:      *
 60:      * If you have several messages stored in the Session, each message will be rendered in its own
 61:      * element.
 62:      *
 63:      * @param string $key The [Flash.]key you are rendering in the view.
 64:      * @param array $options Additional options to use for the creation of this flash message.
 65:      *    Supports the 'params', and 'element' keys that are used in the helper.
 66:      * @return string|null Rendered flash message or null if flash key does not exist
 67:      *   in session.
 68:      * @throws \UnexpectedValueException If value for flash settings key is not an array.
 69:      */
 70:     public function render($key = 'flash', array $options = [])
 71:     {
 72:         $session = $this->_View->getRequest()->getSession();
 73: 
 74:         if (!$session->check("Flash.$key")) {
 75:             return null;
 76:         }
 77: 
 78:         $flash = $session->read("Flash.$key");
 79:         if (!is_array($flash)) {
 80:             throw new UnexpectedValueException(sprintf(
 81:                 'Value for flash setting key "%s" must be an array.',
 82:                 $key
 83:             ));
 84:         }
 85:         $session->delete("Flash.$key");
 86: 
 87:         $out = '';
 88:         foreach ($flash as $message) {
 89:             $message = $options + $message;
 90:             $out .= $this->_View->element($message['element'], $message);
 91:         }
 92: 
 93:         return $out;
 94:     }
 95: 
 96:     /**
 97:      * Event listeners.
 98:      *
 99:      * @return array
100:      */
101:     public function implementedEvents()
102:     {
103:         return [];
104:     }
105: }
106: