scache_rename
Description
scache_rename renames session to new identifier and modifies current session to use new identifier. On further connection attempts, session must be opened with new identifier and previous identifier is permanently gone.
Parameters
Return values
TRUE on success, FALSE on failure.
In case of failure, error codes resolvable by scache_lasterr is one of below :
- SCERR_NO_SESSION Connected session does not exist or has been expired. Connection is not valid any more.
- SCERR_EXIST Session id newid already exists and will not be overwritten.
- SCERR_NOT_CONNECTED Connection to backend is broken and cannot be reconnected.
- SCERR_PROTOCOL Internal protocol error has occurred when communicating to backend. This indicates something is severely broken.
Notes I
Basically scache_rename makes possible to provide some extra security by occasionally changing clients session cookie. Unfortunately from server application's side this is not as easy than it sounds because of concurrency where you might have some active request already sent by browser (with old session cookie) on the wire or pending for its processor slice while you independently rename session on another process (or thread).
This generates race condition that needs to be addressed by some two-cookie system, where one with shortened expire is for what it is now and second for what it will soon be. Server application needs to be designed so that it's capable from fallbacking from expired and nonexisting id to new one.
As a conclusion; if you decide to rename you session on fly you really need to know what are you doing and how are you going to do it. scache_rename does not rename you web applications session, it just changes its identifier on scached backend. Your application needs to do the session renaming and from quality and performance point of view - without locks.
Notes II
If rename fails, both sessions are left to unknown state. It might be possible to handle it with testing both whether either still exists, but considering its improbability, best thing to do in rename failure is to panic the application. The most probable and almost only error is to rename it to something that already exists. Don't do that, use unique identifiers.
If session is renamed, its session index slot used by scache_connect_fast will remain same.
Examples
<?php
/* we do have a session */
$session = scache_reset('TheOriginalIdentifier');
scache_put($session, 'testvalue', 'Valid');
if (session_rename($session, 'TheNewIndentifier')) {
/* old resource handle is still valid... */
if (scache_get($session, 'testvalue') != 'Valid')
die('Can't happen');
/* but in further page loads, renamed session must be opened
with its new identifier */
$newsession = session_open('TheNewIdentifier');
if (scache_get($session, 'testvalue') != 'Valid')
die('Can't happen either');
}
?>