Add php session interfaces

src/session/SessionHandlerInterface.php

@@ -0,0 +1,155 @@
+<?php
+/**
+ * This file is part of Adapterman.
+ *
+ * Licensed under The MIT License
+ * For full copyright and license information, please see the LICENSE.txt
+ * Redistributions of files must retain the above copyright notice.
+ *
+ * @author    Joan Miquel<https://github.com/joanhey>
+ * @copyright Joan Miquel<https://github.com/joanhey>
+ * @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;
+
+}

src/session/SessionUpdateTimestampHandlerInterface.php

@@ -0,0 +1,67 @@
+<?php
+/**
+ * This file is part of Adapterman.
+ *
+ * Licensed under The MIT License
+ * For full copyright and license information, please see the LICENSE.txt
+ * Redistributions of files must retain the above copyright notice.
+ *
+ * @author    Joan Miquel<https://github.com/joanhey>
+ * @copyright Joan Miquel<https://github.com/joanhey>
+ * @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;
+}