root/fCookie.php

Class Resources

Revision 717, 9.0 kB (checked in by wbond, 5 months ago)

Fixed ticket #304 - added fCookie::delete()

LineHide Line Numbers
1 <?php
2 /**
3  * Provides a consistent cookie API, HTTPOnly compatibility with older PHP versions and default parameters
4  *
5  * @copyright  Copyright (c) 2008-2009 Will Bond, others
6  * @author     Will Bond [wb] <will@flourishlib.com>
7  * @author     Nick Trew [nt]
8  * @license    http://flourishlib.com/license
9  *
10  * @package    Flourish
11  * @link       http://flourishlib.com/fCookie
12  *
13  * @version    1.0.0b3
14  * @changes    1.0.0b3  Added the ::delete() method [nt+wb, 2009-09-30]
15  * @changes    1.0.0b2  Updated for new fCore API [wb, 2009-02-16]
16  * @changes    1.0.0b   The initial implementation [wb, 2008-09-01]
17  */
18 class fCookie
19 {
20     // The following constants allow for nice looking callbacks to static methods
21     const delete             = 'fCookie::delete';
22     const get                = 'fCookie::get';
23     const reset              = 'fCookie::reset';
24     const set                = 'fCookie::set';
25     const setDefaultDomain   = 'fCookie::setDefaultDomain';
26     const setDefaultExpires  = 'fCookie::setDefaultExpires';
27     const setDefaultHTTPOnly = 'fCookie::setDefaultHTTPOnly';
28     const setDefaultPath     = 'fCookie::setDefaultPath';
29     const setDefaultSecure   = 'fCookie::setDefaultSecure';
30    
31    
32     /**
33     * The default domain to set for cookies
34     *
35     * @var string
36     */
37     static private $default_domain = NULL;
38    
39     /**
40     * The default expiration date to set for cookies
41     *
42     * @var string|integer
43     */
44     static private $default_expires = NULL;
45    
46     /**
47     * If cookies should default to being http-only
48     *
49     * @var boolean
50     */
51     static private $default_httponly = FALSE;
52    
53     /**
54     * The default path to set for cookies
55     *
56     * @var string
57     */
58     static private $default_path = NULL;
59    
60     /**
61     * If cookies should default to being secure-only
62     *
63     * @var boolean
64     */
65     static private $default_secure = FALSE;
66    
67    
68     /**
69     * Deletes a cookie - uses default parameters set by the other set methods of this class
70     *
71     * @param  string  $name    The cookie name to delete
72     * @param  string  $path    The path of the cookie to delete
73     * @param  string  $domain  The domain of the cookie to delete
74     * @param  boolean $secure  If the cookie is a secure-only cookie
75     * @return void
76     */
77     static public function delete($name, $path=NULL, $domain=NULL, $secure=NULL)
78     {
79         self::set($name, '', time() - 86400, $path, $domain, $secure);
80     }
81    
82    
83     /**
84     * Gets a cookie value from `$_COOKIE`, while allowing a default value to be provided
85     *
86     * @param  string $name           The name of the cookie to retrieve
87     * @param  mixed  $default_value  If there is no cookie with the name provided, return this value instead
88     * @return mixed  The value
89     */
90     static public function get($name, $default_value=NULL)
91     {
92         if (isset($_COOKIE[$name])) {
93             $value = fUTF8::clean($_COOKIE[$name]);
94             if (get_magic_quotes_gpc()) {
95                 $value = stripslashes($value);
96             }
97             return $value;
98         }
99         return $default_value;
100     }
101    
102    
103     /**
104     * Resets the configuration of the class
105     *
106     * @internal
107      *
108     * @return void
109     */
110     static public function reset()
111     {
112         self::$default_domain   = NULL;
113         self::$default_expires  = NULL;
114         self::$default_httponly = FALSE;
115         self::$default_path     = NULL;
116         self::$default_secure   = FALSE;
117     }
118    
119    
120     /**
121     * Sets a cookie to be sent back to the browser - uses default parameters set by the other set methods of this class
122     *
123     * The following methods allow for setting default parameters for this method:
124     *   
125     *  - ::setDefaultExpires():  Sets the default for the `$expires` parameter
126     *  - ::setDefaultPath():     Sets the default for the `$path` parameter
127     *  - ::setDefaultDomain():   Sets the default for the `$domain` parameter
128     *  - ::setDefaultSecure():   Sets the default for the `$secure` parameter
129     *  - ::setDefaultHTTPOnly(): Sets the default for the `$httponly` parameter
130     *
131     * @param  string         $name      The name of the cookie to set
132     * @param  mixed          $value     The value of the cookie to set
133     * @param  string|integer $expires   A relative string to be interpreted by [http://php.net/strtotime strtotime()] or an integer unix timestamp
134     * @param  string         $path      The path this cookie applies to
135     * @param  string         $domain    The domain this cookie applies to
136     * @param  boolean        $secure    If the cookie should only be transmitted over a secure connection
137     * @param  boolean        $httponly  If the cookie should only be readable by HTTP connection, not javascript
138     * @return void
139     */
140     static public function set($name, $value, $expires=NULL, $path=NULL, $domain=NULL, $secure=NULL, $httponly=NULL)
141     {
142         if ($expires === NULL && self::$default_expires !== NULL) {
143             $expires = self::$default_expires;   
144         }
145        
146         if ($path === NULL && self::$default_path !== NULL) {
147             $path = self::$default_path;   
148         }
149        
150         if ($domain === NULL && self::$default_domain !== NULL) {
151             $domain = self::$default_domain;   
152         }
153        
154         if ($secure === NULL && self::$default_secure !== NULL) {
155             $secure = self::$default_secure;   
156         }
157        
158         if ($httponly === NULL && self::$default_httponly !== NULL) {
159             $httponly = self::$default_httponly;   
160         }
161        
162         if ($expires && !is_numeric($expires)) {
163             $expires = strtotime($expires);   
164         }
165        
166         // Adds support for httponly cookies to PHP 5.0 and 5.1
167         if (strlen($value) && $httponly && !fCore::checkVersion('5.2')) {
168             $header_string = urlencode($name) . '=' . urlencode($value);
169             if ($expires) {
170                 $header_string .= '; expires=' . gmdate('D, d-M-Y H:i:s T', $expires);         
171             }
172             if ($path) {
173                 $header_string .= '; path=' . $path;   
174             }
175             if ($domain) {
176                 $header_string .= '; domain=' . $domain;   
177             }
178             if ($secure) {
179                 $header_string .= '; secure';   
180             }
181             $header_string .= '; httponly';
182             header('Set-Cookie: ' . $header_string, FALSE);
183             return;
184            
185         // Only pases the httponly parameter if we are on 5.2 since it causes error notices otherwise
186         } elseif (strlen($value) && $httponly) {
187             setcookie($name, $value, $expires, $path, $domain, $secure, TRUE);
188             return;         
189         }
190        
191         setcookie($name, $value, $expires, $path, $domain, $secure);
192     }
193    
194    
195     /**
196     * Sets the default domain to use for cookies
197     *
198     * This value will be used when the `$domain` parameter of the ::set()
199     * method is not specified or is set to `NULL`.
200     *
201     * @param  string $domain  The default domain to use for cookies
202     * @return void
203     */
204     static public function setDefaultDomain($domain)
205     {
206         self::$default_domain = $domain;   
207     }
208    
209    
210     /**
211     * Sets the default expiration date to use for cookies
212     *
213     * This value will be used when the `$expires` parameter of the ::set()
214     * method is not specified or is set to `NULL`.
215     *
216     * @param  string|integer $expires  The default expiration date to use for cookies
217     * @return void
218     */
219     static public function setDefaultExpires($expires)
220     {
221         self::$default_expires = $expires;   
222     }
223    
224    
225     /**
226     * Sets the default httponly flag to use for cookies
227     *
228     * This value will be used when the `$httponly` parameter of the ::set()
229     * method is not specified or is set to `NULL`.
230     *
231     * @param  boolean $httponly  The default httponly flag to use for cookies
232     * @return void
233     */
234     static public function setDefaultHTTPOnly($httponly)
235     {
236         self::$default_httponly = $httponly;   
237     }
238    
239    
240     /**
241     * Sets the default path to use for cookies
242     *
243     * This value will be used when the `$path` parameter of the ::set()
244     * method is not specified or is set to `NULL`.
245     *
246     * @param  string $path  The default path to use for cookies
247     * @return void
248     */
249     static public function setDefaultPath($path)
250     {
251         self::$default_path = $path;   
252     }
253    
254    
255     /**
256     * Sets the default secure flag to use for cookies
257     *
258     * This value will be used when the `$secure` parameter of the ::set()
259     * method is not specified or is set to `NULL`.
260     *
261     * @param  boolean $secure  The default secure flag to use for cookies
262     * @return void
263     */
264     static public function setDefaultSecure($secure)
265     {
266         self::$default_secure = $secure;   
267     }
268    
269    
270     /**
271     * Forces use as a static class
272     *
273     * @return fCookie
274     */
275     private function __construct() { }
276 }
277  
278  
279  
280 /**
281  * Copyright (c) 2008-2009 Will Bond <will@flourishlib.com>, others
282  *
283  * Permission is hereby granted, free of charge, to any person obtaining a copy
284  * of this software and associated documentation files (the "Software"), to deal
285  * in the Software without restriction, including without limitation the rights
286  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
287  * copies of the Software, and to permit persons to whom the Software is
288  * furnished to do so, subject to the following conditions:
289  *
290  * The above copyright notice and this permission notice shall be included in
291  * all copies or substantial portions of the Software.
292  *
293  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
294  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
295  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
296  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
297  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
298  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
299  * THE SOFTWARE.
300  */