PHP Unframework
PHP Unframework
PHP Unframework
Wraps the session control functions and the $_SESSION superglobal for a more consistent and safer API
A Cannot send session cache limiter warning will be triggered if open(), add(), clear(), delete(), get() or set() is called after output has been sent to the browser. To prevent such a warning, explicitly call open() before generating any output.
| 1.0.0b22 | Fixed destroy() to no longer call regenerateID() since it fails after a session is destroyed 9/20/12 |
|---|---|
| 1.0.0b21 | Changed regenerateID() to not fail silently if the session has not been opened yet 9/15/12 |
| 1.0.0b20 | Fixed bugs with reset() introduced in 1.0.0b19 8/23/11 |
| 1.0.0b19 | Fixed some session warning messages for PHP 5.1.6 7/29/11 |
| 1.0.0b18 | Added support for storing session data in memcache, redis and databases using fCache and setBackend() 6/21/11 |
| 1.0.0b17 | Updated ignoreSubdomain() to use $_SERVER['HTTP_HOST'] when $_SERVER['SERVER_NAME'] is not set 2/1/11 |
| 1.0.0b16 | Changed delete() to return the value of the key being deleted 9/19/10 |
| 1.0.0b15 | Added documentation about [sub-key] syntax 9/12/10 |
| 1.0.0b14 | Backwards Compatibility Break - add(), delete(), get() and set() now interpret [ and ] as array shorthand and thus they can not be used in keys - added $beginning parameter to add(), added remove() method 9/12/10 |
| 1.0.0b13 | Fixed a bug that prevented working with existing sessions since they did not have the fSession::expires key 8/24/10 |
| 1.0.0b12 | Changed enablePersistence() to always regenerate the session ID, which ensures the function works even if the ID has already been regenerated by fAuthorizaton 8/21/10 |
| 1.0.0b11 | Updated the class to make sure enablePersistence() is called after ignoreSubdomain(), setLength() and setPath() 5/29/10 |
| 1.0.0b10 | Fixed some documentation bugs 3/3/10 |
| 1.0.0b9 | Fixed a bug in destroy() where sessions weren't always being properly destroyed 12/8/09 |
| 1.0.0b8 | Fixed a bug that made the unit tests fail on PHP 5.1 10/27/09 |
| 1.0.0b7 | Backwards Compatibility Break - Removed the $prefix parameter from the methods delete(), get() and set() - added the methods add(), enablePersistence(), regenerateID() 10/23/09 |
| 1.0.0b6 | Backwards Compatibility Break - the first parameter of clear() was removed, use delete() instead 5/8/09 |
| 1.0.0b5 | Added documentation about session cache limiter warnings 5/4/09 |
| 1.0.0b4 | The class now works with existing sessions 5/4/09 |
| 1.0.0b3 | Fixed clear() to properly handle when $key is NULL 2/5/09 |
| 1.0.0b2 | Made open() public, fixed some consistency issues with setting session options through the class 1/6/09 |
| 1.0.0b | The initial implementation 6/14/07 |
Adds a value to an already-existing array value, or to a new array value
void add( string $key, mixed $value, boolean $beginning=FALSE )
| string | $key | The name to access the array under - array elements can be modified via [sub-key] syntax, and thus [ and ] can not be used in key names |
| mixed | $value | The value to add to the array |
| boolean | $beginning | If the value should be added to the beginning |
Removes all session values with the provided prefix
This method will not remove session variables used by this class, which are prefixed with fSession::.
void clear( string $prefix=NULL )
| string | $prefix | The prefix to clear all session values for |
Closes the session for writing, allowing other pages to open the session
void close( )
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Callback to close the session
boolean closeCache( )
If the operation succeeded
Deletes a value from the session
mixed delete( string $key, mixed $default_value=NULL )
| string | $key | The key of the value to delete - array elements can be modified via [sub-key] syntax, and thus [ and ] can not be used in key names |
| mixed | $default_value | The value to return if the $key is not set |
The value of the $key that was deleted
Destroys the session, removing all values
void destroy( )
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Callback to destroy a session
boolean destroyCache( string $id )
| string | $id | The session to destroy |
If the operation succeeded
Changed the session to use a time-based cookie instead of a session-based cookie
The length of the time-based cookie is controlled by setLength(). When this method is called, a time-based cookie is used to store the session ID. This means the session can persist browser restarts. Normally, a session-based cookie is used, which is wiped when a browser restart occurs.
This method should be called during the login process and will normally be controlled by a checkbox or similar where the user can indicate if they want to stay logged in for an extended period of time.
void enablePersistence( )
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Callback to garbage-collect the session cache
boolean gcCache( )
If the operation succeeded
Gets data from the $_SESSION superglobal
mixed get( string $key, mixed $default_value=NULL )
| string | $key | The name to get the value for - array elements can be accessed via [sub-key] syntax, and thus [ and ] can not be used in key names |
| mixed | $default_value | The default value to use if the requested key is not set |
The data element requested
Sets the session to run on the main domain, not just the specific subdomain currently being accessed
This method should be called after any calls to session_set_cookie_params().
void ignoreSubdomain( )
Opens the session for writing, is automatically called by clear(), get() and set()
A Cannot send session cache limiter warning will be triggered if this, add(), clear(), delete(), get() or set() is called after output has been sent to the browser. To prevent such a warning, explicitly call this method before generating any output.
void open( boolean $cookie_only_session_id=TRUE )
| boolean | $cookie_only_session_id | If the session id should only be allowed via cookie - this is a security issue and should only be set to FALSE when absolutely necessary |
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Callback to open the session
boolean openCache( )
If the operation succeeded
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Callback to read a session's values
string readCache( string $id )
| string | $id | The session to read |
The session's serialized data
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Regenerates the session ID, but only once per script execution
void regenerateID( )
Removes and returns the value from the end of an array value
mixed remove( string $key, boolean $beginning=FALSE )
| string | $key | The name of the element to remove the value from - array elements can be modified via [sub-key] syntax, and thus [ and ] can not be used in key names |
| boolean | $beginning | If the value should be removed to the beginning |
The value that was removed
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Resets the configuration of the class
void reset( )
Sets data to the $_SESSION superglobal
void set( string $key, mixed $value )
| string | $key | The name to save the value under - array elements can be modified via [sub-key] syntax, and thus [ and ] can not be used in key names |
| mixed | $value | The value to store |
Sets an fCache object to store sessions in
While any type of fCache backend should technically work, it would be unwise to use the file and directory types. The file caching backend stores all values in a single file, which would quickly become a performance bottleneck and could cause data loss with many concurrent users. The directory caching backend would not make sense since it is the same general functionality as the default session handler, but it would be slightly slower since it is written in PHP and not C.
It is recommended to set the serializer and unserializer $config settings on the fCache object to string for the best performance and minimal storage space.
For better performance, check out using the built-in session handlers that are bundled with the following extensions:
The igbinary extension can provide even more of a performance boost by storing serialized data in binary format instead of as text.
void setBackend( fCache $backend, string $key_prefix='' )
Sets the minimum length of a session - PHP might not clean up the session data right away once this timespan has elapsed
Please be sure to set a custom session path via setPath() to ensure another site on the server does not garbage collect the session files from this site!
Both of the timespan can accept either a integer timespan in seconds, or an english description of a timespan (e.g. '30 minutes', '1 hour', '1 day 2 hours').
void setLength( string|integer $normal_timespan, string|integer $persistent_timespan=NULL )
| string|integer | $normal_timespan | The normal, session-based cookie, length for the session |
| string|integer | $persistent_timespan | The persistent, timed-based cookie, length for the session - this is enabled by calling enabledPersistence() during login |
Sets the path to store session files in
This method should always be called with a non-standard directory whenever setLength() is called to ensure that another site on the server does not garbage collect the session files for this site.
Standard session directories usually include /tmp and /var/tmp.
void setPath( string|fDirectory $directory )
| string|fDirectory | $directory | The directory to store session files in |
Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code
Callback to write a session's values
string writeCache( string $id, string $values )
| string | $id | The session to write |
| string | $values | The serialized values |
The session's serialized data
