repo_zf1/documentation/manual/en/module_specs/Zend_Session-BasicUsage.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.session.basic_usage">
    <title>Basic Usage</title>

    <para>
        <classname>Zend_Session_Namespace</classname> instances provide the primary
        <acronym>API</acronym> for manipulating session data in the Zend Framework. Namespaces are
        used to segregate all session data, although a default namespace exists for those who only
        want one namespace for all their session data. <classname>Zend_Session</classname> utilizes
        ext/session and its special <varname>$_SESSION</varname> superglobal as the storage
        mechanism for session state data. while <varname>$_SESSION</varname> is still available in
        <acronym>PHP</acronym>'s global namespace, developers should refrain from directly accessing
        it, so that <classname>Zend_Session</classname> and
        <classname>Zend_Session_Namespace</classname> can most effectively and securely provide its
        suite of session related functionality.
    </para>

    <para>
        Each instance of <classname>Zend_Session_Namespace</classname> corresponds to an entry of
        the <varname>$_SESSION</varname> superglobal array, where the namespace is used as the key.
    </para>

    <programlisting language="php"><![CDATA[
$myNamespace = new Zend_Session_Namespace('myNamespace');

// $myNamespace corresponds to $_SESSION['myNamespace']
]]></programlisting>

    <para>
        It is possible to use <classname>Zend_Session</classname> in conjunction with other code
        that uses <varname>$_SESSION</varname> directly. To avoid problems, however, it is highly
        recommended that such code only uses parts of <varname>$_SESSION</varname> that do not
        correspond to instances of <classname>Zend_Session_Namespace</classname>.
    </para>

    <sect2 id="zend.session.basic_usage.basic_examples">
        <title>Tutorial Examples</title>

        <para>
            If no namespace is specified when instantiating
            <classname>Zend_Session_Namespace</classname>, all data will be transparently stored in
            a namespace called "<code>Default</code>". <classname>Zend_Session</classname> is not
            intended to work directly on the contents of session namespace containers. Instead, we
            use <classname>Zend_Session_Namespace</classname>. The example below demonstrates use of
            this default namespace, showing how to count the number of client requests during a
            session:
        </para>

        <example id="zend.session.basic_usage.basic_examples.example.counting_page_views">
            <title>Counting Page Views</title>

            <programlisting language="php"><![CDATA[
$defaultNamespace = new Zend_Session_Namespace('Default');

if (isset($defaultNamespace->numberOfPageRequests)) {
    // this will increment for each page load.
    $defaultNamespace->numberOfPageRequests++;
} else {
    $defaultNamespace->numberOfPageRequests = 1; // first time
}

echo "Page requests this session: ",
    $defaultNamespace->numberOfPageRequests;
]]></programlisting>
        </example>

        <para>
            When multiple modules use instances of <classname>Zend_Session_Namespace</classname>
            having different namespaces, each module obtains data encapsulation for its session
            data. The <classname>Zend_Session_Namespace</classname> constructor can be passed an
            optional <varname>$namespace</varname> argument, which allows developers to partition
            session data into separate namespaces. Namespacing provides an effective and popular way
            to secure session state data against changes due to accidental naming collisions.
        </para>

        <para>
            Namespace names are restricted to character sequences represented as non-empty
            <acronym>PHP</acronym> strings that do not begin with an underscore ("<code>_</code>")
            character. Only core components included in Zend Framework should use namespace names
            starting with "<code>Zend</code>".
        </para>

        <example id="zend.session.basic_usage.basic_examples.example.namespaces.new">
            <title>New Way: Namespaces Avoid Collisions</title>

            <programlisting language="php"><![CDATA[
// in the Zend_Auth component
$authNamespace = new Zend_Session_Namespace('Zend_Auth');
$authNamespace->user = "myusername";

// in a web services component
$webServiceNamespace = new Zend_Session_Namespace('Some_Web_Service');
$webServiceNamespace->user = "mywebusername";
]]></programlisting>
        </example>

        <para>
            The example above achieves the same effect as the code below, except that the session
            objects above preserve encapsulation of session data within their respective namespaces.
        </para>

        <example id="zend.session.basic_usage.basic_examples.example.namespaces.old">
            <title>Old Way: PHP Session Access</title>

            <programlisting language="php"><![CDATA[
$_SESSION['Zend_Auth']['user'] = "myusername";
$_SESSION['Some_Web_Service']['user'] = "mywebusername";
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.session.basic_usage.iteration">
        <title>Iterating Over Session Namespaces</title>

        <para>
            <classname>Zend_Session_Namespace</classname> provides the full <ulink
                url="http://www.php.net/~helly/php/ext/spl/interfaceIteratorAggregate.html">IteratorAggregate
                interface</ulink>, including support for the <code>foreach</code> statement:
        </para>

        <example id="zend.session.basic_usage.iteration.example">
            <title>Session Iteration</title>

            <programlisting language="php"><![CDATA[
$aNamespace =
    new Zend_Session_Namespace('some_namespace_with_data_present');

foreach ($aNamespace as $index => $value) {
    echo "aNamespace->$index = '$value';\n";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.session.basic_usage.accessors">
        <title>Accessors for Session Namespaces</title>

        <para>
            <classname>Zend_Session_Namespace</classname> implements the
            <methodname>__get()</methodname>, <methodname>__set()</methodname>,
            <methodname>__isset()</methodname>, and <methodname>__unset()</methodname> <ulink
                url="http://www.php.net/manual/en/language.oop5.overloading.php">magic
                methods</ulink>, which should not be invoked directly, except from within a
            subclass. Instead, the normal operators automatically invoke these methods, such as in
            the following example:
        </para>

        <example id="zend.session.basic_usage.accessors.example">
            <title>Accessing Session Data</title>

            <programlisting language="php"><![CDATA[
$namespace = new Zend_Session_Namespace(); // default namespace

$namespace->foo = 100;

echo "\$namespace->foo = $namespace->foo\n";

if (!isset($namespace->bar)) {
    echo "\$namespace->bar not set\n";
}

unset($namespace->foo);
]]></programlisting>
        </example>
    </sect2>
</sect1>