<sect1 id="zend.session.basicusage">

    <title>Базовое использование<!--Basic Usage--></title>

    <para>
        <code>Zend_Session_Namespace</code> создает экземпляры контейнеров,
        предоставляющих основной API для работы с данными сессии в Zend
        Framework. Пространства имен используются для разделения всех данных
        сессии, несмотря на то, что есть пространство имен по умолчанию для тех,
        кому нужно только одно пространство имен для всех данных сессии.
        <code>Zend_Session</code> использует расширение ext/session и его
        суперглобальный массив <varname>$_SESSION</varname> в качестве механизма
        хранения постоянных данных сессии. Несмотря на то, что
        <varname>$_SESSION</varname> остается доступным в глобальном пространстве
        имен, разработчики должны избегать прямого обращения к нему с тем, чтобы
        можно было наиболее безопасно и эффективно использовать возможности
        <code>Zend_Session</code> и <code>Zend_Session_Namespace</code> для
        работы с сессиями.
<!--
        <code>Zend_Session_Namespace</code> creates instances of containers providing the primary API for manipulating
        session data in 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. <code>Zend_Session</code>
        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 PHP's global namespace, developers should refrain
        from directly accessing it, so that <code>Zend_Session</code> and <code>Zend_Session_Namespace</code> can most
        effectively and securely provide its suite of session related functionality.
-->
    </para>

    <sect2 id="zend.session.basicexamples">

        <title>Учебные примеры<!--Tutorial Examples--></title>

        <para>
            Если при инстанцировании Zend_Session не было указано пространство
            имен, то все данные будут неявным образом сохранены в пространстве
            имен "<code>Default</code>". <code>Zend_Session</code> не
            предназначен для работы с содержимым контейнера пространства имен
            сессии напрямую. Вместо этого мы используем
            <code>Zend_Session_Namespace</code>. Пример ниже демонстрирует
            использование пространства имен по умолчанию и показывает, как
            подсчитывать количество просмотров страниц пользователем на сайте.
            Для тестирования этого примера добавьте следующий код в
            файл загрузки:
<!--
            If no namespace is specified when instantiating Zend_Session, all data will be transparently stored in a
            namespace called "<code>Default</code>". <code>Zend_Session</code> is not intended to work directly on the
            contents of session namespace containers. Instead, we use <code>Zend_Session_Namespace</code>. The example
            below demonstrates use of this default namespace, showing how to count the number of times a user views
            pages on your website. To test this example, add the following code to your ZF bootstrap area:
-->
        </para>

        <example>
            <title>Подсчет количества просмотров страниц<!--Counting Page Views--></title>
<programlisting language="php">
<![CDATA[<?php
    require_once 'Zend/Session.php';

    $defaultNamespace = new Zend_Session_Namespace('Default');

    // используется "магический" метод __isset() в Zend_Session_Namespace:
    if (isset($defaultNamespace->numberOfPageRequests)) {
        // будет увеличиваться на единицу при каждой загрузке страницы.
        $defaultNamespace->numberOfPageRequests++;
    } else {
        $defaultNamespace->numberOfPageRequests = 1; // начальное значение
    }

    echo "Запросов к странице за эту сессию: ", $defaultNamespace->numberOfPageRequests;
?>]]></programlisting>
        </example>

        <para>
            Одним из многих преимуществ Zend_Session_Namespace
            является то, что при его использовании различными модулями
            приложения достигается инкапсуляциия принадлежащих им данных сессий.
            Конструктору Zend_Session можно передавать необязательный аргумент
            $namespace, который позволяет другим компонентам, модулям и
            разрабочикам кода быть уверенным в том, что их данные
            защищены отделением от других областей данных, используемых другими
            компонентами, модулями и кодами разработчиков. Пространства имен
            представляют собой эффективный и доступный способ защиты данных
            сессий от случайных изменений. Имена пространств имен должны быть
            непустыми строками, не начинающимися со знака подчеркивания. Только
            основные компоненты, включенные в Zend Framework, должны
            использовать имена пространств имен, начинающиеся с 'Zend_'.
<!--
            One of the many benefits of Zend_Session_Namespace results when multiple modules use Zend_Session_Namespace
            and obtain data encapsulation for their session data. Zend_Session can be passed an optional $namespace
            argument in the constructor, which allows other components, modules, and developer specific code to be
            assured that their data is protected by a partition between data areas used by other components, modules,
            and developer code. Namespacing provides an effective and popular way to "secure" a subset of session state
            data against accidental changes. Namespace names are restricted to character sequences represented as
            non-empty PHP strings that do not begin with an underscore ('_') character. Only core components included in
            Zend Framework should use namespace names starting with 'Zend_'.
-->
        </para>

        <example>
            <title>Новый подход: избежание конфликтов с помощью пространств имен<!--New Way: Namespaces Avoid Collisions--></title>
<programlisting language="php">
<![CDATA[<?php
    // in the Zend_Auth component
    require_once 'Zend/Session.php';
    $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>
            <title>Старый подход: обращение к сессиям PHP<!--Old Way: PHP Session Access--></title>
<programlisting language="php">
<![CDATA[<?php
    $_SESSION['Zend_Auth']['user'] = "myusername";
    $_SESSION['Some_Web_Service']['user'] = "mywebusername";
?>]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.session.iteration">

        <title>Итерация по пространствам имен<!--Iterating Over Session Namespaces--></title>

        <para>
            <code>Zend_Session_Namespace</code> предоставляет полный интерфейс
            <ulink url="http://www.php.net/~helly/php/ext/spl/interfaceIteratorAggregate.html">IteratorAggregate</ulink>,
            включая поддержку выражения <code>foreach</code>:
<!--
            <code>Zend_Session_Namespace</code> 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>
            <title>Итерация по сессии<!--Session Iteration--></title>
<programlisting language="php">
<![CDATA[<?php
    // Zend_Session is iteratable
    require_once 'Zend/Session.php';
    $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.accessors">

        <title>Методы доступа для пространств имен<!--Accessors for Session Namespaces--></title>

        <para>
            Обычные методы доступа доступны через "магические" методы (magic
            methods) __set(), __unset(), __isset() и __get(). "Магические"
            методы не должны использоваться напрямую, кроме как внутри
            подклассов Zend_Session. Вместо этого используйте обычные операторы
            для вызова этих "магических" методов, например:
<!--
            The usual accessors are available, via the __set(), __unset(), __isset(), and __get() magic methods. The
            magic methods should not be used directly, except from within a subclass of Zend_Session. Instead, use the
            normal operators to invoke these magic methods, such as:
-->
        </para>

        <example>
            <title>Доступ к сессионным данным<!--Accessing Session Data--></title>
<programlisting language="php">
<![CDATA[<?php
            $object->property = $value;
            echo (isset($object->property) ? 'set' : 'unset');
?>]]></programlisting>
        </example>

    </sect2>

</sect1>
