scache_open, scache_popen

Description

scache_open and scache_popen opens connection to scached server and queries for session id provided. If session is found, it's verified and returned to caller. If session is not found, session will be created.

Both functions does a round trip to scached, scache_popen opens connection as persistent and reuses existing connections while scache_open 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 shared 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 :

• scache_connect initiates tcp connection to scached, but doesn't query anything. It merely prepares connection to use values provided. scache_connect operates only on existing and valid sessions and never create a new one.
• scache_open initiates tcp connection and queries server. If session with provided id exists and optional secret matches, scache_open returns that session. If session doesn't exist, it will be created and scache_open acts like scache_reset. If return value is not FALSE, session is verified to be valid unlike with scache_connect where validness is not resolved out until on first actual operation.
• scache_reset also initiates tcp connection and queries server, but it always resets and creates session whether it exists or not, as long as secret match if set on possibly existing session. As like with scache_open non-false result is actually verified.

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

Parameters

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 :

• SCERR_EXIST Session specified already exist but with differing secret. Session won't be opened without providing correct secret.
• SCERR_LIMITS_REACHED Partition has exceeded its memory or node limits and new session cannot be created until memory is freed.
• 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

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

Examples

<?php
$my_session_identifier = $_COOKIE['MySessionIdentifier'];
$session = scache_open($my_session_identifier);
?>

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

<?php
$my_session_identifier = $_COOKIE['MySessionIdentifier'];
$session = new SCache($my_session_identifier);
$session->open();
?>

Although when using class interface you probably spare your keyboard and omit session opening altogether, relying only to SCache-object initialization as it equals to scache_connect in itself.