From f16f0a48ead24a3ce208c902fa50c2b159791aef Mon Sep 17 00:00:00 2001 From: Mehdi Achour Date: Fri, 15 Jun 2007 00:16:49 +0000 Subject: [PATCH] ref.session: new doc style git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@237708 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../functions/session-cache-expire.xml | 85 ++++++--- .../functions/session-cache-limiter.xml | 102 ++++++++--- .../session/functions/session-commit.xml | 3 +- .../session/functions/session-decode.xml | 41 ++++- .../session/functions/session-destroy.xml | 43 +++-- .../session/functions/session-encode.xml | 25 ++- .../functions/session-get-cookie-params.xml | 75 ++++++-- reference/session/functions/session-id.xml | 3 +- .../functions/session-is-registered.xml | 55 ++++-- .../session/functions/session-module-name.xml | 38 +++- reference/session/functions/session-name.xml | 96 ++++++++--- .../functions/session-regenerate-id.xml | 4 +- .../session/functions/session-register.xml | 162 +++++++++++------- .../session/functions/session-save-path.xml | 72 +++++--- .../functions/session-set-cookie-params.xml | 122 +++++++++++-- .../functions/session-set-save-handler.xml | 148 +++++++++++----- reference/session/functions/session-start.xml | 126 +++++++++----- .../session/functions/session-unregister.xml | 58 +++++-- reference/session/functions/session-unset.xml | 49 +++--- .../session/functions/session-write-close.xml | 31 ++-- 20 files changed, 958 insertions(+), 380 deletions(-) diff --git a/reference/session/functions/session-cache-expire.xml b/reference/session/functions/session-cache-expire.xml index 3a3b532153..03f9833e24 100644 --- a/reference/session/functions/session-cache-expire.xml +++ b/reference/session/functions/session-cache-expire.xml @@ -1,23 +1,20 @@ - - + session_cache_expire Return current cache expire - - Description + + + &reftitle.description; intsession_cache_expire intnew_cache_expire session_cache_expire returns the current setting of - session.cache_expire. The value returned should be read - in minutes, defaults to 180. If new_cache_expire - is given, the current cache expire is replaced with - new_cache_expire. + session.cache_expire. The cache expire is reset to the default value of 180 stored in @@ -25,9 +22,48 @@ you need to call session_cache_expire for every request (and before session_start is called). - - <function>session_cache_expire</function> example - + + + + &reftitle.parameters; + + + + new_cache_expire + + + If new_cache_expire is given, the current cache + expire is replaced with new_cache_expire. + + + + + Setting new_cache_expire is of value only, if + session.cache_limiter is set to a value + different from nocache. + + + + + + + + + + + &reftitle.returnvalues; + + Returns the current setting of session.cache_expire. + The value returned should be read in minutes, defaults to 180. + + + + + &reftitle.examples; + + + <function>session_cache_expire</function> example + "; echo "The cached session pages expire after $cache_expire minutes"; ?> ]]> - - - - - Setting new_cache_expire is of value only, if - session.cache_limiter is set to a value - different from nocache. - - - - See also the configuration settings - session.cache_expire, - session.cache_limiter and session_cache_limiter. + + + + + &reftitle.seealso; + + + session.cache_expire + session.cache_limiter + session_cache_limiter + + + + - + session_cache_limiter Get and/or set the current cache limiter - - Description + + + &reftitle.description; stringsession_cache_limiter stringcache_limiter session_cache_limiter returns the name of the - current cache limiter. If cache_limiter - is specified, the name of the current cache limiter is changed to the - new value. + current cache limiter. The cache limiter defines which cache control HTTP headers are sent to @@ -28,17 +26,11 @@ and permits the client to cache the contents. - In private mode, the Expire header sent to the - client may cause confusion for some browsers, including Mozilla. - You can avoid this problem by using - private_no_expire mode. The expire header is never - sent to the client in this mode. + In private mode, the Expire header sent to the client + may cause confusion for some browsers, including Mozilla. You can avoid + this problem by using private_no_expire mode. The + expire header is never sent to the client in this mode. - - - private_no_expire was added in PHP 4.2.0. - - The cache limiter is reset to the default value stored in session.cache_limiter @@ -46,9 +38,62 @@ session_cache_limiter for every request (and before session_start is called). - - <function>session_cache_limiter</function> example - + + + + &reftitle.parameters; + + + + cache_limiter + + + If cache_limiter is specified, the name of the + current cache limiter is changed to the new value. + + + + + + + + + &reftitle.returnvalues; + + Returns the name of the current cache limiter. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 4.2.0 + + The private_no_expire cache limiter was added. + + + + + + + + + + &reftitle.examples; + + + <function>session_cache_limiter</function> example + "; ?> ]]> - - - - Also see the session.cache_limiter - configuration directive. + + + + + &reftitle.seealso; + + + session.cache_limiter + + + + + session_commit @@ -13,6 +13,7 @@ session_write_close. + - + session_decode Decodes session data from a string - - Description + + + &reftitle.description; boolsession_decode stringdata @@ -17,11 +17,40 @@ data, setting variables stored in the session. + + + + &reftitle.parameters; - See also - session_encode. + + + data + + + The encoded data to be stored. + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.seealso; + + + session_encode + + + + - + session_destroy Destroys all data registered to a session - - Description + + + &reftitle.description; boolsession_destroy - session_destroy destroys all of the data - associated with the current session. It does not unset any of - the global variables associated with the session, or unset the - session cookie. + session_destroy destroys all of the data associated + with the current session. It does not unset any of the global variables + associated with the session, or unset the session cookie. In order to kill the session altogether, like to log the user out, the @@ -24,9 +23,17 @@ session id (default behavior), then the session cookie must be deleted. setcookie may be used for that. - + + + + &reftitle.returnvalues; + &return.success; - + + + + + &reftitle.examples; Destroying a session with <varname>$_SESSION</varname> @@ -53,18 +60,28 @@ session_destroy(); + + + + &reftitle.notes; Only use session_unset for older deprecated code that does not use $_SESSION. + + + + &reftitle.seealso; - See also - unset and - setcookie. + + unset + setcookie + + - + session_encode Encodes the current session data as a string - - Description + + + &reftitle.description; stringsession_encode @@ -16,11 +16,24 @@ session_encode returns a string with the contents of the current session encoded within. + + + + &reftitle.returnvalues; - See also - session_decode + Returns the contents of the current session encoded. + + + &reftitle.seealso; + + + session_decode + + + + - + session_get_cookie_params Get the session cookie parameters - - Description + + + &reftitle.description; arraysession_get_cookie_params - The session_get_cookie_params function returns an - array with the current session cookie information, the array contains - the following items: + Gets the session cookie parameters. + + + + + &reftitle.returnvalues; + + Returns an array with the current session cookie information, the array + contains the following items: @@ -35,27 +41,62 @@ "secure" - The cookie should only be sent over secure connections. - (This item was added in PHP 4.0.4.) - "httponly" - The cookie can only be accessed through the HTTP protocol - (This item was added in PHP 5.2.0). + "httponly" - The cookie can only be accessed through the HTTP protocol. + + + + &reftitle.changelog; - See also the configuration directives - session.cookie_lifetime, - session.cookie_path, - session.cookie_domain, - session.cookie_secure, - session.cookie_httponly, and - session_set_cookie_params. + + + + + &Version; + &Description; + + + + + 5.2.0 + + The "httponly" entry was added in the returned array? + + + + 4.0.4 + + The "secure" entry was added in the returned array? + + + + + + + + &reftitle.seealso; + + + session.cookie_lifetime + session.cookie_path + session.cookie_domain + session.cookie_secure + session.cookie_httponly + session.cookie_lifetime + session_set_cookie_params + + + + - + session_id diff --git a/reference/session/functions/session-is-registered.xml b/reference/session/functions/session-is-registered.xml index d0d8a62324..40edcedf4e 100644 --- a/reference/session/functions/session-is-registered.xml +++ b/reference/session/functions/session-is-registered.xml @@ -1,40 +1,67 @@ - - + session_is_registered Find out whether a global variable is registered in a session - - Description + + + &reftitle.description; boolsession_is_registered stringname - session_is_registered returns &true; if there - is a global variable with the name name - registered in the current session. + Finds out whether a global variable is registered in a session. + + + + &reftitle.parameters; + + + + name + + + The variable name. + + + + + + + + + &reftitle.returnvalues; + + session_is_registered returns &true; if there is a + global variable with the name name registered in + the current session, &false; otherwise. + + + + + &reftitle.notes; - 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. + 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. - If you are using - $_SESSION (or $HTTP_SESSION_VARS), - do not use session_register, + If you are using $_SESSION + (or $HTTP_SESSION_VARS), do not use + session_register, session_is_registered and session_unregister. + - + session_module_name Get and/or set the current session module - - Description + + + &reftitle.description; stringsession_module_name stringmodule - session_module_name returns the name of the - current session module. If module is - specified, that module will be used instead. + session_module_name gets the name of the current + session module. + + + &reftitle.parameters; + + + + module + + + If module is specified, that module will be + used instead. + + + + + + + + + &reftitle.returnvalues; + + Returns the name of the current session module. + + + - + session_name Get and/or set the current session name - - Description + + + &reftitle.description; stringsession_name stringname session_name returns the name of the current - session. If name is specified, the name of - the current session is changed to its value. + session. - 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 reset 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 is reset 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 can't consist of digits only, at least one letter must - be present. Otherwise a new session id is generated every time. - - - - <function>session_name</function> examples - + + + + &reftitle.parameters; + + + + name + + + 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). + If name is specified, the name of the current + session is changed to its value. + + + + + The session name can't consist of digits only, at least one letter + must be present. Otherwise a new session id is generated every time. + + + + + + + + + + + &reftitle.returnvalues; + + Returns the name of the current session. + + + + + &reftitle.examples; + + + <function>session_name</function> example + "; ?> ]]> - - - - See also the session.name - configuration directive. + + + + + &reftitle.seealso; + + + + The session.name configuration + directive + + + + + + session_regenerate_id @@ -7,6 +7,7 @@ Update the current session id with a newly generated one + &reftitle.description; @@ -112,6 +113,7 @@ print_r($_SESSION); + - + session_register Register one or more global variables with the current session - - Description + + + &reftitle.description; boolsession_register mixedname @@ -20,52 +20,6 @@ each name, session_register registers the global variable with that name in the current session. - - - If you want your script to work regardless of register_globals, - you need to instead use the - $_SESSION array - as $_SESSION entries are automatically - registered. If your script uses - session_register, it will not work in - environments where the PHP directive - register_globals - is disabled. - - - - ¬e.registerglobals; - - - - This registers a global variable. If you - want to register a session variable from within a function, you - need to make sure to make it global using the global - keyword or the $GLOBALS[] array, or use the - special session arrays as noted below. - - - - - If you are using $_SESSION - (or $HTTP_SESSION_VARS), do not use - session_register, - session_is_registered, and - session_unregister. - - - - This function returns &true; when all of the variables are successfully - registered with the session. - - - If session_start was not called before this function - is called, an implicit call to session_start with no - parameters will be made. $_SESSION does not mimic - this behavior and requires session_start before use. - You can also create a session variable by simply setting the appropriate member of the $_SESSION @@ -88,31 +42,109 @@ $HTTP_SESSION_VARS["spongebob"] = "He's got square pants."; + + If session_start was not called before this function + is called, an implicit call to session_start with no + parameters will be made. $_SESSION does not mimic + this behavior and requires session_start before use. + + + + + &reftitle.parameters; + + + + name + + + A string holding the name of a variable or an array consisting of + variable names or other arrays. + + + + + ... + + + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.notes; + + + If you want your script to work regardless of register_globals, you need to + instead use the $_SESSION array as + $_SESSION entries are automatically registered. If + your script uses session_register, it will not work + in environments where the PHP directive register_globals is disabled. + + + ¬e.registerglobals; + + + This registers a global variable. If you want to + register a session variable from within a function, you need to make sure + to make it global using the global + keyword or the $GLOBALS[] array, or use the special + session arrays as noted below. + + + + + If you are using $_SESSION + (or $HTTP_SESSION_VARS), do not use + session_register, + session_is_registered, and + session_unregister. + + - It is currently impossible to register resource variables in a - session. For example, you cannot create a connection to a - database and store the connection id as a session variable and - expect the connection to still be valid the next time the - session is restored. PHP functions that return a resource are - identified by having a return type of - resource in their function definition. A - list of functions that return resources are available in the - resource types appendix. + It is currently impossible to register resource variables in a session. + For example, you cannot create a connection to a database and store the + connection id as a session variable and expect the connection to still be + valid the next time the session is restored. PHP functions that return a + resource are identified by having a return type of + resource in their function definition. A 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 values to + If $_SESSION (or $HTTP_SESSION_VARS + for PHP 4.0.6 or less) is used, assign values to $_SESSION. For example: $_SESSION['var'] = 'ABC'; + + + + &reftitle.seealso; - See also session_is_registered, - session_unregister, and - $_SESSION. + + session_is_registered + session_unregister + $_SESSION + + - + session_save_path Get and/or set the current session save path - - Description + + + &reftitle.description; stringsession_save_path stringpath 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. - session_save_path needs to be called before - session_start for that purpose. - - - 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. - - - - - See also the session.save_path - configuration directive. + directory used to save session data. + + + &reftitle.parameters; + + + + path + + + Session data path. If specified, the path to which data is saved will + be changed. session_save_path needs to be called + before session_start for that purpose. + + + + + 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. + + + + + + + + + + + &reftitle.returnvalues; + + Returns the path of the current directory used for data storage. + + + + + &reftitle.seealso; + + + + The session.save_path + configuration directive + + + + + - + session_set_cookie_params Set the session cookie parameters - - Description + + + &reftitle.description; voidsession_set_cookie_params intlifetime @@ -22,23 +22,109 @@ call session_set_cookie_params for every request and before session_start is called. - - - The secure parameter was added in PHP - 4.0.4, while the httponly parameter was added in - PHP 5.2.0. - - + + + + &reftitle.parameters; - See also the configuration directives - session.cookie_lifetime, - session.cookie_path, - session.cookie_domain, - session.cookie_secure, - session.cookie_httponly, and - session_get_cookie_params. + + + lifetime + + + + + + + path + + + + + + + domain + + + + + + + secure + + + + + + + httponly + + + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 5.2.0 + + The httponly parameter was added. + + + + 4.0.4 + + The secure parameter was added. + + + + + + + + + + &reftitle.seealso; + + + + session.cookie_lifetime + + + session.cookie_domain + + + session.cookie_secure + + + session.cookie_httponly + + session_get_cookie_params + + + + - + session_set_save_handler Sets user-level session storage functions - - Description + + + &reftitle.description; boolsession_set_save_handler callbackopen @@ -23,44 +23,90 @@ retrieving data associated with a session. This is most useful when a storage method other than those supplied by PHP sessions is preferred. i.e. Storing the session data in a local database. + + + + + &reftitle.parameters; + + + + open + + + + + + + close + + + + + + + read + + + Read function must return string value always to make save handler + work as expected. Return empty string if there is no data to read. + Return values from other handlers are converted to boolean expression. + &true; for success, &false; for failure. + + + + + write + + + + + The "write" handler is not executed until after the output stream is + closed. Thus, output from debugging statements in the "write" + handler will never be seen in the browser. If debugging output is + necessary, it is suggested that the debug output be written to a + file instead. + + + + + + + destroy + + + + + + + gc + + + + + + + + + + + &reftitle.returnvalues; + &return.success; - - - The "write" handler is not executed until after the output - stream is closed. Thus, output from debugging statements in the - "write" handler will never be seen in the browser. If debugging - output is necessary, it is suggested that the debug output be - written to a file instead. - - - - The following example provides file based session - storage similar to the PHP sessions default save handler - files. This example could easily be - extended to cover database storage using your favorite PHP - supported database engine. - - - Read function must return string value always to make save - handler work as expected. Return empty string if there is no data - to read. Return values from other handlers are converted to - boolean expression. &true; for success, &false; for failure. - - - - Write and Close handlers are called after destructing objects since PHP - 5.0.5. Thus destructors can use sessions but session handler can't use - objects. In prior versions, they were called in the opposite order. It - is possible to call session_write_close from the - destructor to solve this chicken and egg problem. - - + + + + &reftitle.examples; - - <function>session_set_save_handler</function> example - + <function>session_set_save_handler</function> example + + The following example provides file based session storage similar to the + PHP sessions default save handler files. This + example could easily be extended to cover database storage using your + favorite PHP supported database engine. + + + + + &reftitle.notes; + + + Write and Close handlers are called after destructing objects since PHP + 5.0.5. Thus destructors can use sessions but session handler can't use + objects. In prior versions, they were called in the opposite order. It + is possible to call session_write_close from the + destructor to solve this chicken and egg problem. + + + + + + &reftitle.seealso; - See also the session.save_handler - configuration directive. + + + The session.save_handler + configuration directive + + + - + session_start Initialize session data - - Description + + + &reftitle.description; boolsession_start - - session_start creates a session or resumes - the current one based on the current session id that's being - passed via a request, such as GET, POST, or a cookie. - - + + session_start creates a session or resumes the + current one based on the current session id that's being passed via a + request, such as GET, POST, or a cookie. + + + If you want to use a named session, you must call + session_name before calling + session_start. + + + session_start will register internal output handler + for URL rewriting when trans-sid is enabled. If a user + uses ob_gzhandler or like with + ob_start, the order of output handler is important + for proper output. For example, user must register + ob_gzhandler before session start. + + + + + &reftitle.returnvalues; + This function always returns &true;. - - - - If you are using cookie-based sessions, you must call - session_start before anything is outputted to the - browser. - - + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 4.3.3 + + As of now, calling session_start while the + session has already been started will result in an error of level + E_NOTICE. Also, the second session start will + simply be ignored. + + + + + + + + + + &reftitle.examples; A session example: <filename>page1.php</filename> @@ -84,40 +125,39 @@ echo '
page 1'; - - If you want to use a named session, you must call - session_name before calling - session_start. - - - session_start will register internal output - handler for URL rewriting when trans-sid is - enabled. If a user uses ob_gzhandler or like - with ob_start, the order of output handler - is important for proper output. For example, user must register - ob_gzhandler before session start. - + + + + &reftitle.notes; - - Use of zlib.output_compression - is recommended rather than ob_gzhandler - + + If you are using cookie-based sessions, you must call + session_start before anything is outputted to the + browser. + - As of PHP 4.3.3, calling session_start while the - session has already been started will result in an error of level - E_NOTICE. Also, the second session start will - simply be ignored. + Use of zlib.output_compression + is recommended rather than ob_gzhandler + + + + &reftitle.seealso; - See also - $_SESSION, - session.auto_start, and - session_id. + + $_SESSION + + The session.auto_start + configuration directive + + session_id + + - + session_unregister Unregister a global variable from the current session - - Description + + + &reftitle.description; boolsession_unregister stringname - session_unregister unregisters - the global variable named name from the - current session. + session_unregister unregisters the global variable + named name from the current session. + + + + &reftitle.parameters; - This function returns &true; when the variable is successfully - unregistered from the session. + + + name + + + The variable name. + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.notes; - If $_SESSION (or - $HTTP_SESSION_VARS for PHP 4.0.6 or less) is - used, use unset to unregister a session - variable. Do not unset $_SESSION - itself as this will disable the special function of the - $_SESSION superglobal. + If $_SESSION (or $HTTP_SESSION_VARS + for PHP 4.0.6 or less) is used, use unset to + unregister a session variable. Do not unset + $_SESSION itself as this will disable the special + function of the $_SESSION superglobal. @@ -41,14 +62,15 @@ - If you are using - $_SESSION (or $HTTP_SESSION_VARS), - do not use session_register, + If you are using $_SESSION (or + $HTTP_SESSION_VARS), do not use + session_register, session_is_registered and session_unregister. + - + session_unset Free all session variables - - Description + + + &reftitle.description; voidsession_unset @@ -16,25 +16,34 @@ The session_unset function frees all session variables currently registered. - - - If $_SESSION (or - $HTTP_SESSION_VARS for PHP 4.0.6 or less) is - used, use unset to unregister a session - variable, i.e. unset ($_SESSION['varname']);. - - + + + + &reftitle.returnvalues; - - - Do NOT unset the whole $_SESSION with - unset($_SESSION) as this will disable the - registering of session variables through the - $_SESSION superglobal. - - + &return.success; + + + &reftitle.notes; + + + If $_SESSION (or $HTTP_SESSION_VARS + for PHP 4.0.6 or less) is used, use unset to + unregister a session variable, i.e. + unset ($_SESSION['varname']);. + + + + + Do NOT unset the whole $_SESSION with + unset($_SESSION) as this will disable the registering + of session variables through the $_SESSION superglobal. + + + + - + session_write_close Write session data and end session - - Description + + + &reftitle.description; voidsession_write_close @@ -16,16 +16,23 @@ End the current session and store session data. - Session data is usually stored after your script terminated - without the need to call session_write_close, but as - session data is locked to prevent concurrent writes only one - script may operate on a session at any time. When using framesets - together with sessions you will experience the frames loading one - by one due to this locking. You can reduce the time needed to - load all the frames by ending the session as soon as all changes - to session variables are done. + Session data is usually stored after your script terminated without the + need to call session_write_close, but as session data + is locked to prevent concurrent writes only one script may operate on a + session at any time. When using framesets together with sessions you will + experience the frames loading one by one due to this locking. You can + reduce the time needed to load all the frames by ending the session as + soon as all changes to session variables are done. + + + &reftitle.returnvalues; + + &return.success; + + +