archived-doc-ru/reference/session/functions/session-start.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 151e61773c016edcae8fd4989ad9a86ffd03c283 Maintainer: rjhdby Status: ready -->
<!-- Reviewed: no -->
<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-запрос или в блоке данных cookie.
  </para>
  <para>
   При вызове функции <function>session_start</function> или автозапуске сессии
   PHP вызовет открытие и чтение обработчиков сохранения сессии. Обработчиком станет
   либо встроенный обработчик сохранения по умолчанию, либо обработчик, который установил
   PHP-модуль наподобие SQLite или Memcached, или пользовательский обработчик, который определили
   функцией <function>session_set_save_handler</function>.
   Callback-функция чтения извлечёт данные сессии из хранилища и вернёт сериализованное
   представление сохранённых данных обработчику PHP-сессий в формате, который определили в директиве <link linkend="ini.session.serialize-handler">session.serialize_handler</link>.
   Обработчик десериализует данные и автоматически заменит ими содержимое суперглобального массива $_SESSION.
  </para>
  <para>
   Произвольное название сессии устанавливают функцией <function>session_name</function>
   путём вызова перед функции <function>session_start</function>.
  </para>
  <para>
   При включённой опции <link linkend="ini.session.use-trans-sid">session.use_trans_sid</link>
   функция <function>session_start</function> зарегистрирует внутренний обработчик вывода
   для перезаписи URL-адресов.
  </para>
  <para>
   Порядок вызова функций играет важную роль для правильного вывода данных при передаче в функцию <function>ob_start</function>
   обработчика вывода сжатых данных <literal>ob_gzhandler</literal> или похожей callback-функции.
   Например, обработчик <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 'Добро пожаловать на страницу 1';

$_SESSION['favcolor'] = 'зелёный';
$_SESSION['animal']   = 'кот';
$_SESSION['time']     = time();

// Работает, если получатель принял сессионный блок данных cookie
echo '<br /><a href="page2.php">page 2</a>';

// Или вывод передают вместе с идентификатором сессии, если требуется
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">о передаче идентификатора сессии</link>,
    включая сведения о том, как работает
    константа <constant>SID</constant>.
   </para>
   <para>
    <example>
     <title><filename>page2.php</filename></title>
     <programlisting role="php">
<![CDATA[
<?php

// page2.php

session_start();

echo 'Добро пожаловать на страницу 2<br />';

echo $_SESSION['favcolor']; // зелёный
echo $_SESSION['animal'];   // кот
echo date('Y m d H:i:s', $_SESSION['time']);

// В этом месте можно использовать константу SID, как это делал код страницы page1.php
echo '<br /><a href="page1.php">page 1</a>';
]]>
     </programlisting>
    </example>
   </para>
  </refsect2>
  <refsect2>
   <title>Пример передачи опций в функцию <function>session_start</function></title>

   <example>
    <title>Переопределение времени жизни cookie</title>
    <programlisting role="php">
<![CDATA[
<?php

// Устанавливаем срок действия cookie равным одному дню
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> требуется вызывать перед выводом данных в браузер,
    чтобы работать с сессиями на основе блоков данных cookies.
   </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
-->