<!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>Update the current session id with a newly generated one</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.session-name.html">session_name</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.session-register-shutdown.html">session_register_shutdown</a></div>
<div class="up"><a href="ref.session.html">Session Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.session-regenerate-id" class="refentry">
<div class="refnamediv">
<h1 class="refname">session_regenerate_id</h1>
<p class="verinfo">(PHP 4 >= 4.3.2, PHP 5, PHP 7)</p><p class="refpurpose"><span class="refname">session_regenerate_id</span> — <span class="dc-title">
Update the current session id with a newly generated one
</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.session-regenerate-id-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">bool</span> <span class="methodname"><strong>session_regenerate_id</strong></span>
([ <span class="methodparam"><span class="type">bool</span> <code class="parameter">$delete_old_session</code><span class="initializer"> = <strong><code>FALSE</code></strong></span></span>
] )</div>
<p class="para rdfs-comment">
<span class="function"><strong>session_regenerate_id()</strong></span> will replace the current
session id with a new one, and keep the current session information.
</p>
<p class="para">
When <a href="session.configuration.html#ini.session.use-trans-sid" class="link">session.use_trans_sid</a>
is enabled, output must be started after <span class="function"><strong>session_regenerate_id()</strong></span>
call. Otherwise, old session ID is used.
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
Current session_regenerate_id does not handle unstable network well.
e.g. Mobile and WiFi network. Therefore, you may experience lost
session by calling session_regenerate_id.
</p>
<p class="para">
You should not destroy old session data immediately, but should use
destroy time-stamp and control access to old session ID. Otherwise,
concurrent access to page may result in inconsistent state, or you
may have lost session, or it may cause client(browser) side race
condition and may create many session ID needlessly. Immediate
session data deletion disables session hijack attack detection
and prevention also.
</p>
</div>
</div>
<div class="refsect1 parameters" id="refsect1-function.session-regenerate-id-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<code class="parameter">delete_old_session</code></dt>
<dd>
<p class="para">
Whether to delete the old associated session file or not.
You should not delete old session if you need to avoid
races caused by deletion or detect/avoid session hijack
attacks.
</p>
</dd>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.session-regenerate-id-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns <strong><code>TRUE</code></strong> on success or <strong><code>FALSE</code></strong> on failure.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.session-regenerate-id-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>7.0.0</td>
<td>
<span class="function"><strong>session_regenerate_id()</strong></span> saves old session data
before closing.
</td>
</tr>
<tr>
<td>5.1.0</td>
<td>
Added the <code class="parameter">delete_old_session</code> parameter.
</td>
</tr>
<tr>
<td>4.3.3</td>
<td>
Since then, if session cookies are enabled, use of
<span class="function"><strong>session_regenerate_id()</strong></span> will also submit a new
session cookie with the new session id.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.session-regenerate-id-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-5963">
<p><strong>Example #1 A <span class="function"><strong>session_regenerate_id()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">// NOTE: This code is not fully working code, but an example!<br /><br /></span><span style="color: #0000BB">session_start</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000">// Check destroyed time-stamp<br /></span><span style="color: #007700">if (isset(</span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'destroyed'</span><span style="color: #007700">])<br /> && </span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'destroyed'</span><span style="color: #007700">] < </span><span style="color: #0000BB">time</span><span style="color: #007700">() - </span><span style="color: #0000BB">300</span><span style="color: #007700">) {<br /> </span><span style="color: #FF8000">// Should not happen usually. This could be attack or due to unstable network.<br /> // Remove all authentication status of this users session.<br /> </span><span style="color: #0000BB">remove_all_authentication_flag_from_active_sessions</span><span style="color: #007700">(</span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'userid'</span><span style="color: #007700">]);<br /> throw(new </span><span style="color: #0000BB">DestroyedSessionAccessException</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #0000BB">$old_sessionid </span><span style="color: #007700">= </span><span style="color: #0000BB">session_id</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000">// Set destroyed timestamp<br /></span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'destroyed'</span><span style="color: #007700">] = </span><span style="color: #0000BB">time</span><span style="color: #007700">(); </span><span style="color: #FF8000">// Since PHP 7.0.0 and up, session_regenerate_id() saves old session data<br /><br />// Simply calling session_regenerate_id() may result in lost session, etc.<br />// See next example.<br /></span><span style="color: #0000BB">session_regenerate_id</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000">// New session does not need destroyed timestamp<br /></span><span style="color: #007700">unset(</span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'destroyed'</span><span style="color: #007700">]);<br /><br /></span><span style="color: #0000BB">$new_sessionid </span><span style="color: #007700">= </span><span style="color: #0000BB">session_id</span><span style="color: #007700">();<br /><br />echo </span><span style="color: #DD0000">"Old Session: </span><span style="color: #0000BB">$old_sessionid</span><span style="color: #DD0000"><br />"</span><span style="color: #007700">;<br />echo </span><span style="color: #DD0000">"New Session: </span><span style="color: #0000BB">$new_sessionid</span><span style="color: #DD0000"><br />"</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
Current session module does not handle unstable network well. You should
manage session ID to avoid lost session by session_regenerate_id.
</p>
<p class="para">
<div class="example" id="example-5964">
<p><strong>Example #2 Avoiding lost session by <span class="function"><strong>session_regenerate_id()</strong></span></strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">// NOTE: This code is not fully working code, but an example!<br />// my_session_start() and my_session_regenerate_id() avoid lost sessions by<br />// unstable network. In addition, this code may prevent exploiting stolen<br />// session by attackers.<br /><br /></span><span style="color: #007700">function </span><span style="color: #0000BB">my_session_start</span><span style="color: #007700">() {<br /> </span><span style="color: #0000BB">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">'destroyed'</span><span style="color: #007700">])) {<br /> if (</span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'destroyed'</span><span style="color: #007700">] < </span><span style="color: #0000BB">time</span><span style="color: #007700">()-</span><span style="color: #0000BB">300</span><span style="color: #007700">) {<br /> </span><span style="color: #FF8000">// Should not happen usually. This could be attack or due to unstable network.<br /> // Remove all authentication status of this users session.<br /> </span><span style="color: #0000BB">remove_all_authentication_flag_from_active_sessions</span><span style="color: #007700">(</span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'userid'</span><span style="color: #007700">]);<br /> throw(new </span><span style="color: #0000BB">DestroyedSessionAccessException</span><span style="color: #007700">);<br /> }<br /> if (isset(</span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'new_session_id'</span><span style="color: #007700">])) {<br /> </span><span style="color: #FF8000">// Not fully expired yet. Could be lost cookie by unstable network.<br /> // Try again to set proper session ID cookie.<br /> // NOTE: Do not try to set session ID again if you would like to remove<br /> // authentication flag.<br /> </span><span style="color: #0000BB">session_commit</span><span style="color: #007700">();<br /> </span><span style="color: #0000BB">session_id</span><span style="color: #007700">(</span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'new_session_id'</span><span style="color: #007700">]);<br /> </span><span style="color: #FF8000">// New session ID should exist<br /> </span><span style="color: #0000BB">session_start</span><span style="color: #007700">();<br /> return;<br /> }<br /> }<br />}<br /><br />function </span><span style="color: #0000BB">my_session_regenerate_id</span><span style="color: #007700">() {<br /> </span><span style="color: #FF8000">// New session ID is required to set proper session ID<br /> // when session ID is not set due to unstable network.<br /> </span><span style="color: #0000BB">$new_session_id </span><span style="color: #007700">= </span><span style="color: #0000BB">session_create_id</span><span style="color: #007700">();<br /> </span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'new_session_id'</span><span style="color: #007700">] = </span><span style="color: #0000BB">$new_session_id</span><span style="color: #007700">;<br /> <br /> </span><span style="color: #FF8000">// Set destroy timestamp<br /> </span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'destroyed'</span><span style="color: #007700">] = </span><span style="color: #0000BB">time</span><span style="color: #007700">();<br /> <br /> </span><span style="color: #FF8000">// Write and close current session;<br /> </span><span style="color: #0000BB">session_commit</span><span style="color: #007700">();<br /><br /> </span><span style="color: #FF8000">// Start session with new session ID<br /> </span><span style="color: #0000BB">session_id</span><span style="color: #007700">(</span><span style="color: #0000BB">$new_session_id</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">ini_set</span><span style="color: #007700">(</span><span style="color: #DD0000">'session.use_strict_mode'</span><span style="color: #007700">, </span><span style="color: #0000BB">0</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">session_start</span><span style="color: #007700">();<br /> </span><span style="color: #0000BB">ini_set</span><span style="color: #007700">(</span><span style="color: #DD0000">'session.use_strict_mode'</span><span style="color: #007700">, </span><span style="color: #0000BB">1</span><span style="color: #007700">);<br /> <br /> </span><span style="color: #FF8000">// New session does not need them<br /> </span><span style="color: #007700">unset(</span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'destroyed'</span><span style="color: #007700">]);<br /> unset(</span><span style="color: #0000BB">$_SESSION</span><span style="color: #007700">[</span><span style="color: #DD0000">'new_session_id'</span><span style="color: #007700">]);<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-function.session-regenerate-id-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"><span class="function"><a href="function.session-id.html" class="function" rel="rdfs-seeAlso">session_id()</a> - Get and/or set the current session id</span></li>
<li class="member"><span class="function"><a href="function.session-create-id.html" class="function" rel="rdfs-seeAlso">session_create_id()</a> - Create new session id</span></li>
<li class="member"><span class="function"><a href="function.session-start.html" class="function" rel="rdfs-seeAlso">session_start()</a> - Start new or resume existing session</span></li>
<li class="member"><span class="function"><a href="function.session-destroy.html" class="function" rel="rdfs-seeAlso">session_destroy()</a> - Destroys all data registered to a session</span></li>
<li class="member"><span class="function"><a href="function.session-reset.html" class="function" rel="rdfs-seeAlso">session_reset()</a> - Re-initialize session array with original values</span></li>
<li class="member"><span class="function"><a href="function.session-name.html" class="function" rel="rdfs-seeAlso">session_name()</a> - Get and/or set the current session name</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.session-name.html">session_name</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.session-register-shutdown.html">session_register_shutdown</a></div>
<div class="up"><a href="ref.session.html">Session Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
