Session.php

Session.php

<?php

/**
 * ------------------------------------------------------------------------
 * The Session Library Class is a utility wrapper class that assists in the
 * handling of sessions in PHP applications. We achieve this by creating an
 * abstraction between the developer and PHP's native session library. Thus
 * providing a factory that can manufacture, modify and manage session data
 * ------------------------------------------------------------------------
 *
 * @author  Jason Napolitano
 * @license MIT https://mit-license.org
 * @version 1.2.0
 */
class Session implements \Countable, \JsonSerializable, \Stringable
{
    /**
     * Was an existing session already killed by calling session_destroy()?
     *
     * @link https://www.php.net/manual/en/function.session-destroy.php
     *
     * @see  session_destroy()
     *
     * @var bool $destroyed
     */
    protected bool $destroyed = false;

    /**
     * ----------------------------------------------------------
     * The session class constructor will help us build a session 
     * object. This object will interact directly with native PHP
     * SPL's and $_SESSION variables
     *
     * @link  https://www.php.net/manual/en/reserved.variables.session.php
     *
     * @param bool $autoStart Run session_start() when instantiating
     *                        this class?
     *
     * @return void
     */
    public function __construct(protected bool $autoStart = true)
    {
        if ($this->autoStart) session_start();
    }

    // ----------------------------------------------------------

    /**
     * Calls session_write_close() to write session data and ends
     * the session
     *
     * @link https://php.net/manual/en/function.session-write-close.php
     *
     * @return void
     */
    public function close(): void
    {
        session_write_close();
    }

    // ----------------------------------------------------------

    /**
     * Calls session_register_shutdown() which will also register
     * session_write_close() as a shutdown function
     *
     * @link https://php.net/en/functions.session-register-shutdown.php
     */
    public function shutdown(): void
    {
        session_register_shutdown();
    }

    // ----------------------------------------------------------

    /**
     * Destroys all data registered to a session
     *
     * @link https://php.net/manual/en/function.session-destroy.php
     *
     * @return void
     */
    public function destroy(): void
    {
        $this->destroyed = true;
        session_destroy();
    }

    // ----------------------------------------------------------

    /**
     * Removes data from $_SESSION
     *
     * @param string|array $keys The session key(s) to use
     *
     * @return void
     */
    public function remove(string|array $keys): void
    {
        // If self::destroy() hasn't been called ...
        if (!$this->destroyed) {
            // ... and, if $keys is a string ...
            if (is_string($keys)) {
                // ... unset the value of $keys
                unset($_SESSION[$keys]);
            }

            // otherwise, if $keys is an array ...
            if (is_array($keys)) {
                // ... unset each matching value within $keys
                foreach ($keys as $key) {
                    unset($_SESSION[$key]);
                }
            }

            // if all else fails, we'll want to flush the
            // entire $_SESSION array
            $this->flush();
        }
    }

    // ----------------------------------------------------------

    /**
     * Reset $_SESSION completely by setting it to an empty array
     */
    public function flush(): void
    {
        $_SESSION = [];
    }

    // ----------------------------------------------------------

    /**
     * Adds a key => value pair to the $_SESSION array
     *
     * @param string|array          $keys The key to store in $_SESSION
     * @param string|array|int|null $val  The value to assign to $key
     *
     * @return void
     */
    public function set(string|array $keys, string|array|int $val = null): void
    {
        // if $keys is an array, take $keys and add them to $_SESSION,
        // then assign a $value to a $key and stop script execution
        if (is_array($keys) && is_null($val)) {
            foreach ($keys as $key => $value) {
                $_SESSION[$key] = $value;
            }
            return;
        }
        // otherwise, assign $val to $keys
        $_SESSION[(string) $keys] = $val;
    }

    // ----------------------------------------------------------

    /**
     * Get a single value from $_SESSION. If $key is NULL, then a 
     * string representation of $_SESSION will be returned
     *
     * @param string|array $keys
     *
     * @return array|string
     */
    public function get(string|array $keys): array|string
    {
        // if $keys is an array, return each of its values,
        // based on their keys
        if (is_array($keys)) {
            $values = [];
            foreach ($_SESSION as $key => $value) {
                $values[] = $value;
            }
            return $values;
        }
        // if $keys is a string, return its value. otherwise,
        // return an empty array
        return $_SESSION[$keys] ?: [];
    }

    // ----------------------------------------------------------

    /**
     * Returns the total number of values stored in $_SESSION
     *
     * @link   https://www.php.net/manual/en/class.countable.php
     *
     * @return int
     */
    public function count(): int
    {
        // Return the total number of values in $_SESSION
        return count($_SESSION);
    }

    // ----------------------------------------------------------

    /**
     * Returns the value of the $_SESSION array as an implode()'ed
     * string
     *
     * @link   https://www.php.net/manual/en/class.stringable.php
     *
     * @return string
     */
    public function __toString(): string
    {
        // Return $_SESSION as a string, delineated by
        // commas. EG - "value_1, value_2, value_3..."
        return implode(", ", $_SESSION);
    }

    // ----------------------------------------------------------

    /**
     * Returns the $_SESSION array to be serialized by json_encode()
     * or an empty array if $_SESSION isn't set
     *
     * @link   https://www.php.net/manual/en/class.jsonserializable.php
     *
     * @return array
     */
    public function jsonSerialize(): array
    {
        return $_SESSION ?? [];
    }
}