<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.session.basic_usage">

    <title>基本的な使用法</title>

    <para>
        <classname>Zend_Session_Namespace</classname>
        のインスタンスが、Zend Framework
        のセッションデータを操作するための基本的な <acronym>API</acronym> を提供します。
        名前空間を使用するとセッションデータを個別に扱うことができますが、
        セッションデータ全体をひとつの名前空間で扱いたい人のためのデフォルト名前空間も用意されています。
        <classname>Zend_Session_Namespace</classname> は、ext/session およびスーパーグローバル変数 <code>$_SESSION</code>
        を使用して、セッション状態のデータを保存します。
        <code>$_SESSION</code> はグローバルにアクセス可能ですが、
        開発者はこれに対して直接アクセスするのはやめるべきです。
        <classname>Zend_Session</classname> および <classname>Zend_Session_Namespace</classname> を用いることで、
        セッション関連の機能をより効率的かつ安全に使用できるようになります。
    </para>

    <para>
        <classname>Zend_Session_Namespace</classname> の各インスタンスが、
        スーパーグローバル配列 <code>$_SESSION</code> のエントリに対応します。
        名前空間をキーとして使用します。
    </para>

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

// $myNamespace は $_SESSION['myNamespace'] に対応します
]]></programlisting>

    <para>
        <classname>Zend_Session</classname> は、<code>$_SESSION</code> を直接使用するその他のコードと組み合わせて使用することもできます。
        しかし、問題が起こることをさけるために、<code>$_SESSION</code>
        を直接使用するのは <classname>Zend_Session_Namespace</classname>
        のインスタンスに関連しないキーに限るようにしましょう。
    </para>

    <sect2 id="zend.session.basic_usage.basic_examples">

        <title>チュートリアル</title>

        <para>
            何も名前空間を指定せずに <classname>Zend_Session_Namespace</classname> のインスタンスを作成すると、
            すべてのデータは透過的に "<code>Default</code>" という名前の名前空間に保存されます。
            <classname>Zend_Session</classname> は、セッション名前空間コンテナの内容を
            直接操作するためのものではあります。そのかわりとして
            <classname>Zend_Session_Namespace</classname> を使用します。
            以下の例は、このデフォルトの名前空間を使用して
            セッション内でのクライアントからのリクエストの回数を数えるものです。
        </para>

        <example id="zend.session.basic_usage.basic_examples.example.counting_page_views">

            <title>ページビューの数え方</title>

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

if (isset($defaultNamespace->numberOfPageRequests)) {
    // これが、ページが読み込まれるたびに加算されます
    $defaultNamespace->numberOfPageRequests++;
} else {
    $defaultNamespace->numberOfPageRequests = 1; // 一回目
}

echo "このセッションでページがリクエストされた回数: ",
    $defaultNamespace->numberOfPageRequests;
]]></programlisting>

        </example>

        <para>
            複数のモジュールが別々の名前空間で <classname>Zend_Session_Namespace</classname>
            のインスタンスを使用するようにすると、各モジュールのデータをセッション内でカプセル化できます。
            <classname>Zend_Session_Namespace</classname> のコンストラクタでオプションの引数
            <code>$namespace</code> を指定すると、
            セッションデータを個別の名前空間に分割できます。
            名前空間は、セッションデータで名前の衝突による事故を防ぐための方法として、
            効率的で人気のある方法です。
        </para>

        <para>
            名前空間名に使用できるのは、空文字列以外の <acronym>PHP</acronym> の文字列です。ただし、
            最初の文字にアンダースコア ("<code>_</code>") を使用することはできません。
            "<code>Zend</code>" で始まる名前空間を使えるのは、
            Zend Framework に同梱されるコアコンポーネントだけです。
        </para>

        <example id="zend.session.basic_usage.basic_examples.example.namespaces.new">

            <title>新しい方法: 名前空間の衝突を避ける</title>

            <programlisting language="php"><![CDATA[
// Zend_Auth コンポーネント用
$authNamespace = new Zend_Session_Namespace('Zend_Auth');
$authNamespace->user = "myusername";

// ウェブサービスコンポーネント用
$webServiceNamespace = new Zend_Session_Namespace('Some_Web_Service');
$webServiceNamespace->user = "mywebusername";
]]></programlisting>

        </example>

        <para>
            上の例は、この下のコードと同じ結果になります。
            ただ、上の例ではセッションデータがそれぞれの名前空間でカプセル化されています。
        </para>

        <example id="zend.session.basic_usage.basic_examples.example.namespaces.old">

            <title>古い方法: PHP のセッションへのアクセス</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>セッション名前空間の順次処理</title>

        <para>
            <classname>Zend_Session_Namespace</classname> は
            <ulink url="http://www.php.net/~helly/php/ext/spl/interfaceIteratorAggregate.html">IteratorAggregate インターフェイス</ulink>
            を完全に実装しており、<code>foreach</code> 文をサポートしています。
        </para>

        <example id="zend.session.basic_usage.iteration.example">

            <title>セッションの順次処理</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>セッション名前空間へのアクセス方法</title>

        <para>
            <classname>Zend_Session_Namespace</classname> は <methodname>__get()</methodname>、<methodname>__set()</methodname>、
            <methodname>__isset()</methodname> そして <methodname>__unset()</methodname> といった
            <ulink url="http://www.php.net/manual/ja/language.oop5.overloading.php">マジックメソッド</ulink>
            を実装しています。これらは、自分のサブクラス以外から直接コールされることはありません。
            次の例に示すように、通常の演算の際に自動的にコールされることになります。
        </para>

        <example id="zend.session.basic_usage.accessors.example">

            <title>セッションデータへのアクセス</title>

            <programlisting language="php"><![CDATA[
$namespace = new Zend_Session_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>
