session-start.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 151e61773c016edcae8fd4989ad9a86ffd03c283 Maintainer: hirokawa Status: ready -->
<!-- Credits: mumumu -->
<refentry xml:id="function.session-start" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>session_start</refname>
  <refpurpose>新しいセッションを開始、あるいは既存のセッションを再開する</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>session_start</methodname>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>session_start</function> は、セッションを作成します。
   もしくは、リクエスト上で GET, POST またはクッキーにより渡されたセッション
   ID に基づき現在のセッションを復帰します。
  </para>
  <para>
   <function>session_start</function> がコールされたりセッションが自動的に開始したりするときに、
   PHP はセッションの open ハンドラおよび read ハンドラをコールします。
   このハンドラとしては、デフォルトで組み込まれている保存ハンドラの他に PHP 拡張モジュールで提供されているもの
   (SQLite や Memcached など) も使えます。また、自作のハンドラを
   <function>session_set_save_handler</function> で定義することもできます。
   read コールバックは既存のセッションデータ (独自のシリアライズフォーマットで保存されているもの) を読み込み、
   それを復元して自動的にスーパーグローバル $_SESSION に格納します。
  </para>
  <para>
   名前付きのセッションを使用したい場合、
   <function>session_start</function> の前に
   <function>session_name</function> をコールする必要があります。
  </para>
  <para>
   <function>session_start</function> は、
   <link linkend="ini.session.use-trans-sid">session.use_trans_sid</link> が有効の場合に
   URL 書換え用の内部出力ハンドラを登録します。
  </para>
  <para>
   ユーザーが <function>ob_start</function> と共に
   <literal>ob_gzhandler</literal> または類似のものを使用している場合、
   出力ハンドラの順番は正しく出力を行うために重要です。例えば、
   セッション開始時にユーザーは <literal>ob_gzhandler</literal>
   を登録する必要があります。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>options</parameter></term>
    <listitem>
     <para>
      オプションの連想配列を指定することができます。これは、現在設定されている
      <link linkend="session.configuration">セッションの設定ディレクティブ</link>
      を上書きします。
      連想配列のキーにはプレフィックス <literal>session.</literal> を含めてはいけません。
     </para>
     <para>
      通常の設定ディレクティブ群に加えて、
      <literal>read_and_close</literal> オプションを指定することもできます。
      これを &true; にすると、セッションを読み込んだらその場ですぐにクローズします。
      セッションのデータを書き換えるつもりがない場合は、こうしておけば、意図せぬロックを防げます。
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   この関数は、セッションが正常に開始した場合に &true;、それ以外の場合に &false;
   を返します。
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.1.0</entry>
       <entry>
        セッションを開始できなかった場合、
        <function>session_start</function> は、&false; を返し、
        <varname>$_SESSION</varname> を初期化しないようになりました。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <refsect2>
   <title>基本的なセッションの例</title>

   <para>
    <example>
     <title><filename>page1.php</filename></title>
     <programlisting role="php">
<![CDATA[
<?php
// page1.php

session_start();

echo 'Welcome to page #1';

$_SESSION['favcolor'] = 'green';
$_SESSION['animal']   = 'cat';
$_SESSION['time']     = time();

// セッションクッキーが有効なら動作します
echo '<br /><a href="page2.php">page 2</a>';

// あるいは必要に応じてセッション ID を渡します
echo '<br /><a href="page2.php?' . SID . '">page 2</a>';
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    <filename>page1.php</filename> を表示した後なら、
    <filename>page2.php</filename> はセッション上の情報を含んでいるはずです。
    <link linkend="ref.session">セッションについてのリファレンス</link> を読むと、
    <link linkend="session.idpassing">セッションIDの伝達</link> に関する情報が得られます。
    例えば、<constant>SID</constant> とは何かといったことです。
   </para>
   <para>
    <example>
     <title><filename>page2.php</filename></title>
     <programlisting role="php">
<![CDATA[
<?php
// page2.php

session_start();

echo 'Welcome to page #2<br />';

echo $_SESSION['favcolor']; // green
echo $_SESSION['animal'];   // cat
echo date('Y m d H:i:s', $_SESSION['time']);

// page1.php と同様に、ここで SID を使うこともできます
echo '<br /><a href="page1.php">page 1</a>';
?>
]]>
     </programlisting>
    </example>
   </para>
  </refsect2>
  <refsect2>
   <title><function>session_start</function> のオプションの指定</title>

   <example>
    <title>クッキーの有効期限の上書き</title>
    <programlisting role="php">
<![CDATA[
<?php
// これは、有効期限が1日の永続クッキーを送信します
session_start([
    'cookie_lifetime' => 86400,
]);
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>セッションの読み込みとクローズ</title>
    <programlisting role="php">
<![CDATA[
<?php
// セッション内で何も変更する必要がないことがわかっている場合は、
// セッションを読み込んですぐにクローズしてしまえば、
// セッションファイルをロックして他のページをブロックしてしまうことを防げます
session_start([
    'cookie_lifetime' => 86400,
    'read_and_close'  => true,
]);
]]>
    </programlisting>
   </example>
  </refsect2>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    クッキーに基づくセッションを使用している場合、ブラウザに何か出力を行う前に
    <function>session_start</function> をコールする必要があります。
   </para>
  </note>
  <note>
   <para>
    <function>ob_gzhandler</function> よりも
    <link linkend="ini.zlib.output-compression">zlib.output_compression</link>
    の使用が推奨されています。
   </para>
  </note>
  <note>
   <para>
    この関数は、設定によって複数の HTTP ヘッダを送信します。
    これらのヘッダをカスタマイズするには
    <function>session_cache_limiter</function> を参照ください。
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><varname>$_SESSION</varname></member>
    <member>
     設定ディレクティブ <link linkend="ini.session.auto-start">session.auto_start</link>
    </member>
    <member><function>session_id</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->