<?php include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc'; $TOC = array(); $TOC_DEPRECATED = array(); $PARENTS = array(); include_once dirname(__FILE__) ."/toc/session.examples.inc"; $setup = array ( 'home' => array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'en', ), 'this' => array ( 0 => 'session.examples.basic.php', 1 => 'Basic usage', ), 'up' => array ( 0 => 'session.examples.php', 1 => 'Examples', ), 'prev' => array ( 0 => 'session.examples.php', 1 => 'Examples', ), 'next' => array ( 0 => 'session.idpassing.php', 1 => 'Passing the Session ID', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'en', 'path' => 'reference/session/examples.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?> <div id="session.examples.basic" class="section"> <h2 class="title">Basic usage</h2> <p class="para"> Sessions are a simple way to store data for individual users against a unique session ID. This can be used to persist state information between page requests. Session IDs are normally sent to the browser via session cookies and the ID is used to retrieve existing session data. The absence of an ID or session cookie lets PHP know to create a new session, and generate a new session ID. </p> <p class="para"> Sessions follow a simple workflow. When a session is started, PHP will either retrieve an existing session using the ID passed (usually from a session cookie) or if no session is passed it will create a new session. PHP will populate the <var class="varname"><a href="reserved.variables.session.php" class="classname">$_SESSION</a></var> superglobal with any session data after the session has started. When PHP shuts down, it will automatically take the contents of the <var class="varname"><a href="reserved.variables.session.php" class="classname">$_SESSION</a></var> superglobal, serialize it, and send it for storage using the session save handler. </p> <p class="para"> By default, PHP uses the internal <code class="parameter">files</code> save handler which is set by <a href="session.configuration.php#ini.session.save-handler" class="link">session.save_handler</a>. This saves session data on the server at the location specified by the <a href="session.configuration.php#ini.session.save-path" class="link">session.save_path</a> configuration directive. </p> <p class="para"> Sessions can be started manually using the <span class="function"><a href="function.session-start.php" class="function">session_start()</a></span> function. If the <a href="session.configuration.php#ini.session.auto-start" class="link">session.auto_start</a> directive is set to <code class="parameter">1</code>, a session will automatically start on request startup. </p> <p class="para"> Sessions normally shutdown automatically when PHP is finished executing a script, but can be manually shutdown using the <span class="function"><a href="function.session-write-close.php" class="function">session_write_close()</a></span> function. </p> <p class="para"> <div class="example" id="example-4967"> <p><strong>Example #1 Registering a variable with <var class="varname"><a href="reserved.variables.session.php" class="classname">$_SESSION</a></var>. </strong></p> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"><span style="color: #0000BB"><?php<br />session_start</span><span style="color: #007700">();<br />if (!isset(</span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'count'</span><span style="color: #007700">])) {<br /> </span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'count'</span><span style="color: #007700">] = </span><span style="color: #0000BB">0</span><span style="color: #007700">;<br />} else {<br /> </span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'count'</span><span style="color: #007700">]++;<br />}<br /></span><span style="color: #0000BB">?></span></span></code></div> </div> </div> <div class="example" id="example-4968"> <p><strong>Example #2 Unregistering a variable with <var class="varname"><a href="reserved.variables.session.php" class="classname">$_SESSION</a></var>. </strong></p> <div class="example-contents"> <div class="phpcode"><code><span style="color: #000000"><span style="color: #0000BB"><?php<br />session_start</span><span style="color: #007700">();<br />unset(</span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'count'</span><span style="color: #007700">]);<br /></span><span style="color: #0000BB">?></span></span></code></div> </div> </div> </p> <p class="para"> <div class="caution"><strong class="caution">Caution</strong> <p class="para"> Do NOT unset the whole <var class="varname"><a href="reserved.variables.session.php" class="classname">$_SESSION</a></var> with <code class="literal">unset($_SESSION)</code> as this will disable the registering of session variables through the <var class="varname"><a href="reserved.variables.session.php" class="classname">$_SESSION</a></var> superglobal. </p> </div> </p> <div class="warning"><strong class="warning">Warning</strong> <p class="para"> You can't use references in session variables as there is no feasible way to restore a reference to another variable. </p> </div> <blockquote class="note"><p><strong class="note">Note</strong>: <p class="para"> File based sessions (the default in PHP) lock the session file once a session is opened via <span class="function"><a href="function.session-start.php" class="function">session_start()</a></span> or implicitly via <a href="session.configuration.php#ini.session.auto-start" class="link">session.auto_start</a>. Once locked, no other script can access the same session file until it has been closed by the first script terminating or calling <span class="function"><a href="function.session-write-close.php" class="function">session_write_close()</a></span>. </p> <p class="para"> This is most likely to be an issue on Web sites that use AJAX heavily and have multiple concurrent requests. The easiest way to deal with it is to call <span class="function"><a href="function.session-write-close.php" class="function">session_write_close()</a></span> as soon as any required changes to the session have been made, preferably early in the script. Alternatively, a different session backend that does support concurrency could be used. </p> </p></blockquote> </div><?php manual_footer($setup); ?>