diff --git a/reference/session/constants.xml b/reference/session/constants.xml new file mode 100644 index 0000000000..ab4c73bc7e --- /dev/null +++ b/reference/session/constants.xml @@ -0,0 +1,42 @@ + + +
+ &reftitle.constants; + &extension.constants; + + + + SID + (integer) + + + + Constant containing the session name and session ID in + the form of "name=ID". + + + + +
+ + + diff --git a/reference/session/reference.xml b/reference/session/reference.xml index 2748232535..a086c79c15 100644 --- a/reference/session/reference.xml +++ b/reference/session/reference.xml @@ -1,85 +1,289 @@ - + 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. - - - 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 - your site, PHP will check automatically (if session.auto_start is - set to 1) or on your request (explicitly through - session_start or implicitly through - session_register) whether a specific session - 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. - - - The track_vars and - register_globals - configuration settings influence how the session variables get - stored and restored. - - - + +
+ &reftitle.intro; - As of PHP 4.0.3, + + 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 + your site, PHP will check automatically (if session.auto_start is + set to 1) or on your request (explicitly through + session_start or implicitly through + session_register) whether a specific session + 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. + + + + Session handling was added in PHP 4.0. + + +
+ +
+ &reftitle.required; + &no.requirement; +
+ +
+ &reftitle.install; + + Session support is enabled in PHP by default. If you would + not like to build your PHP with session support, you should + specify the + option to configure. + +
+ +
+ &reftitle.runtime; + + 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. If + session.save_path's path depth is more than + 2, garbage collection will not be performed. + + + + If you leave this set to a world-readable directory, such as + /tmp (the default), other users on the + server may be able to hijack sessions by getting the list of + files in that directory. + + + + + + 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 starts a session automatically on request + startup. Defaults to 0 (disabled). + + + + + session.cookie_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 contains the substring you + want to check each HTTP Referer for. If the Referer was sent by the + client and the substring was not found, the embedded session id will + be marked as invalid. Defaults to the empty string. + + + + + 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.use_only_cookies specifies whether the + module will only use cookies to + store the session id on the client side. Defaults to + 0 (disabled, for backward compatibility). Enabling + this setting prevents attacks involved passing session ids in URLs. + This setting was added in PHP 4.3.0. + + + + + session.cookie_path specifies path to set + in session_cookie. Defaults to /. + + + + + session.cookie_domain specifies domain to + set in session_cookie. Default is none at all. + + + + + session.cache_limiter specifies cache + control method to use for session pages + (none/nocache/private/private_no_expire/public). Defaults to + nocache. + + + + + session.cache_expire specifies time-to-live + for cached session pages in minutes, this has no effect for + nocache limiter. Defaults to 180. + + + + + session.use_trans_sid whether transparent sid support + is enabled or not if enabled by compiling with + + --enable-trans-sid. + Defaults to 1 (enabled). + + + + + url_rewriter.tags spefifies which html tags are + rewritten to include session id if transparent sid support is enabled. + Defaults to a=href,area=href,frame=src,input=src,form=fakeentry + + + + + + The track_vars and + register_globals + configuration settings influence how the session variables get + stored and restored. + + + + + As of PHP 4.0.3, track_vars is + always turned on. + + +
+ +
+ &reftitle.resources; + &no.resource; +
+ + &reference.session.constants; + +
+ &reftitle.examples; + + + 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. + + + + + If 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. - - - - - If track_vars is - enabled and register_globals - is disabled, only members of the global associative array - $HTTP_SESSION_VARS can be registered as session - variables. The restored session variables will only be available - in the array $HTTP_SESSION_VARS. - - - Registering a variable with <link - linkend="ini.track-vars"><literal>track_vars</literal></link> - enabled - - + enabled and register_globals + is disabled, only members of the global associative array + $HTTP_SESSION_VARS can be registered as session + variables. The restored session variables will only be available + in the array $HTTP_SESSION_VARS. + + + Registering a variable with <link + linkend="ini.track-vars"><literal>track_vars</literal></link> + enabled + + ]]> - - - - - Use of $_SESSION (or - $HTTP_SESSION_VARS with PHP 4.0.6 or less) is - recommended for security and code readablity. 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. - - + + + + + Use of $_SESSION (or + $HTTP_SESSION_VARS with PHP 4.0.6 or less) is + recommended for security and code readablity. 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. - - + + + + + Unregistering a variable with $_SESSION. + + ]]> - - - - - If 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. 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(). - - - If you are using - $HTTP_SESSION_VARS/$_SESSION - and disable register_globals, - do not use session_register, - session_is_registered and - session_unregister. - - - If you enable + + + + If 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. 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(). + + + If you are using + $HTTP_SESSION_VARS/$_SESSION + and disable register_globals, - session_unregister should be used since - session variables are registered as global variables when - session data is deserialized. Disabling session_register, + session_is_registered and + session_unregister. + + + If you enable register_globals, + session_unregister should be used since + session variables are registered as global variables when + session data is deserialized. Disabling register_globals + is recommended for both security and performance reason. + + + + + Registering a variable with <link linkend="ini.register-globals"><literal>register_globals</literal></link> - is recommended for both security and performance reason. - </para> - </caution> - <example> - <title> - Registering a variable with <link - linkend="ini.register-globals"><literal>register_globals</literal></link> - enabled - - + enabled + + ]]> - - - - - If both track_vars and - register_globals - are enabled, then the globals variables and the - $HTTP_SESSION_VARS/$_SESSION - entries will reference the same value for already registered - variables. - - - If user use session_register() to register session variable, - $HTTP_SESSION_VARS/$_SESSION - will not have these variable in array until it is loaded from - session storage. (i.e. until next request) - - - There are two methods to propagate a session id: - - - - 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, - relative URIs will be changed to contain the session id - automatically. Alternatively, you can use the constant - SID which is defined, if the client did not - send the appropriate cookie. SID is either of - the form session_name=session_id or is an empty - string. - - - The arg_separator.output - &php.ini; directive allows to customize the argument seperator. - - - - - 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 - + + + + + If both track_vars and + register_globals + are enabled, then the globals variables and the + $HTTP_SESSION_VARS/$_SESSION + entries will reference the same value for already registered + variables. + + + If user use session_register() to register session variable, + $HTTP_SESSION_VARS/$_SESSION + will not have these variable in array until it is loaded from + session storage. (i.e. until next request) + +
+ +
+ Passing the Session ID + + There are two methods to propagate a session id: + + + + 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, + relative URIs will be changed to contain the session id + automatically. Alternatively, you can use the constant + SID which is defined, if the client did not + send the appropriate cookie. SID is either of + the form session_name=session_id or is an empty + string. + + + The arg_separator.output + &php.ini; directive allows to customize the argument seperator. + + + + + 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 + times.

; To continue, click here ]]> - - - - - The <?=SID?> is not necessary, if - - --enable-trans-sid was used to compile PHP. - - - - Non-relative URLs are assumed to point to external sites and - hence don't append the SID, as it would be a security risk to - leak the SID to a different server. + + + + + The <?=SID?> is not necessary, if + + --enable-trans-sid was used to compile PHP. - - - To implement database storage, or any other storage method, you - will need to use session_set_save_handler to - create a set of user-level storage functions. - - - 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. If - session.save_path's path depth is more than - 2, garbage collection will not be performed. - - - - If you leave this set to a world-readable directory, such as - /tmp (the default), other users on the - server may be able to hijack sessions by getting the list of - files in that directory. - - - - - - 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 starts a session automatically on request - startup. Defaults to 0 (disabled). - - - - - session.cookie_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 contains the substring you - want to check each HTTP Referer for. If the Referer was sent by the - client and the substring was not found, the embedded session id will - be marked as invalid. Defaults to the empty string. - - - - - 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.use_only_cookies specifies whether the - module will only use cookies to - store the session id on the client side. Defaults to - 0 (disabled, for backward compatibility). Enabling - this setting prevents attacks involved passing session ids in URLs. - This setting was added in PHP 4.3.0. - - - - - session.cookie_path specifies path to set - in session_cookie. Defaults to /. - - - - - session.cookie_domain specifies domain to - set in session_cookie. Default is none at all. - - - - - session.cache_limiter specifies cache - control method to use for session pages - (none/nocache/private/private_no_expire/public). Defaults to - nocache. - - - - - session.cache_expire specifies time-to-live - for cached session pages in minutes, this has no effect for - nocache limiter. Defaults to 180. - - - - - session.use_trans_sid whether transparent sid support - is enabled or not if enabled by compiling with - - --enable-trans-sid. - Defaults to 1 (enabled). - - - - - url_rewriter.tags spefifies which html tags are - rewritten to include session id if transparent sid support is enabled. - Defaults to a=href,area=href,frame=src,input=src,form=fakeentry - - - - Session handling was added in PHP 4.0. + Non-relative URLs are assumed to point to external sites and + hence don't append the SID, as it would be a security risk to + leak the SID to a different server. - +

+ +
+ Custom Session Handlers + + To implement database storage, or any other storage method, you + will need to use session_set_save_handler to + create a set of user-level storage functions. + +
&reference.session.functions;