What is the undocumented SessionIdInterface in PHP 5.5?

Question

In the PHP 5.5.1, there's a reference to a SessionIdInterface. However, it's still undocumented and only thing I could find was the interface definition:

interface SessionIdInterface  {
    public function create_sid ();
}

• Is it safe to rely on this interface?
• Where can I find some sort of documentation regarding this interface?

Answer 1

SessionIdInterface was created as part of php-src pull request 109 and landed in PHP 5.5.1. Some details on it are discussed there.

In short, your SessionHandlerInterface implementation may also implement SessionIdInterface and provide a create_sid method that returns a string. PHP will automatically invoke create_sid instead of using the internal session creation functions as defined in php.ini.

Here's an example script that demonstrates the use.

<?php
class SillySessionHandler implements SessionHandlerInterface, SessionIdInterface {

    static $lol_sessions = [];

    public function open($save_path, $filename) { return true; }
    public function close() { return true; }
    public function destroy($session_id) { return true; }
    public function gc($lifetime) { return true; }
    public function read($session_id) { 
        return array_key_exists($session_id, static::$lol_sessions) ? static::$lol_sessions[$session_id] : null; 
    }
    public function write($session_id, $session_data) { 
        static::$lol_sessions[$session_id] = $session_data;
        echo "Session data: ", $session_data; 
    }

    public function create_sid() {
        $sid = bin2hex(openssl_random_pseudo_bytes(16));
        static::$lol_sessions[$sid] = [];
        return $sid;
    }

}

$handler = new SillySessionHandler;
session_set_save_handler($handler, true);
session_start();

echo "Your session ID is ", session_id(), "<hr>";
$_SESSION['foo'] = 'bar';

Example output:

Your session ID is 2e837e0c5f5ac1b23296d384a9aab2af

---

Session data: foo|s:3:"bar";

Answer 2

According to PHP source code:

/* {{{ SessionIdInterface functions[]
*/
static const zend_function_entry php_session_id_iface_functions[] = {
        PHP_ABSTRACT_ME(SessionIdInterface, create_sid, arginfo_session_class_create_sid)
        { NULL, NULL, NULL }
};
/* }}} */

/* {{{ SessionHandler functions[]
 */
static const zend_function_entry php_session_class_functions[] = {
        PHP_ME(SessionHandler, open, arginfo_session_class_open, ZEND_ACC_PUBLIC)
        PHP_ME(SessionHandler, close, arginfo_session_class_close, ZEND_ACC_PUBLIC)
        PHP_ME(SessionHandler, read, arginfo_session_class_read, ZEND_ACC_PUBLIC)
        PHP_ME(SessionHandler, write, arginfo_session_class_write, ZEND_ACC_PUBLIC)
        PHP_ME(SessionHandler, destroy, arginfo_session_class_destroy, ZEND_ACC_PUBLIC)
        PHP_ME(SessionHandler, gc, arginfo_session_class_gc, ZEND_ACC_PUBLIC)
        PHP_ME(SessionHandler, create_sid, arginfo_session_class_create_sid, ZEND_ACC_PUBLIC)
        { NULL, NULL, NULL }
    };

There is no any other methods in SessionIdInterface and create_sid in this interface is the same with SessionHandler