From bef51ddc027918e8b0b7d86029cba0f220af8cd1 Mon Sep 17 00:00:00 2001 From: Joanhey Date: Sun, 10 Sep 2023 02:39:21 +0200 Subject: [PATCH] Add php session interfaces --- src/session/SessionHandlerInterface.php | 155 ++++++++++++++++++ ...SessionUpdateTimestampHandlerInterface.php | 67 ++++++++ 2 files changed, 222 insertions(+) create mode 100644 src/session/SessionHandlerInterface.php create mode 100644 src/session/SessionUpdateTimestampHandlerInterface.php diff --git a/src/session/SessionHandlerInterface.php b/src/session/SessionHandlerInterface.php new file mode 100644 index 0000000..c7541a7 --- /dev/null +++ b/src/session/SessionHandlerInterface.php @@ -0,0 +1,155 @@ + + * @copyright Joan Miquel + * @link https://github.com/joanhey/AdapterMan + * @license http://www.opensource.org/licenses/mit-license.php MIT License + */ + +/** + * SessionHandlerInterface + * --- + * + * SessionHandlerInterface is an interface which defines + * a prototype for creating a custom session handler. + * + * In order to pass a custom session handler to session_set_save_handler() + * using its OOP invocation, the class must implement this interface. + * + * @link https://php.net/manual/en/class.sessionhandlerinterface.php + * @since 5.4 + */ +interface SessionHandlerInterface +{ + /** + * ### Close the session + * + * Closes the current session. This function is automatically executed + * when closing the session, or explicitly via *session_write_close()*. + * + * @link http://php.net/manual/en/sessionhandlerinterface.close.php + * + * @return bool The return value (usually **true** on success, **false** on failure). + * Note this value is returned internally to PHP for processing. + * + * @since 5.4.0 + */ + public function close(): bool; + + /** + * ### Destroy a session + * + * Called by *session_regenerate_id()* (with $destroy = true), *session_destroy()* + * and when *session_decode()* fails. + * @link http://php.net/manual/en/sessionhandlerinterface.destroy.php + * + * @param string $id The session ID being destroyed. + * @return bool The return value (usually **true** on success, **false** on failure). + * Note this value is returned internally to PHP for processing. + * + * @since 5.4.0 + */ + public function destroy(string $id): bool; + + /** + * ### Cleanup old sessions + * + * Cleans up expired sessions. Called by *session_start()*, + * based on *session.gc_divisor*, *session.gc_probability* + * and *session.gc_maxlifetime* settings. + * @link http://php.net/manual/en/sessionhandlerinterface.gc.php + * + * @param int $max_lifetime Sessions that have not updated + * for the last **maxLifetime** seconds will be removed. + * + * @return int|false Returns the number of deleted sessions on success, or **false** on failure. + * Note this value is returned internally to PHP for processing. + * + * @since 5.4.0 + */ + public function gc(int $max_lifetime): int|false; + + /** + * ### Initialize session + * + * Re-initialize existing session, or creates a new one. + * Called when a session starts or when session_start() is invoked. + * @link http://php.net/manual/en/sessionhandlerinterface.open.php + * + * @param string $path The path where to store/retrieve the session. + * @param string $name The session name. + * + * @return bool The return value (usually **true** on success, **false** on failure). + * Note this value is returned internally to PHP for processing. + * + * @since 5.4.0 + */ + public function open(string $path, string $name): bool; + + + /** + * ### Read session data + * + * Reads the session data from the session storage, and returns the results. + * Called right after the session starts or when *session_start()* is called. + * Please note that before this method is called *SessionHandlerInterface::open()* is invoked. + * + * This method is called by PHP itself when the session is started. + * This method should retrieve the session data from storage by the session ID provided. + * The string returned by this method must be in the same serialized format as when + * originally passed to the *SessionHandlerInterface::write()* If the record was not found, return **false**. + * + * The data returned by this method will be decoded internally by PHP using the unserialization method + * specified in *session.serialize_handler*. + * The resulting data will be used to populate the *$_SESSION* superglobal. + * + * Note that the serialization scheme is not the same as *unserialize()* + * and can be accessed by *session_decode()*. + * @link http://php.net/manual/en/sessionhandlerinterface.read.php + * @param string $id The session id to read data for. + * + * @return string|false Returns an encoded string of the read data. + * If nothing was read, it must return **false**. + * Note this value is returned internally to PHP for processing. + * + * @since 5.4.0 + */ + public function read(string $id): string|false; + + /** + * ### Write session data + * + * Writes the session data to the session storage. Called by *session_write_close()*, + * when *session_register_shutdown()* fails, or during a normal shutdown. + * Note: *SessionHandlerInterface::close()* is called immediately after this function. + * + * PHP will call this method when the session is ready to be saved and closed. + * It encodes the session data from the **$_SESSION** superglobal to a serialized string + * and passes this along with the session ID to this method for storage. + * The serialization method used is specified in the *session.serialize_handler* setting. + * + * Note this method is normally called by PHP after the output buffers have been closed + * unless explicitly called by *session_write_close()* + * @link http://php.net/manual/en/sessionhandlerinterface.write.php + * + * @param string $id The session id. + * @param string $data The encoded session data. This data is the + * result of the PHP internally encoding + * the **$_SESSION** superglobal to a serialized + * string and passing it as this parameter. + * Please note sessions use an alternative serialization method. + * + * @return bool The return value (usually **true** on success, **false** on failure). + * Note this value is returned internally to PHP for processing. + * + * @since 5.4.0 + */ + public function write(string $id, string $data): bool; + +} diff --git a/src/session/SessionUpdateTimestampHandlerInterface.php b/src/session/SessionUpdateTimestampHandlerInterface.php new file mode 100644 index 0000000..e389e12 --- /dev/null +++ b/src/session/SessionUpdateTimestampHandlerInterface.php @@ -0,0 +1,67 @@ + + * @copyright Joan Miquel + * @link https://github.com/joanhey/AdapterMan + * @license http://www.opensource.org/licenses/mit-license.php MIT License + */ + +/** + * SessionUpdateTimestampHandlerInterface + * --- + * + * **SessionUpdateTimestampHandlerInterface** is an interface which defines optional + * methods for creating a custom session handler. + * In order to pass a custom session handler to *session_set_save_handler()* using + * its OOP invocation, the class can implement this interface. + * + * Note that the callback methods of classes implementing this interface are designed + * to be called internally by PHP and are not meant to be called from user-space code. + * + * @since 7.0 + * @link https://www.php.net/manual/en/class.sessionupdatetimestamphandlerinterface.php + */ + +interface SessionUpdateTimestampHandlerInterface +{ + + /** + * ### Update timestamp of a session + * + * Updates the last modification timestamp of the session. + * This function is automatically executed when a session is updated. + * + * @link https://www.php.net/manual/sessionupdatetimestamphandlerinterface.updatetimestamp.php + * + * @param string $id The session id + * @param string $data + * + * @return bool Returns **true** if the timestamp was updated, **false** otherwise. + * Note that this value is returned internally to PHP for processing. + * + */ + public function updateTimestamp(string $id, string $data): bool; + + /** + * ### Validate session id + * + * Validates a given session ID. A session ID is valid, if a session with + * that ID already exists. This function is automatically executed when a session + * is to be started, a session ID is supplied and *session.use_strict_mode* is enabled. + * + * @link https://www.php.net/manual/sessionupdatetimestamphandlerinterface.validateid + * + * @param string $id The session id + * + * @return bool Returns **true** for valid ID, **false** otherwise. + * Note that this value is returned internally to PHP for processing. + * + */ + public function validateId(string $id): bool; +}