<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Basic usage</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="session.examples.html">Examples</a></div>
<div class="next" style="text-align: right; float: right;"><a href="session.idpassing.html">Passing the Session ID</a></div>
<div class="up"><a href="session.examples.html">Examples</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><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"><var class="varname"><a href="reserved.variables.session.html" class="classname">$_SESSION</a></var></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"><var class="varname"><a href="reserved.variables.session.html" class="classname">$_SESSION</a></var></var> superglobal, serialize it, and send it
for storage using the session save handler.
</p>
<p class="para">
By default, PHP uses the internal <em><code class="parameter">files</code></em> save handler which
is set by <a href="session.configuration.html#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.html#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.html" class="function">session_start()</a></span> function.
If the <a href="session.configuration.html#ini.session.auto-start" class="link">session.auto_start</a> directive is set
to <em><code class="parameter">1</code></em>, 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.html" class="function">session_write_close()</a></span> function.
</p>
<p class="para">
<div class="example" id="example-4761">
<p><strong>Example #1
Registering a variable with <var class="varname"><var class="varname"><a href="reserved.variables.session.html" class="classname">$_SESSION</a></var></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-4762">
<p><strong>Example #2
Unregistering a variable with <var class="varname"><var class="varname"><a href="reserved.variables.session.html" class="classname">$_SESSION</a></var></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"><var class="varname"><a href="reserved.variables.session.html" class="classname">$_SESSION</a></var></var> with
<em>unset($_SESSION)</em> as this will disable the
registering of session variables through the
<var class="varname"><var class="varname"><a href="reserved.variables.session.html" class="classname">$_SESSION</a></var></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>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
register_globals will overwrite variables in the global scope whose names are shared with session variables. Please see <a href="security.globals.html" class="link">Using Register Globals</a> for details.
</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.html" class="function">session_start()</a></span> or implicitly via
<a href="session.configuration.html#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.html" 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.html" 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><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="session.examples.html">Examples</a></div>
<div class="next" style="text-align: right; float: right;"><a href="session.idpassing.html">Passing the Session ID</a></div>
<div class="up"><a href="session.examples.html">Examples</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
