Caution: The documentation you are viewing is
for an older version of Zend Framework.
You can find the documentation of the current version at:
Advanced Usage - Zend_Session
While the basic usage examples are a perfectly acceptable way to utilize Zend Framework sessions, there are some best practices to consider. This section discusses the finer details of session handling and illustrates more advanced usage of the Zend_Session component.
If you want all requests to have a session facilitated by Zend_Session, then start the session in the bootstrap file:
Example #1 Starting the Global Session
By starting the session in the bootstrap file, you avoid the possibility that your session might be started after headers have been sent to the browser, which results in an exception, and possibly a broken page for website viewers. Various advanced features require Zend_Session::start() first. (More on advanced features later.)
There are four ways to start a session, when using Zend_Session. Two are wrong.
Wrong: Do not enable PHP's »
session.auto_start setting. If you do not have the
ability to disable this setting in php.ini, you are using mod_php (or
equivalent), and the setting is already enabled in
add the following to your
.htaccess file (usually in your
HTML document root directory):
Wrong: Do not use PHP's » session_start() function directly. If you use session_start() directly, and then start using Zend_Session_Namespace, an exception will be thrown by Zend_Session::start() ("session has already been started"). If you call session_start() after using Zend_Session_Namespace or calling Zend_Session::start(), an error of level E_NOTICE will be generated, and the call will be ignored.
Correct: Use Zend_Session::start(). If you want all requests to have and use sessions, then place this function call early and unconditionally in your bootstrap code. Sessions have some overhead. If some requests need sessions, but other requests will not need to use sessions, then:
Unconditionally set the
strict option to
Zend_Session::setOptions() in your bootstrap.
Call Zend_Session::start() only for requests that need to use sessions and before any Zend_Session_Namespace objects are instantiated.
new Zend_Session_Namespace()" normally, where needed,
but make sure Zend_Session::start() has been
strict option prevents
new Zend_Session_Namespace() from automatically starting the
session using Zend_Session::start(). Thus, this option
helps application developers enforce a design decision to avoid using sessions
for certain requests, since it causes an exception to be thrown when
Zend_Session_Namespace is instantiated before
Zend_Session::start() is called. Developers should
carefully consider the impact of using
Zend_Session::setOptions(), since these options have
global effect, owing to their correspondence to the underlying options for
Correct: Just instantiate Zend_Session_Namespace whenever
needed, and the underlying PHP session will be automatically
started. This offers extremely simple usage that works well in most situations.
However, you then become responsible for ensuring that the first
new Zend_Session_Namespace() happens before
any output (e.g., » HTTP
headers) has been sent by PHP to the client, if
you are using the default, cookie-based sessions (strongly recommended). See
section for more information.
Session namespaces can be locked, to prevent further alterations to the data in that namespace. Use lock() to make a specific namespace read-only, unLock() to make a read-only namespace read-write, and isLocked() to test if a namespace has been previously locked. Locks are transient and do not persist from one request to the next. Locking the namespace has no effect on setter methods of objects stored in the namespace, but does prevent the use of the namespace's setter method to remove or replace objects stored directly in the namespace. Similarly, locking Zend_Session_Namespace instances does not prevent the use of symbol table aliases to the same data (see » PHP references).
Example #2 Locking Session Namespaces
Limits can be placed on the longevity of both namespaces and individual keys in namespaces. Common use cases include passing temporary information between requests, and reducing exposure to certain security risks by removing access to potentially sensitive information some time after authentication occurred. Expiration can be based on either elapsed seconds or the number of "hops", where a hop occurs for each successive request.
Example #3 Expiration Examples
When working with data expiring from the session in the current request, care should be used when retrieving them. Although the data are returned by reference, modifying the data will not make expiring data persist past the current request. In order to "reset" the expiration time, fetch the data into temporary variables, use the namespace to unset them, and then set the appropriate keys again.
Namespaces can also be used to separate session access by controllers to protect variables from contamination. For example, an authentication controller might keep its session state data separate from all other controllers for meeting security requirements.
Example #4 Namespaced Sessions for Controllers with Automatic Expiration
The following code, as part of a controller that displays a test question, initiates a boolean variable to represent whether or not a submitted answer to the test question should be accepted. In this case, the application user is given 300 seconds to answer the displayed question.
Below, the controller that processes the answers to test questions determines whether or not to accept an answer based on whether the user submitted the answer within the allotted time:
Although session locking provides a good degree of protection against unintended use of namespaced session data, Zend_Session_Namespace also features the ability to prevent the creation of multiple instances corresponding to a single namespace.
To enable this behavior, pass TRUE to the second constructor argument when creating the last allowed instance of Zend_Session_Namespace. Any subsequent attempt to instantiate the same namespace would result in a thrown exception.
Example #5 Limiting Session Namespace Access to a Single Instance
The second parameter in the constructor above tells Zend_Session_Namespace that any future instances with the "Zend_Auth" namespace are not allowed. Attempting to create such an instance causes an exception to be thrown by the constructor. The developer therefore becomes responsible for storing a reference to an instance object ($authSpaceAccessor1, $authSpaceAccessor2, or $authSpaceAccessor3 in the example above) somewhere, if access to the session namespace is needed at a later time during the same request. For example, a developer may store the reference in a static variable, add the reference to a » registry (see Zend_Registry), or otherwise make it available to other methods that may need access to the session namespace.
Due to the implementation history of PHP magic methods, modifying an array inside a namespace may not work under PHP versions before 5.2.1. If you will only be working with PHP 5.2.1 or later, then you may skip to the next section.
Example #6 Modifying Array Data with a Session Namespace
The following illustrates how the problem may be reproduced:
Example #7 Building Arrays Prior to Session Storage
If possible, avoid the problem altogether by storing arrays into a session namespace only after all desired array values have been set.
If you are using an affected version of PHP and need to modify the array after assigning it to a session namespace key, you may use either or both of the following workarounds.
Example #8 Workaround: Reassign a Modified Array
In the code that follows, a copy of the stored array is created, modified, and reassigned to the location from which the copy was created, overwriting the original array.
Example #9 Workaround: store array containing reference
Alternatively, store an array containing a reference to the desired array, and then access it indirectly.
If you plan to persist objects in the PHP session, know that they
will be » serialized
for storage. Thus, any object persisted with the PHP session must be
unserialized upon retrieval from storage. The implication is that the developer must
ensure that the classes for the persisted objects must have been defined before the
object is unserialized from session storage. If an unserialized object's class is not
defined, then it becomes an instance of
Zend Framework relies on PHPUnit to facilitate testing of itself. Many developers extend the existing suite of unit tests to cover the code in their applications. The exception "Zend_Session is currently marked as read-only" is thrown while performing unit tests, if any write-related methods are used after ending the session. However, unit tests using Zend_Session require extra attention, because closing ( Zend_Session::writeClose()), or destroying a session ( Zend_Session::destroy()) prevents any further setting or unsetting of keys in any instance of Zend_Session_Namespace. This behavior is a direct result of the underlying ext/session mechanism and PHP's session_destroy() and session_write_close(), which have no "undo" mechanism to facilitate setup/teardown with unit tests.
To work around this, see the unit test
SessionTestHelper.php, both located in
which make use of PHP's exec() to launch a
separate process. The new process more accurately simulates a second, successive request
from a browser. The separate process begins with a "clean" session, just like any
PHP script execution for a web request. Also, any changes to
$_SESSION made in the calling process become available to the child
process, provided the parent closed the session before using
Example #10 PHPUnit Testing Code Dependent on Zend_Session