root/fMessaging.php

Class Resources

Revision 721, 6.2 kB (checked in by wbond, 5 months ago)

BackwardsCompatibilityBreak - Removed the $prefix parameter from the methods fSession::delete(), fSession::get() and fSession::set()

Fixed ticket #302 - added the method fSession::add()

Fixed ticket #303 - added a second parameter to fSession::setLength() and added fSession::enablePersistence()

LineHide Line Numbers
1 <?php
2 /**
3  * Provides session-based messaging for page-to-page communication
4  *
5  * @copyright  Copyright (c) 2007-2009 Will Bond
6  * @author     Will Bond [wb] <will@flourishlib.com>
7  * @license    http://flourishlib.com/license
8  *
9  * @package    Flourish
10  * @link       http://flourishlib.com/fMessaging
11  *
12  * @version    1.0.0b6
13  * @changes    1.0.0b6  Updated class to use new fSession API [wb, 2009-10-23]
14  * @changes    1.0.0b5  Made the `$recipient` parameter optional for all methods [wb, 2009-07-08]
15  * @changes    1.0.0b4  Added support for `'*'` and arrays of names to ::check() [wb, 2009-06-02]
16  * @changes    1.0.0b3  Updated class to use new fSession API [wb, 2009-05-08]
17  * @changes    1.0.0b2  Changed ::show() to accept more than one message name, or * for all messages [wb, 2009-01-12]
18  * @changes    1.0.0b   The initial implementation [wb, 2008-03-05]
19  */
20 class fMessaging
21 {
22     // The following constants allow for nice looking callbacks to static methods
23     const check     = 'fMessaging::check';
24     const create    = 'fMessaging::create';
25     const reset     = 'fMessaging::reset';
26     const retrieval = 'fMessaging::retrieval';
27     const show      = 'fMessaging::show';
28    
29    
30     /**
31     * Checks to see if a message exists of the name specified for the recipient specified
32     *
33     * @param  string $name         The name or array of names of the message(s) to check for, or `'*'` to check for any
34     * @param  string [$recipient]  The intended recipient
35     * @return boolean  If a message of the name and recipient specified exists
36     */
37     static public function check($name, $recipient=NULL)
38     {
39         if ($recipient === NULL) {
40             $recipient = '{default}';   
41         }
42        
43         // Check all messages if * is specified
44         if (is_string($name) && $name == '*') {
45             fSession::open();
46             $prefix = __CLASS__ . '::' . $recipient . '::';
47             $keys   = array_keys($_SESSION);
48             foreach ($keys as $key) {
49                 if (strpos($key, $prefix) === 0) {
50                     return TRUE;
51                 }
52             }
53             return FALSE;
54         }
55        
56         // Handle checking multiple messages
57         if (is_array($name)) {
58             foreach ($names as $name) {
59                 if (self::check($name, $recipient)) {
60                     return TRUE;   
61                 }
62             }
63             return FALSE;
64         }
65        
66         return fSession::get(__CLASS__ . '::' . $recipient . '::' . $name, NULL) !== NULL;
67     }
68    
69    
70     /**
71     * Creates a message that is stored in the session and retrieved by another page
72     *
73     * @param  string $name       A name for the message
74     * @param  string $recipient  The intended recipient - this may be ommitted
75     * @param  string $message    The message to send
76     * @param  string :$name
77     * @param  string :$message
78     * @return void
79     */
80     static public function create($name, $recipient, $message=NULL)
81     {                                 
82         // This allows for the $recipient parameter to be optional
83         if ($message === NULL) {
84             $message   = $recipient;
85             $recipient = '{default}';   
86         }
87        
88         fSession::set(__CLASS__ . '::' . $recipient . '::' . $name, $message);
89     }
90    
91    
92     /**
93     * Resets the data of the class
94     *
95     * @internal
96      *
97     * @return void
98     */
99     static public function reset()
100     {
101         fSession::clear(__CLASS__ . '::');
102     }
103    
104    
105     /**
106     * Retrieves and removes a message from the session
107     *
108     * @param  string $name       The name of the message to retrieve
109     * @param  string $recipient  The intended recipient
110     * @return string  The message contents
111     */
112     static public function retrieve($name, $recipient=NULL)
113     {
114         if ($recipient === NULL) {
115             $recipient = '{default}';   
116         }
117        
118         $key     = __CLASS__ . '::' . $recipient . '::' . $name;
119         $message = fSession::get($key, NULL);
120         fSession::delete($key);
121         return $message;
122     }
123    
124    
125     /**
126     * Retrieves a message, removes it from the session and prints it - will not print if no content
127     *
128     * The message will be printed in a `p` tag if it does not contain
129     * any block level HTML, otherwise it will be printed in a `div` tag.
130     *
131     * @param  mixed  $name       The name or array of names of the message(s) to show, or `'*'` to show all
132     * @param  string $recipient  The intended recipient
133     * @param  string $css_class  Overrides using the `$name` as the CSS class when displaying the message - only used if a single `$name` is specified
134     * @return boolean  If one or more messages was shown
135     */
136     static public function show($name, $recipient=NULL, $css_class=NULL)
137     {
138         if ($recipient === NULL) {
139             $recipient = '{default}';   
140         }
141        
142         // Find all messages if * is specified
143         if (is_string($name) && $name == '*') {
144             fSession::open();
145             $prefix = __CLASS__ . '::' . $recipient . '::';
146             $keys   = array_keys($_SESSION);
147             $name   = array();
148             foreach ($keys as $key) {
149                 if (strpos($key, $prefix) === 0) {
150                     $name[] = substr($key, strlen($prefix));
151                 }
152             }
153         }
154        
155         // Handle showing multiple messages
156         if (is_array($name)) {
157             $shown = FALSE;
158             $names = $name;
159             foreach ($names as $name) {
160                 $shown = fHTML::show(
161                     self::retrieve($name, $recipient),
162                     $name
163                 ) || $shown;
164             }
165             return $shown;
166         }
167        
168         // Handle a single message
169         return fHTML::show(
170             self::retrieve($name, $recipient),
171             ($css_class === NULL) ? $name : $css_class
172         );
173     }
174    
175    
176     /**
177     * Forces use as a static class
178     *
179     * @return fMessaging
180     */
181     private function __construct() { }
182 }
183  
184  
185  
186 /**
187  * Copyright (c) 2007-2009 Will Bond <will@flourishlib.com>
188  *
189  * Permission is hereby granted, free of charge, to any person obtaining a copy
190  * of this software and associated documentation files (the "Software"), to deal
191  * in the Software without restriction, including without limitation the rights
192  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
193  * copies of the Software, and to permit persons to whom the Software is
194  * furnished to do so, subject to the following conditions:
195  *
196  * The above copyright notice and this permission notice shall be included in
197  * all copies or substantial portions of the Software.
198  *
199  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
200  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
201  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
202  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
203  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
204  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
205  * THE SOFTWARE.
206  */