From ffa28a4690fc8d2ab203f5f12bc67da5a54a6120 Mon Sep 17 00:00:00 2001 From: Egon Schmid Date: Thu, 24 Feb 2000 07:03:05 +0000 Subject: [PATCH] Some cosmetics. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@20310 c90b9560-bf6c-de11-be94-00142212c4b1 --- functions/session.xml | 452 +++++++++++++++++++++++------------------- 1 file changed, 253 insertions(+), 199 deletions(-) diff --git a/functions/session.xml b/functions/session.xml index 9e12a1bd69..40b5bb5e77 100644 --- a/functions/session.xml +++ b/functions/session.xml @@ -1,24 +1,23 @@ Session handling functions Sessions + Session support in PHP consists of a way to preserve certain data across subsequent accesses. This enables you to build more customized applications and increase the appeal of your web site. - - If you are familiar with the session management of PHPLIB, you will notice - that some concepts are similar to PHP's session support. + If you are familiar with the session management of PHPLIB, you + will notice that some concepts are similar to PHP's session + support. - A visitor accessing your web site is assigned an unique id, the so-called session id. This is either stored in a cookie on the user side or is propagated in the URL. - The session support allows you to register arbitrary numbers of variables to be preserved across requests. When a visitor accesses @@ -29,14 +28,12 @@ id has been sent with the request. If this is the case, the prior saved environment is recreated. - All registered variables are serialized after the request finishes. Registered variables which are undefined are marked as being not defined. On subsequent accesses, these are not defined by the session module unless the user defines them later. - track_vars and gpc_globals configuration settings influence how the session variables get @@ -48,24 +45,27 @@ both of these settings are enabled, then the globals variables and the $HTTP_STATE_VARS entries will reference the same value. - There are two methods to propagate a session id: - - - Cookies - - URL parameter - - + + + Cookies + + + + + URL parameter + + + + The session module supports both methods. Cookies are optimal, but since they are not reliable (clients are not bound to accept them), we cannot rely on them. The second method embeds the session id directly into URLs. - PHP is capable of doing this transparently when compiled with --enable-trans-sid. If you enable this option, @@ -76,32 +76,28 @@ the form session_name=session_id or is an empty string. - The following example demonstrates how to register a variable, and how to link correctly to another page using SID. - - - Counting the number of hits of a single user - + + Counting the number of hits of a single user + <?php - session_register("count"); - $count++; - ?> Hello visitor, you have seen this page <? echo $count; ?> times.<p> -<? +<php? # the <?=SID?> is necessary to preserve the session id # in the case that the user has disabled cookies ?> - To continue, <A HREF="nextpage.php?<?=SID?>">click here</A> - - +To continue, <A HREF="nextpage.php?<?=SID?>">click here</A> + + + To implement database storage you need PHP code and a user level function session_set_save_handler. You would @@ -116,12 +112,12 @@ Hello visitor, you have seen this page <? echo $count; ?> times.<p> <?php -function open ( $save_path, $session_name ) { +function open ($save_path, $session_name) { echo "open ($save_path, $session_name)\n"; return true; } -function close () { +function close() { echo "close\n"; return true; } @@ -144,7 +140,7 @@ function gc ($maxlifetime) { return true; } -session_set_save_handler("open", "close", "read", "write", "destroy", "gc"); +session_set_save_handler ("open", "close", "read", "write", "destroy", "gc"); session_start(); @@ -154,11 +150,9 @@ $foo++; - Will produce this results: - $ ./php save_handler.php @@ -171,104 +165,120 @@ write (f08b925af0ecb52bdd2de97d95cdbe6b, foo|i:2;) close - The <?=SID?> is not necessary, if --enable-trans-sid was used to compile PHP. - The session management system supports a number of configuration options which you can place in your php.ini file. We will give a short overview. - - - session.save_handler defines the name of the - handler which is used for storing and retrieving data associated - with a session. Defaults to - files. - - - session.save_path 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 /tmp. - - - session.name specifies the name of the - session which is used as cookie name. It should only contain - alphanumeric characters. Defaults to - PHPSESSID. - - - session.auto_start specifies whether the - session module start a session automatically on request - startup. Defaults to 0 - (disabled). - - - session.lifetime specifies the lifetime of - the cookie in seconds which is sent to the browser. The value 0 - means "until the browser is closed." Defaults to - 0. - - - session.serialize_handler defines the name of - the handler which is used to serialize/deserialize - data. Currently, a PHP internal format (name - php) and WDDX is supported (name - wddx). WDDX is only available, if PHP is - compiled with WDDX - support. Defaults to - php. - - - session.gc_probability specifies the - probability that the gc (garbage collection) routine is started - on each request in percent. Defaults to - 1. - - - session.gc_maxlifetime specifies the number - of seconds after which data will be seen as 'garbage' and - cleaned up. - - - session.referer_check determines - whether session ids referred to by external sites will be - eliminated. If session ids are propagated using the URL method, - users not knowing about the impact might publish session - ids. This can lead to security problems which this check tries - to defeat. Defaults to - 0. - - - session.entropy_file gives a path to an - external resource (file) which will be used as an additional - entropy source in the session id creation process. Examples are - /dev/random or - /dev/urandom which are available on many Unix - systems. - - - session.entropy_length specifies the number - of bytes which will be read from the file specified - above. Defaults to 0 - (disabled). - - - session.use_cookies specifies whether the - module will use cookies to store the session id on the client - side. Defaults to 1 - (enabled). - + + + session.save_handler defines the name of the + handler which is used for storing and retrieving data + associated with a session. Defaults to + files. + + + + + session.save_path 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 /tmp. + + + + + session.name specifies the name of the + session which is used as cookie name. It should only contain + alphanumeric characters. Defaults to + PHPSESSID. + + + + + session.auto_start specifies whether the + session module start a session automatically on request + startup. Defaults to 0 (disabled). + + + + + session.lifetime specifies the lifetime of + the cookie in seconds which is sent to the browser. The value 0 + means "until the browser is closed." Defaults to + 0. + + + + + session.serialize_handler defines the name + of the handler which is used to serialize/deserialize + data. Currently, a PHP internal format (name + php) and WDDX is supported (name + wddx). WDDX is only available, if PHP is + compiled with WDDX + support. Defaults to php. + + + + + session.gc_probability specifies the + probability that the gc (garbage collection) routine is started + on each request in percent. Defaults to 1. + + + + + session.gc_maxlifetime specifies the number + of seconds after which data will be seen as 'garbage' and + cleaned up. + + + + + session.referer_check determines whether + session ids referred to by external sites will be + eliminated. If session ids are propagated using the URL method, + users not knowing about the impact might publish session + ids. This can lead to security problems which this check tries + to defeat. Defaults to 0. + + + + + session.entropy_file gives a path to an + external resource (file) which will be used as an additional + entropy source in the session id creation process. Examples are + /dev/random or + /dev/urandom which are available on many + Unix systems. + + + + + session.entropy_length specifies the number + of bytes which will be read from the file specified + above. Defaults to 0 (disabled). + + + + + session.use_cookies specifies whether the + module will use cookies to store the session id on the client + side. Defaults to 1 (enabled). + + - - - - Session handling was added in PHP 4.0. - + + + Session handling was added in PHP 4.0. + + + @@ -287,10 +297,12 @@ close the current one based on the session id being passed via a GET variable or a cookie). - This function always returns true. + This function always returns true. + - This function was added in PHP 4.0. + This function was added in PHP 4.0. + @@ -308,12 +320,15 @@ close session_destroy destroys all of the data - associated with the current session. + associated with the current session. + - This function always returns true. + This function always returns true. + - This function was added in PHP 4.0. + This function was added in PHP 4.0. + @@ -327,36 +342,41 @@ close Description string session_name - string name + string + name + session_name returns the name of the current session. If name is specified, the name of - the current session is changed to its value. + the current session is changed to its value. + - The session name references the session id in cookies and URLs. It should - contain only alphanumeric characters; it should be short and descriptive - (i.e. for users with enabled cookie warnings). The session name is - resetted to the default value stored in session.name - at request startup time. Thus, you need to call - session_name for every request (and before - session_start or - session_register are called). + The session name references the session id in cookies and + URLs. It should contain only alphanumeric characters; it should + be short and descriptive (i.e. for users with enabled cookie + warnings). The session name is resetted to the default value + stored in session.name at request startup + time. Thus, you need to call session_name + for every request (and before session_start + or session_register are called). + <function>session_name</function> examples - + <?php # set the session name to WebsiteID -$previous_name = session_name("WebsiteID"); +$previous_name = session_name ("WebsiteID"); echo "The previous session name was $previous_name<p>"; - This function was added in PHP 4.0. + This function was added in PHP 4.0. + @@ -370,16 +390,20 @@ echo "The previous session name was $previous_name<p>"; Description string session_module_name - string module + string + module + - session_module_name returns the name of the current - session module. If module is specified, that - module will be used instead. - - - This function was added in PHP 4.0. - + session_module_name returns the name of the + current session module. If module is + specified, that module will be used instead. + + + This function was added in PHP 4.0. + + + @@ -392,23 +416,28 @@ echo "The previous session name was $previous_name<p>"; Description string session_save_path - string path + string + path + session_save_path returns the path of the current directory used to save session data. If path is specified, the path to which data is saved will be changed. - - - On some operating systems, you may want to specify a path on - a filesystem that handles lots of small files efficiently. For - example, on Linux, reiserfs may provide better performance than - ext2fs. - - - - This function was added in PHP 4.0. - + + + On some operating systems, you may want to specify a path on a + filesystem that handles lots of small files efficiently. For + example, on Linux, reiserfs may provide better performance than + ext2fs. + + + + + This function was added in PHP 4.0. + + + @@ -424,27 +453,34 @@ echo "The previous session name was $previous_name<p>"; string id - session_id returns the session id for the current - session. If id is specified, it will replace - the current session id. + session_id returns the session id for the + current session. If id is specified, it + will replace the current session id. + - directory used to save session data. If path - is specified, the path to which data is saved will be changed. + directory used to save session data. If + path is specified, the path to which data + is saved will be changed. + - The constant SID can also be used to retrieve - the current name and session id as a string suitable for adding to - URLs. - - - This function was added in PHP 4.0. - + The constant SID can also be used to + retrieve the current name and session id as a string suitable for + adding to URLs. + + + This function was added in PHP 4.0. + + + session_register - Register one or more variables with the current session + + Register one or more variables with the current session + Description @@ -460,21 +496,26 @@ echo "The previous session name was $previous_name<p>"; variable name or an array consisting of such variable names or other arrays. For each encountered variable name, session_register registers the global - variable named by it with the current session. + variable named by it with the current session. + This function returns true when the variable is successfully registered with the session. - - - This function was added in PHP 4.0. - + + + This function was added in PHP 4.0. + + + session_unregister - Unregister a variable from the current session + + Unregister a variable from the current session + Description @@ -485,21 +526,26 @@ echo "The previous session name was $previous_name<p>"; session_unregister unregisters (forgets) the global variable named name from the - current session. + current session. + This function returns true when the variable is successfully unregistered from the session. - - - This function was added in PHP 4.0. - + + + This function was added in PHP 4.0. + + + session_is_registered - Find out if a variable is registered in a session + + Find out if a variable is registered in a session + Description @@ -509,12 +555,14 @@ echo "The previous session name was $previous_name<p>"; session_is_registered returns true if there - is a variable with the name name registered - in the current session. - - - This function was added in PHP 4.0. - + is a variable with the name name + registered in the current session. + + + This function was added in PHP 4.0. + + + @@ -533,17 +581,21 @@ echo "The previous session name was $previous_name<p>"; session_decode decodes the session data in data, setting variables stored in the session. - - - This function was added in PHP 4.0. - + + + This function was added in PHP 4.0. + + + session_encode - Encodes the current session data as a string + + Encodes the current session data as a string + Description @@ -554,10 +606,12 @@ echo "The previous session name was $previous_name<p>"; session_encode returns a string with the contents of the current session encoded within. - - - This function was added in PHP 4.0. - + + + This function was added in PHP 4.0. + + +