Session.php

<?php

/*
 * This file is part of the Koded package.
 *
 * (c) Mihail Binev <mihail@kodeart.com>
 *
 * Please view the LICENSE distributed with this source code
 * for the full copyright and license information.
 *
 */

namespace Koded\Session;

use Koded\Exceptions\KodedException;
use Koded\Stdlib\{Immutable, UUID};
use Koded\Stdlib\Interfaces\Data;


interface Session
{

 /**
 * The timestamp when session started.
 */
 const STAMP = '_stamp';

 /**
 * The web browser signature.
 */
 const AGENT = '_agent';

 /**
 * Session token (useful for CSRF)
 */
 const TOKEN = '_token';

 /**
 * Flash data
 */
 const FLASH = '_flash';

 public function id(): string;

 public function get(string $name, $default = null);

 public function set(string $name, $value): Session;

 public function pull(string $name, $default = null);

 public function add(string $name, $value): void;

 public function import(array $data): Session;

 public function remove(string $name): void;

 public function all(): array;

 public function toArray(): array;

 public function toData(): Data;

 public function clear(): bool;

 /**
 * Destroys all of the data associated with the current session,
 * by closing the session and re-opening it again.
 * Also the object state is cleaned and internal metadata is recreated.
 *
 * @return bool TRUE on success, FALSE otherwise
 */
 public function destroy(): bool;

 /**
 * Update the current session id with a newly generated one
 * and session token with a new v4 UUID.
 *
 * @param bool $deleteOldSession [optional] Whether to delete the old associated session or not
 *
 * @return bool TRUE on success, FALSE otherwise
 * @link https://php.net/manual/en/function.session-regenerate-id.php
 */
 public function regenerate(bool $deleteOldSession = false): bool;

 /**
 * Exchange the session data for another one.
 *
 * @param array $data The new array or object to exchange with the current session data
 *
 * @return array The old session data
 */
 public function replace(array $data): array;

 public function has(string $name): bool;

 public function accessed(): bool;

 public function modified(): bool;

 public function token(): string;

 public function starttime(): float;

 public function agent(): string;

 public function isEmpty(): bool;

 public function count(): int;

 public function flash(string $name, $value = null);
}

/**
 * Class PhpSession
 */
final class PhpSession implements Session
{
 /**
 * @var bool
 */
 private $accessed = false;

 /**
 * @var bool
 */
 private $modified = false;

 /**
 * @var float
 */
 private $stamp = 0;

 /**
 * @var string
 */
 private $agent = '';

 /**
 * @var string
 */
 private $token = '';

 public function __construct()
 {
 // @codeCoverageIgnoreStart
 if (false === isset($_SESSION)) {
 global $_SESSION;
 $_SESSION = [];
 }
 // @codeCoverageIgnoreEnd

 $this->loadMetadata();
 $this->accessed = false;
 $this->modified = false;
 session($this);
 }

 public function get(string $name, $default = null)
 {
 $this->accessed = true;

 return $_SESSION[$name] ?? $default;
 }

 public function __get(string $name)
 {
 return $this->get($name);
 }

 public function all(): array
 {
 $this->accessed = true;

 return (array)$_SESSION + $this->getMetadata();
 }

 public function __set(string $name, $value)
 {
 return $this->set($name, $value);
 }

 public function toArray(): array
 {
 $this->accessed = true;

 return $_SESSION ?? [];
 }

 public function toData(): Data
 {
 $this->accessed = true;

 return new Immutable($_SESSION ?? []);
 }

 /*
 *
 * (mutator methods)
 *
 */

 public function set(string $name, $value): Session
 {
 $this->modified = true;
 $_SESSION[$name] = $value;

 return $this;
 }

 public function add(string $name, $value): void
 {
 $this->has($name) || $this->set($name, $value);
 }

 public function import(array $data): Session
 {
 $data = array_filter($data, 'is_string', ARRAY_FILTER_USE_KEY);
 $_SESSION = array_replace($_SESSION, $data);

 $this->modified = true;

 return $this;
 }

 public function pull(string $name, $default = null)
 {
 $value = $_SESSION[$name] ?? $default;
 unset($_SESSION[$name]);

 return $value;
 }

 public function remove(string $name): void
 {
 $this->modified = true;
 unset($_SESSION[$name]);
 }

 public function flash(string $name, $value = null)
 {
 if (null === $value) {
 $value = $this->pull(self::FLASH);
 } else {
 $_SESSION[self::FLASH][$name] = $value;
 }

 $this->modified = true;

 return $value;
 }

 public function has(string $name): bool
 {
 return array_key_exists($name, $_SESSION ?? []);
 }

 /*
 *
 * (support methods)
 *
 */

 public function replace(array $data): array
 {
 $oldSession = $_SESSION;
 $_SESSION = [];
 $this->import($data);

 return $oldSession;
 }

 public function clear(): bool
 {
 $_SESSION = [];
 $this->modified = true;

 return empty($_SESSION);
 }

 public function regenerate(bool $deleteOldSession = false): bool
 {
 $_SESSION[self::TOKEN] = $this->token = UUID::v4();

 return session_regenerate_id($deleteOldSession);
 }

 public function destroy(): bool
 {
 session_write_close();

 // @codeCoverageIgnoreStart
 if (false === session_start()) {
 return false;
 }
 // @codeCoverageIgnoreEnd

 $updated = session_regenerate_id(true);

 $this->replace([]);
 $this->resetMetadata();

 return $updated;
 }

 public function id(): string
 {
 return session_id();
 }

 public function accessed(): bool
 {
 return $this->accessed;
 }

 public function modified(): bool
 {
 return $this->modified;
 }

 public function token(): string
 {
 return $this->token;
 }

 public function starttime(): float
 {
 return $this->stamp;
 }

 public function agent(): string
 {
 return $this->agent;
 }

 public function isEmpty(): bool
 {
 return 0 === $this->count();
 }

 public function count(): int
 {
 return count($_SESSION);
 }

 /*
 *
 * Session metadata
 *
 */

 /**
 * move CSRF token, start time and user agent into object properties.
 */
 private function loadMetadata(): void
 {
 $this->stamp = $this->pull(self::STAMP, microtime(true));
 $this->agent = $this->pull(self::AGENT, $_SERVER['HTTP_USER_AGENT'] ?? '');
 $this->token = $this->pull(self::TOKEN, UUID::v4());
 }

 private function resetMetadata(): void
 {
 $_SESSION[self::STAMP] = $this->stamp = microtime(true);
 $_SESSION[self::AGENT] = $this->agent = $_SERVER['HTTP_USER_AGENT'] ?? '';
 $_SESSION[self::TOKEN] = $this->token = UUID::v4();
 }

 private function getMetadata(): array
 {
 return [
 self::STAMP => $this->stamp,
 self::AGENT => $this->agent,
 self::TOKEN => $this->token,
 ];
 }
}

/**
 * Class SessionException
 */
class SessionException extends KodedException
{
 private const E_HANDLER_NOT_FOUND = 0;

 protected $messages = [
 self::E_HANDLER_NOT_FOUND => 'Failed to load the session handler class. Requested :handler',
 ];

 public static function forNotFoundHandler(string $handler): SessionException
 {
 return new self(self::E_HANDLER_NOT_FOUND, [':handler' => $handler]);
 }
}