Documentation

Advanced Usage

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.

Starting a Session

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

Zend_Session::start();

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 php.ini, then
add the following to your .htaccess file (usually in your
HTML document root directory):

php_value session.auto_start 0

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
TRUE using
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.

Use "new Zend_Session_Namespace()" normally, where needed,
but make sure Zend_Session::start() has been
called previously.

The 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
ext/session.

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
this
section for more information.

Locking Session Namespaces

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).

Namespace Expiration

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.

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.

Session Encapsulation and Controllers

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.

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.

// ...

// in the question view controller

$testSpace = new Zend_Session_Namespace('testSpace');

// expire only this variable

$testSpace->setExpirationSeconds(300, 'accept_answer');

$testSpace->accept_answer = true;

//...

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:

// ...

// in the answer processing controller

$testSpace = new Zend_Session_Namespace('testSpace');

if($testSpace->accept_answer === true){

// within time

}

else{

// not within time

}

// ...

Preventing Multiple Instances per Namespace

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.

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.

Working with Arrays

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.

Using Sessions with Objects

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 stdClass.

Using Sessions with Unit Tests

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
testSetExpirationSeconds() in SessionTest.php and
SessionTestHelper.php, both located in tests/Zend/Session,
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
exec().