examples.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 184f3f7bd45643cb80f828d0bb001991ec3a5fad Maintainer: aur Status: ready -->
<!-- Reviewed: no -->
<appendix xml:id="session.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.examples;
 <section xml:id="session.examples.basic">
  <title>Основы использования</title>
  <para>
   Сессии являются простым способом хранения информации для отдельных пользователей
   с уникальным идентификатором сессии. Это может использоваться для сохранения
   состояния между запросами страниц. Идентификаторы сессий обычно отправляются
   браузеру через сессионный cookie и используются для получения имеющихся данных
   сессии. Отсутствие идентификатора сессии или сессионного cookie сообщает PHP о том,
   что необходимо создать новую сессию и сгенерировать новый идентификатор сессии.
  </para>
  <para>
   Сессии используют простую технологию. Когда сессия создана, PHP будет либо получать
   существующую сессию, используя переданный идентификатор (обычно из сессионного
   cookie) или, если ничего не передавалось, будет создана новая сессия. PHP заполнит
   суперглобальную переменную <varname>$_SESSION</varname> сессионной информацией
   после того, как будет запущена сессия. Когда PHP завершает работу, он автоматически
   сериализует содержимое суперглобальной переменной <varname>$_SESSION</varname>
   и отправит для сохранения, используя сессионный обработчик для записи сессии.
  </para>
  <para>
   По умолчанию PHP использует внутренний обработчик <parameter>files</parameter>
   для сохранения сессий, который установлен в INI-переменной <link linkend="ini.session.save-handler">session.save_handler</link>.
   Этот обработчик сохраняет данные на сервере в директории, указанной в конфигурационной
   директиве <link linkend="ini.session.save-path">session.save_path</link>.
  </para>
  <para>
   Сессии могут запускаться вручную с помощью функции <function>session_start</function>.
   Если директива <link linkend="ini.session.auto-start">session.auto_start</link> установлена
   в <parameter>1</parameter>, сессия автоматически запустится, в начале запроса.
  </para>
  <para>
   Сессия обычно завершает свою работу, когда PHP заканчивает исполнять скрипт, но может
   быть завершена и вручную с помощью функции <function>session_write_close</function>.
  </para>
  <para>
   <example>
    <title>
     Регистрация переменной с помощью <varname>$_SESSION</varname>.
    </title>
    <programlisting role="php">
<![CDATA[
<?php
session_start();
if (!isset($_SESSION['count'])) {
  $_SESSION['count'] = 0;
} else {
  $_SESSION['count']++;
}
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>
     Отмена объявления переменной с помощью <varname>$_SESSION</varname>.
    </title>
    <programlisting role="php">
<![CDATA[
<?php
session_start();
unset($_SESSION['count']);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <caution>
    <para>
     НЕ ОЧИЩАЙТЕ <varname>$_SESSION</varname> целиком, используя
     <literal>unset($_SESSION)</literal>, так как это отключит возможность
     регистрации сессионных переменных через суперглобальную переменную
     <varname>$_SESSION</varname>.
    </para>
   </caution>
  </para>
  <warning>
   <para>
    Вы не можете использовать ссылки в сессионных переменных, так как не
    существует реального способа восстановления ссылки к другой переменной.
   </para>
  </warning>
  <note>
   <para>
    Сессии, использующие файлы (по умолчанию в PHP), блокируют файл сессии
    сразу при открытии сессии функцией <function>session_start</function> или
    косвенно при указании <link linkend="ini.session.auto-start">session.auto_start</link>.
    После блокировки, ни один другой скрипт не может получить доступ к этому же файлу
    сессии, пока он не будет закрыт или при завершении скрипта или при вызове функции
    <function>session_write_close</function>.
   </para>
   <para>
    Скорее всего это станет проблемой для сайтов, которые активно используют AJAX
    и делают несколько одновременных запросов. Простейшим путём решить эту проблему
    будет вызов функции <function>session_write_close</function> сразу же как только
    все требуемые изменения в сессии будут сделаны, предпочтительно ближе к началу работы
    скрипта. Также можно использовать другой механизм сессии, который поддерживает
    конкурентный доступ.
   </para>
  </note>
 </section>

 <section xml:id="session.idpassing">
  <title>Передача идентификатора сессии</title>
  <para>
   Существуют два метода передачи идентификатора сессии:
   <itemizedlist>
    <listitem>
     <simpara>
      Cookies
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Параметр URL
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   Модуль сессии поддерживает оба метода. Метод с cookies является оптимальным,
   но он не всегда доступен.
   Поэтому PHP предоставляет второй способ, который внедряет идентификатор сессии
   непосредственно в URL.
  </para>
  <para>
   PHP умеет преобразовывать ссылки прозрачно.
   Если <literal>session.use_trans_sid</literal> включена,
   все относительные URI-адреса будут автоматически содержать идентификатор сессии.
   <note>
    <para>
     Директива
     <link linkend="ini.arg-separator.output">arg_separator.output</link> из
     &php.ini; позволяет настраивать разделитель аргументов. Для полной
     совместимости с XHTML следует указывать &amp;amp;.
    </para>
   </note>
  </para>
  <para>
   В качестве альтернативы вы можете использовать константу
   <constant>SID</constant>, которая устанавливается при запуске сессии.
   Если клиентское ПО не хранит подходящую сессионную
   cookie, SID имеет вид <literal>session_name=session_id</literal>.
   В противном случае содержит пустую строку. Таким образом, вы можете
   в любом случае внедрять его в URL.
  </para>
  <para>
   Приведённый ниже пример демонстрирует, как зарегистрировать переменную и как
   правильно построить ссылку на другую страницу, используя <constant>SID</constant>.
   <example>
    <title>Подсчёт количества посещений конкретного пользователя</title>
    <programlisting role="php">
<![CDATA[
<?php

session_start();

if (empty($_SESSION['count'])) {
   $_SESSION['count'] = 1;
} else {
   $_SESSION['count']++;
}
?>

<p>
Здравствуйте, посетитель, вы видели эту страницу <?php echo $_SESSION['count']; ?> раз.
</p>

<p>
<a href="nextpage.php?<?php echo htmlspecialchars(SID); ?>">Нажмите
сюда</a>, чтобы продолжить.
</p>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Функция <function>htmlspecialchars</function> может использоваться для вывода
   <constant>SID</constant> с целью предотвращения XSS-атак.
  </para>
  <para>
   Вывод <constant>SID</constant> способом, показанном выше, не является
   обязательным, если опция <link linkend="ini.session.use-trans-sid">
   --enable-trans-sid</link> была использована при компиляции PHP.
  </para>
  <note>
   <para>
    Подразумевается, что неотносительные URL-адреса указывают только на внешние сайты и
    потому <constant>SID</constant> к ним не добавляется, т.к.
    это представляло бы угрозу для безопасности, в частности, риск
    утечки <constant>SID</constant> другому серверу.
   </para>
  </note>
 </section>

 <section xml:id="session.customhandler">
  <title>Пользовательские обработчики сессии</title>
  <para>
   Для реализации хранилища данных (или любого иного хранилища) следует
   использовать <function>session_set_save_handler</function>, чтобы создать
   набор пользовательских функций хранилища. Обработчики сессий можно создать,
   используя класс <classname>SessionHandlerInterface</classname>, или расширить внутренние обработчики PHP,
   унаследовав класс <classname>SessionHandler</classname>.
  </para>
  <para>
   Функции обратного вызова, указанные в <function>session_set_save_handler</function>, являются методами,
   вызываемыми PHP в течение жизненного цикла сессии: <parameter>open</parameter>, <parameter>read</parameter>,
   <parameter>write</parameter> и <parameter>close</parameter> и для служебных задач:
   <parameter>destroy</parameter> для удаления сессии и <parameter>gc</parameter> для периодической
   сборки мусора.
  </para>
  <para>
   Следовательно, в PHP всегда необходимы обработчики, сохраняющие сессии. По умолчанию работает
   внутренний обработчик 'files', сохраняющий сессии в файлы. Пользовательский обработчик может быть установлен,
   используя функцию <function>session_set_save_handler</function>. Альтернативные обработчики для сохранения сессии
   также доступны в модулях PHP, таких как <parameter>sqlite</parameter>,
   <parameter>memcache</parameter> и <parameter>memcached</parameter> и могут быть установлены с помощью
   <link linkend="ini.session.save-handler">session.save_handler</link>.
  </para>
  <para>
   Когда стартует сессия, PHP внутренне вызовет обработчик <parameter>open</parameter> с последующим
   вызовом обработчика <parameter>read</parameter>, который должен вернуть закодированную строку - в точности такую,
   какая передавалась для сохранения. После возвращения обработчиком <parameter>read</parameter> закодированной строки, PHP
   декодирует её и заполнит получившимся массивом суперглобальный массив <varname>$_SESSION</varname>.
  </para>
  <para>
   Когда PHP завершает исполнение скрипта (или когда вызвана функция <function>session_write_close</function>),
   PHP внутренне закодирует суперглобальный массив <varname>$_SESSION</varname>, и передаст
   эти данные с идентификатором сессии функции обратного вызова <parameter>write</parameter>.
   После того, как отработает функция обратного вызова <parameter>write</parameter>, PHP внутренне вызовет
   обработчик функции обратного вызова <parameter>close</parameter>.
  </para>
  <para>
   Когда сессия специально уничтожена, PHP вызовет обработчик <parameter>destroy</parameter> с
   идентификатором сессии.
  </para>
  <para>
   PHP будет вызывать обработчик функции обратного вызова <parameter>gc</parameter> время от времени,
  чтобы пометить сессии как истёкшие в соответствии с временем жизни сессий.
  Эта операция удалит все записи из постоянного хранилища, доступ к которым не осуществлялся
  более чем интервал времени, указанный в параметре <parameter>$lifetime</parameter>.
  </para>
 </section>
</appendix>
<!-- 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
-->