Implemented info/example about deleting the session id cookie. Removed deprecated

use of session_unset() and wrote it as a note instead.  Implemented return.success,
and added see also.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@167763 c90b9560-bf6c-de11-be94-00142212c4b1

reference/session/functions/session-destroy.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/session.xml, last change in rev 1.2 -->
   <refentry id="function.session-destroy">
    <refnamediv>
@@ -18,50 +18,51 @@
      the global variables associated with the session, or unset the
      session cookie.
     </simpara>
+    <para>
+     In order to kill the session altogether, like to log the user out, the
+     session id must also be unset. If a cookie is used to propogate the 
+     session id (default behavior), then the session cookie must be deleted.  
+     <function>setcookie</function> may be used for that.
+    </para>
     <simpara>
-     This function returns &true; on success and 
-     &false; on failure to destroy
-     the session data.
+     &return.success;
     </simpara>
     <para>
      <example>
-      <title>Destroying a session</title>
+      <title>Destroying a session with <varname>$_SESSION</varname></title>
       <programlisting role="php">
 <![CDATA[
 <?php
-
 // Initialize the session.
 // If you are using session_name("something"), don't forget it now!
 session_start();
+
 // Unset all of the session variables.
-session_unset();
+$_SESSION = array();
+
+// If it's desired to kill the session, also delete the session cookie.
+// Note: This will destroy the session, and not just the session data!
+if (isset($_COOKIE[session_name()])) {
+    setcookie(session_name(), '', time()-42000, '/');
+}
+
 // Finally, destroy the session.
 session_destroy();
-
 ?>
 ]]>
       </programlisting>
      </example>
     </para>
+    <note>
+     <para>
+      Only use <function>session_unset</function> for older deprecated code 
+      that does not use <varname>$_SESSION</varname>.
+     </para>
+    </note>
     <para>
-     <example>
-      <title>Destroying a session with $_SESSION</title>
-      <programlisting role="php">
-<![CDATA[
-<?php
-
-// Initialize the session.
-// If you are using session_name("something"), don't forget it now!
-session_start();
-// Unset all of the session variables.
-$_SESSION = array();
-// Finally, destroy the session.
-session_destroy();
-
-?>
-]]>
-      </programlisting>
-     </example>
+     See also
+     <function>unset</function> and
+     <function>setcookie</function>.
     </para>
    </refsect1>
   </refentry>