session-start.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d8849b5554a4b934cc8aacce047d8ec7b7cdec80 Maintainer: seros Status: ready -->
<!-- Reviewed: no -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.session-start">
 <refnamediv>
  <refname>session_start</refname>
  <refpurpose>Iniciar una nueva sesión o reanudar la existente</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> crea una sesión o reanuda la
   actual basada en un identificador de sesión pasado mediante una petición GET o POST,
   o pasado mediante una cookie.
  </para>
  <para>
   Cuando <function>session_start</function> es llamada o cuando se autoinicia una sesión,
   PHP llamará a los gestores de almacenamiento de sesiones open y read. Éstos serán un gestor
   de almacenamiento proporcionado por omisión o por extensiones de PHP (como SQLite o Memcached); o pueden ser
   un gestor personalizado como está definido en <function>session_set_save_handler</function>.
   La llamada de retorno read recuperará cualquier información se de sesión existente (almacenada en un formato serializado especial)
   y será deserializada y usada para rellenar automáticamente la variable superglobal $_SESSION cuando la
   llamada de retorno read devuelva la información de sesión guardada a la gestión de sesiones de PHP.
  </para>
  <para>
   Para usar una sesión nominada llame a
   <function>session_name</function> antes de llamar a
   <function>session_start</function>.
  </para>
  <para>
   Cuando <link linkend="ini.session.use-trans-sid">session.use_trans_sid</link>
   está habilidado, la función <function>session_start</function> registrará
   un gestor de salida interno para la reescritura de URL.
  </para>
  <para>
   Si un usuario utiliza <literal>ob_gzhandler</literal> o similar con
   <function>ob_start</function>, el orden de las funciones es importante para
   la salida adecuada. Por ejemplo,
   <literal>ob_gzhandler</literal> se debe registrar antes de iniciar una sesión.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>options</parameter></term>
    <listitem>
     <para>
      Si se proporciona, este array asociativo de opciones sobrescribirá las
      <link linkend="session.configuration">directivas de configuración de sesiones</link>
      establecidas actualmente.
      Las claves no deben incluir el prefijo <literal>session.</literal>.
     </para>
     <para>
      Además del conjunto habitual de directivas de configuración, también se
      puede proporcionar la opción <literal>read_and_close</literal>. Si se establece a
      &true;, resultará en el cierre inmediato de la sesión después de haber
      sido leída, evitando así el bloqueo inncesario si los datos de la sesión
      no han cambiado.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Esta función devuleve &true; si una sesión fue iniciada satisfactoriamente,
   si no, devuelve &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.0.0</entry>
        <entry>
         Se añadió el parámetro <parameter>options</parameter>.
        </entry>
      </row>
      <row>
       <entry>5.3.0</entry>
       <entry>
        Si una sesión falla al iniciarse, se devuelve &false;.
        Anteriormente se devolvía &true;.
       </entry>
      </row>
      <row>
       <entry>4.3.3</entry>
       <entry>
        A partir de PHP 4.3.3, llamar a <function>session_start</function>
        después de que una sesión estuviera previamente iniciada resultaba en un
        error de nivel <constant>E_NOTICE</constant>. También, el
        segundo inicio de sesión se ignoraba simplemente.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <refsect2>
   <title>Un ejemplo de sesión básico</title>
   
   <para>
    <example>
     <title><filename>pagina1.php</filename></title>
     <programlisting role="php">
<![CDATA[
<?php
// pagina1.php

session_start();

echo 'Bienvenido a la página #1';

$_SESSION['color']  = 'verde';
$_SESSION['animal'] = 'gato';
$_SESSION['instante']   = time();

// Funciona si la cookie de sesión fue aceptada
echo '<br /><a href="pagina2.php">página 2</a>';

// O quizás pasar el id de sesión, si fuera necesario
echo '<br /><a href="pagina2.php?' . SID . '">página 2</a>';
?>
]]>
    </programlisting>
   </example>
   </para>
   <para>
    Después de ver <filename>pagina1.php</filename>, la segunda página
    <filename>pagina2.php</filename> contendrá mágicamente la información de la
    sesión. Consulte la <link linkend="ref.session">referencia de sesiones</link>
    para informarse sobre la <link linkend="session.idpassing">propagación de
    los ID de sesiones</link> ya que explica, por ejemplo, en qué consiste la constante
    <constant>SID</constant>.
   </para>
   <para>
    <example>
     <title><filename>pagina2.php</filename></title>
     <programlisting role="php">
<![CDATA[
<?php
// pagina2.php

session_start();

echo 'Bienvenido a la página #2<br />';

echo $_SESSION['color'];  // verde
echo $_SESSION['animal']; // gato
echo date('Y m d H:i:s', $_SESSION['instante']);

// Puede ser conveniente usar el SID aquí, como hicimos en pagina1.php
echo '<br /><a href="pagina1.php">página 1</a>';
?>
]]>
    </programlisting>
   </example>
   </para>
  </refsect2>
  <refsect2>
   <title>Proporcionar opciones a <function>session_start</function></title>
   
   <example>
    <title>Sobrescribir el tiempo de vida de la cookie</title>
    <programlisting role="php">
<![CDATA[
<?php
// Esto envía una cookie persistente que dura un día day.
session_start([
    'cookie_lifetime' => 86400,
]);
?>
]]>
    </programlisting>
   </example>
   
   <example>
    <title>Leer la sesión y cerrarla</title>
    <programlisting role="php">
<![CDATA[
<?php
// Si sabemos que no necesitamos cambiar nada de la sesión,
// podemos simplemente leerla y cerrarla inmediatamente para evitar
// bloquear el fichero de sesión y otras páginas
session_start([
    'cookie_lifetime' => 86400,
    'read_and_close'  => true,
]);
]]>
    </programlisting>
   </example>
  </refsect2>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Para usar sesiones basadas en cookies, <function>session_start</function>
    debe ser llamada antes de imprimir cualquier cosa en el navegador.
   </para>
  </note>
  <note>
   <para>
    Se recomienda el uso de <link linkend="ini.zlib.output-compression">zlib.output_compression</link>
    en vez de <function>ob_gzhandler</function>
   </para>
  </note>
  <note>
   <para>
    Esta función envía varias cabeceras HTTP dependiendo de la
    configuración. Véase <function>session_cache_limiter</function> para
    personalizar estas cabeceras.
   </para>
  </note>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><varname>$_SESSION</varname></member>
    <member>
     La directiva de configuarción <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
-->