scache_reset, scache_preset


resource scache_reset(string id [, string host [, string secret [, long expire [, long port [, long flags]]]]])
resource scache_preset(string id [, string host [, string secret [, long expire [, long port [, long flags]]]]])
bool $SCacheConnection->reset()

scache_reset and scache_preset opens connection to scached server and creates new or resets already existing session id, provided that secret matches in case of existing session has one set.

Both functions do a round trip to scached, scache_preset opens connection as persistent and reuses existing connections while scache_reset doesn't.

id is in most cases the cookie or whatever you send to browsers to distinguish them between. secret is meant to be web application specific check to be matched on a case where same scached is used between not so trustworthy apps and servers. If secret is set it must match on further opens. On a simple local-only scacheds secret has no sensible uses.

scache_open, scache_reset and scache_connect are all for opening session handle. Differencies between them are :

Class interface does not support parameters on reset method. All parameters are given in SCache object's constructor.


Unique session identifier that distinguishes sessions from each other on scached. Basically this is the cookie or whatever you use to distinguish your users. Scache treats this as null terminated c-string so it is not binary safe.
Host name of server to connect. If host name begins with slash (/) it is treated as a unix socket path to local filesystem. If hostname is null, system default path or ini-overrided value is used.
Secret to match on already existing session or to be set to a new session. Scache treats this as null terminated c-string meaning it is not binary safe.
Maximum idle time in seconds of created session between queries. If expire time is exceeded, session is invalidated in complete. If expire is false, either system default or it's ini overrided value is used.
TCP-port of host to connect. If port is false, either system default or it's ini overriden value is used.
Something not to be used.

Return values

Class interface returns either TRUE on success or FALSE on failure, while procedural interface returns session resource on success or FALSE on failure. All other functions operate on this returned resource as their first parameter.

In case of failure, error codes resolvable by scache_lasterr is one of below :


On a normal life-cycle you should separate user login from other activities and create session on that login phase with either scache_open or scache_reset. With scache_open you can detect already existing session and choose to select another session identifier while scache_reset always resets session leaving undetectable possibility that there is another user using same identifier. It's a case how much you trust you id's uniqueness.

On the later page loads you should acquire session resource with scache_connect to avoid unnecessary backend queries. Good practice is to separate session initialization from it's further use.

Finally you log out the user by destroying session with scache_drop


$new_session_identifier = uniqid();
$session = scache_reset($new_session_identifier, 'myhost.tcp.ip', 'SuperSeCREt');

By class interface, equal session initialization must be done in two stages :

$new_session_identifier = uniqid();
$session = new SCache($new_session_identifier, 'myhost.tcp.ip', 
                      false /* default-expire */,
		      true /* persistent */, 'SuperSeCREt');