From 10448f3d83ff9d11ac4db96e9fc0d4e37b5e191e Mon Sep 17 00:00:00 2001 From: Yasuo Ohgaki Date: Mon, 7 Jan 2002 11:23:25 +0000 Subject: [PATCH] Add more description for $_SESSION and $HTTP_SESSION_VARS. # Hopefully, there will be less bug reports. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@67219 c90b9560-bf6c-de11-be94-00142212c4b1 --- functions/session.xml | 163 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 144 insertions(+), 19 deletions(-) diff --git a/functions/session.xml b/functions/session.xml index dca8b938fb..f3f5eb95c6 100644 --- a/functions/session.xml +++ b/functions/session.xml @@ -1,5 +1,5 @@ - + Session handling functions Sessions @@ -51,6 +51,12 @@ linkend="ini.track-vars">track_vars is always turned on. + + As of PHP 4.1.0, $_SESSION is available as global variable just + like $_POST, $_GET, $_REQUEST and so on. Not like + $HTTP_SESSION_VARS, $_SESSION is always global. Therefore, + global should not be used for $_SESSION. + @@ -71,8 +77,51 @@ +]]> + + + + + Use of $_SESSION (or $HTTP_SESSION_VARS with PHP 4.0.6 or less) is + recommended for security and code readablility. With $_SESSION or + $HTTP_SESSION_VARS, there is no need to use + session_register()/session_unregister()/session_is_registered() + functions. Users can access session variable like a normal + variable. + + + Registering a variable with $_SESSION. + + + +]]> + + + + + Unregistering a variable with $_SESSION. + + + ]]> @@ -83,8 +132,12 @@ $HTTP_SESSION_VARS["count"]++; linkend="ini.register-globals">register_globals is enabled, then all global variables can be registered as session variables and the session variables will be restored to - corresponding global variables. - + corresponding global variables. Since PHP must know which global + variables are registered as session variables, users must register + variables with session_register() function while + $HTTP_SESSION_VARS/$_SESSION does not need to use + session_register(). + Registering a variable with <link linkend="ini.register-globals"><literal>register_globals</literal></link> @@ -93,8 +146,13 @@ $HTTP_SESSION_VARS["count"]++; <programlisting role="php"> <![CDATA[ <?php -session_register("count"); -$count++; +if (!session_is_registered('count')) { + session_register("count"); + $count = 0; +} +else { + $count++; +} ?> ]]> </programlisting> @@ -148,8 +206,13 @@ $count++; <programlisting role="php"> <![CDATA[ <?php -session_register ("count"); -$count++; +if (!session_is_registered('count')) { + session_register('count'); + $count = 1; +} +else { + $count++; +} ?> Hello visitor, you have seen this page <?php echo $count; ?> times.<p>; @@ -199,7 +262,9 @@ To continue, <A HREF="nextpage.php?<?=SID?>">click here</A> <literal>session.save_path</literal> defines the argument which is passed to the save handler. If you choose the default files handler, this is the path where the files are created. - Defaults to <literal>/tmp</literal>. + Defaults to <literal>/tmp</literal>. If + <literal>session.save_path</literal>'s path depth is more than + 2, garbage collection will not be performed. </simpara> <warning> <para> @@ -293,13 +358,13 @@ To continue, <A HREF="nextpage.php?<?=SID?>">click here</A> <listitem> <simpara> <literal>session.cookie_path</literal> specifies path to set - in session_cookie. Defaults to <literal>/</literal>. + in session_cookie. Defaults to <literal>/</literal>. </simpara> </listitem> <listitem> <simpara> <literal>session.cookie_domain</literal> specifies domain to - set in session_cookie. Default is none at all. + set in session_cookie. Default is none at all. </simpara> </listitem> <listitem> @@ -374,6 +439,20 @@ To continue, <A HREF="nextpage.php?<?=SID?>">click here</A> browser. </para> </note> + <simpara> + <function>session_start</function> will register internal output + handler for URL rewriting when <literal>trans-sid</literal> is + enabled. If a user uses <literal>ob_gzhandler</literal> or like + with <function>ob_start</function>, the order of output handler + is important for proper output. For example, user must register + <literal>ob_gzhandler</literal> before session start. + </simpara> + <note> + <simpara> + Use of <literal>zlib.output_compression</literal> is recommended + rather than <literal>ob_gzhandler</literal> + </simpara> + </note> </refsect1> </refentry> @@ -408,12 +487,32 @@ To continue, <A HREF="nextpage.php?<?=SID?>">click here</A> <![CDATA[ <?php -# Initialize the session. -# If you are using session_name("something"), don't forget it now! +// Initialize the session. +// If you are using session_name("something"), don't forget it now! session_start(); -# Unset all of the session variables. +// Unset all of the session variables. session_unset(); -# Finally, destroy the session. +// Finally, destroy the session. +session_destroy(); + +?> +]]> + </programlisting> + </example> + </para> + <para> + <example> + <title>Destroying a session with $_SESSION + + @@ -460,9 +559,9 @@ session_destroy(); "; ?> @@ -622,6 +721,11 @@ $_SESSION["spongebob"] = "He's got square pants."; list of functions that return resources are available in the resource types appendix. + + If $_SESSION (or $HTTP_SESSION_VARS for PHP 4.0.6 or less) is + used, assign variable to $_SESSION. i.e. $_SESSION['var'] = + 'ABC'; + See also session_is_registered and @@ -654,6 +758,13 @@ $_SESSION["spongebob"] = "He's got square pants."; This function returns &true; when the variable is successfully unregistered from the session. + + + If $_SESSION (or $HTTP_SESSION_VARS for PHP 4.0.6 or less) is + used, use unset to unregister a session + variable. + + This function doesn't unset the corresponding global variable for @@ -684,6 +795,13 @@ $_SESSION["spongebob"] = "He's got square pants."; The session_unset function free's all session variables currently registered. + + + If $_SESSION (or $HTTP_SESSION_VARS for PHP 4.0.6 or less) is + used, use unset to unregister session + variable. i.e. unset($_SESSION)); + + @@ -707,6 +825,13 @@ $_SESSION["spongebob"] = "He's got square pants."; is a variable with the name name registered in the current session. + + + If $_SESSION (or $HTTP_SESSION_VARS for PHP 4.0.6 or less) is + used, use isset to check a variable is + registered in $_SESSION. + + @@ -913,7 +1038,7 @@ function read ($id) { $sess_data = fread($fp, filesize($sess_file)); return($sess_data); } else { - return(""); + return(""); // Must return ("") here. } }