session-start.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 151e61773c016edcae8fd4989ad9a86ffd03c283 Maintainer: jpauli Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="function.session-start" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>session_start</refname>
  <refpurpose>Démarre une nouvelle session ou reprend une session existante</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> crée une session ou
   restaure celle trouvée sur le serveur, via l'identifiant
   de session passé dans une requête GET, POST ou par un cookie.
  </para>
  <para>
   Lorsque <function>session_start</function> est appelée ou lorsqu'une session démarre
   toute seule, PHP va appeler les gestionnaires d'ouverture et de lecture. Ce sont des
   gestionnaires internes fournis par PHP (comme fichiers, SQLite ou Memcached) ou encore
   des gestionnaires personnalisés définis au moyen de
   <function>session_set_save_handler</function>. La fonction de lecture va récupérer toute
   session existante (stockée sous forme sérialisée) et va désérialiser les données pour peupler
   $_SESSION.
  </para>
  <para>
   Pour utiliser une session nommée, vous devez
   appeler <function>session_name</function> avant d'appeler
   <function>session_start</function>.
  </para>
  <para>
   Lorsque <link linkend="ini.session.use-trans-sid">session.use_trans_sid</link>
   est activée, la fonction <function>session_start</function> enregistrera un
   gestionnaire interne de sortie pour la réécriture d'URL. 
  </para>
  <para>
   Si un utilisateur utilise <literal>ob_gzhandler</literal> ou l'équivalent
   <function>ob_start</function>, l'ordre d'appel des fonctions est important
   pour une sortie correcte. Par exemple, 
   <literal>ob_gzhandler</literal> doit être enregistré avant de démarrer la session.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>options</parameter></term>
    <listitem>
     <para>
      S'il est fourni, il s'agit d'un tableau associatif d'options qui remplacera 
      <link linkend="session.configuration">les directives de configuration de session</link> 
      actuellement définies.
      Les clés ne doivent pas inclure le préfixe <literal>session.</literal>.
     </para>
     <para>
      En plus de l'ensemble normal des directives de configuration, une option 
      <literal>read_and_close</literal> peut également être fournie. Si la 
      valeur est définie sur &true;, cela entraîne la fermeture immédiate de 
      la session après la lecture, ce qui évite tout blocage inutile si les 
      données de session ne sont pas modifiées.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne &true; si une session a pu être démarrée avec succès, et &false; sinon.
  </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> retourne maintenant &false; et 
        n'initialise plus <varname>$_SESSION</varname> lorsqu'il n'a pas pu 
        démarrer la session.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <refsect2>
   <title>Un exemple de session de base</title>
   
  <para>
   <example>
    <title><filename>page1.php</filename></title>
    <programlisting role="php">
<![CDATA[
<?php
// page1.php

session_start();

echo 'Bienvenue à la page numéro 1';

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

// Fonctionne si le cookie a été accepté
echo '<br /><a href="page2.php">page 2</a>';

// Ou bien, en indiquant explicitement l'identfiant de session
echo '<br /><a href="page2.php?' . SID . '">page 2</a>';
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Après avoir vu la page <filename>page1.php</filename> avec un navigateur,
   la seconde page <filename>page2.php</filename> (dont le code suit) va magiquement afficher
   les données de session. Lisez la référence sur
   les  <link linkend="ref.session">sessions</link> pour des informations
   sur la <link linkend="session.idpassing">propagation des identifiants de session</link>,
   et l'utilisation de la constante <constant>SID</constant>.
  </para>
  <para>
   <example>
    <title>Récupération de la session : <filename>page2.php</filename></title>
    <programlisting role="php">
<![CDATA[
<?php
// page2.php

session_start();

echo 'Bienvenue sur la page numéro 2<br />';

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

// Vous pourriez utiliser la constante SID ici, tout comme dans la page page1.php
echo '<br /><a href="page1.php">page 1</a>';
?>
]]>
    </programlisting>
   </example>
  </para>
  </refsect2>
  <refsect2>
   <title>Fournir des options à <function>session_start</function></title>

   <example>
    <title>Remplacement de la durée de vie du cookie</title>
    <programlisting role="php">
<![CDATA[
<?php
// Cela envoie un cookie persistant qui dure une journée.
session_start([
    'cookie_lifetime' => 86400,
]);
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Lecture de la session et fermeture</title>
    <programlisting role="php">
<![CDATA[
<?php
// Si nous savons que nous n'avons pas besoin de changer 
// quoi que ce soit dans la session, nous pouvons juste 
// lire et fermer tout de suite pour éviter de verrouiller 
// le fichier de session et bloquer d'autres pages
session_start([
    'cookie_lifetime' => 86400,
    'read_and_close'  => true,
]);
]]>
    </programlisting>
   </example>
  </refsect2>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Pour utiliser des sessions basées sur les cookies, <function>session_start</function>
    doit être appelée avant d'afficher quoi que ce soit dans le navigateur.
   </para>
  </note>
  <note>
   <para>
    L'utilisation de
    <link linkend="ini.zlib.output-compression"><option>zlib.output_compression</option></link>
    est recommandée, à la place de <function>ob_gzhandler</function>.
   </para>
  </note>
  <note>
   <para>
    Cette fonction va émettre plusieurs entêtes HTTP, en fonction
    de la configuration. Voyez <function>session_cache_limiter</function> pour
    personnaliser ces entêtes.
   </para>
  </note>  
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><varname>$_SESSION</varname></member>
    <member>
     La directive de configuration <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
-->