feat: use PSR20 ClockInterface for session handling

- Introduced a new `SystemClock` class implementing `ClockInterface` for time management.
- Updated `ArraySessionHandler` and `CacheSessionHandler` to utilize the `SystemClock` for timestamping, enhancing testability and flexibility.
- Added a `FixedClock` mock for testing purposes, allowing controlled time manipulation in tests.

Author: CodeWithKyrian

composer.json

@@ -15,6 +15,7 @@
         "opis/json-schema": "^2.4",
         "php-mcp/schema": "dev-main",
         "phpdocumentor/reflection-docblock": "^5.6",
+        "psr/clock": "^1.0",
         "psr/container": "^1.0 || ^2.0",
         "psr/event-dispatcher": "^1.0",
         "psr/log": "^1.0 || ^2.0 || ^3.0",

src/Defaults/SystemClock.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpMcp\Server\Defaults;
+
+use DateTimeImmutable;
+use Psr\Clock\ClockInterface;
+
+class SystemClock implements ClockInterface
+{
+    public function now(): \DateTimeImmutable
+    {
+        return new \DateTimeImmutable();
+    }
+}

src/Session/ArraySessionHandler.php

@@ -5,6 +5,8 @@
 namespace PhpMcp\Server\Session;
 
 use PhpMcp\Server\Contracts\SessionHandlerInterface;
+use PhpMcp\Server\Defaults\SystemClock;
+use Psr\Clock\ClockInterface;
 
 class ArraySessionHandler implements SessionHandlerInterface
 {
@@ -13,8 +15,13 @@ class ArraySessionHandler implements SessionHandlerInterface
      */
     protected array $store = [];
 
-    public function __construct(public readonly int $ttl = 3600)
-    {
+    private ClockInterface $clock;
+
+    public function __construct(
+        public readonly int $ttl = 3600,
+        ?ClockInterface $clock = null
+    ) {
+        $this->clock = $clock ?? new SystemClock();
     }
 
     public function read(string $sessionId): string|false
@@ -24,7 +31,7 @@ public function read(string $sessionId): string|false
             return false;
         }
 
-        $currentTimestamp = time();
+        $currentTimestamp = $this->clock->now()->getTimestamp();
 
         if ($currentTimestamp - $session['timestamp'] > $this->ttl) {
             unset($this->store[$sessionId]);
@@ -38,7 +45,7 @@ public function write(string $sessionId, string $data): bool
     {
         $this->store[$sessionId] = [
             'data' => $data,
-            'timestamp' => time(),
+            'timestamp' => $this->clock->now()->getTimestamp(),
         ];
 
         return true;
@@ -55,7 +62,7 @@ public function destroy(string $sessionId): bool
 
     public function gc(int $maxLifetime): array
     {
-        $currentTimestamp = time();
+        $currentTimestamp = $this->clock->now()->getTimestamp();
         $deletedSessions = [];
 
         foreach ($this->store as $sessionId => $session) {

src/Session/CacheSessionHandler.php

@@ -5,30 +5,45 @@
 namespace PhpMcp\Server\Session;
 
 use PhpMcp\Server\Contracts\SessionHandlerInterface;
+use PhpMcp\Server\Defaults\SystemClock;
 use Psr\SimpleCache\CacheInterface;
+use Psr\Clock\ClockInterface;
 
 class CacheSessionHandler implements SessionHandlerInterface
 {
     private const SESSION_INDEX_KEY = 'mcp_session_index';
     private array $sessionIndex = [];
+    private ClockInterface $clock;
 
     public function __construct(
         public readonly CacheInterface $cache,
-        public readonly int $ttl = 3600
+        public readonly int $ttl = 3600,
+        ?ClockInterface $clock = null
     ) {
         $this->sessionIndex = $this->cache->get(self::SESSION_INDEX_KEY, []);
+        $this->clock = $clock ?? new SystemClock();
     }
 
     public function read(string $sessionId): string|false
     {
-        return $this->cache->get($sessionId, false);
+        $session = $this->cache->get($sessionId, false);
+        if ($session === false) {
+            return false;
+        }
+
+        if ($this->clock->now()->getTimestamp() - $this->sessionIndex[$sessionId] > $this->ttl) {
+            $this->cache->delete($sessionId);
+            return false;
+        }
+
+        return $session;
     }
 
     public function write(string $sessionId, string $data): bool
     {
-        $this->sessionIndex[$sessionId] = time();
+        $this->sessionIndex[$sessionId] = $this->clock->now()->getTimestamp();
         $this->cache->set(self::SESSION_INDEX_KEY, $this->sessionIndex);
-        return $this->cache->set($sessionId, $data, $this->ttl);
+        return $this->cache->set($sessionId, $data);
     }
 
     public function destroy(string $sessionId): bool
@@ -40,7 +55,7 @@ public function destroy(string $sessionId): bool
 
     public function gc(int $maxLifetime): array
     {
-        $currentTime = time();
+        $currentTime = $this->clock->now()->getTimestamp();
         $deletedSessions = [];
 
         foreach ($this->sessionIndex as $sessionId => $timestamp) {

tests/Mocks/Clock/FixedClock.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpMcp\Server\Tests\Mocks\Clock;
+
+use DateTimeImmutable;
+use DateTimeZone;
+use Psr\Clock\ClockInterface;
+use DateInterval;
+
+class FixedClock implements ClockInterface
+{
+    private DateTimeImmutable $currentTime;
+
+    public function __construct(string|DateTimeImmutable $initialTime = 'now', ?DateTimeZone $timezone = null)
+    {
+        if ($initialTime instanceof DateTimeImmutable) {
+            $this->currentTime = $initialTime;
+        } else {
+            $this->currentTime = new DateTimeImmutable($initialTime, $timezone);
+        }
+    }
+
+    public function now(): DateTimeImmutable
+    {
+        return $this->currentTime;
+    }
+
+    public function setCurrentTime(string|DateTimeImmutable $newTime, ?DateTimeZone $timezone = null): void
+    {
+        if ($newTime instanceof DateTimeImmutable) {
+            $this->currentTime = $newTime;
+        } else {
+            $this->currentTime = new DateTimeImmutable($newTime, $timezone);
+        }
+    }
+
+    public function advance(DateInterval $interval): void
+    {
+        $this->currentTime = $this->currentTime->add($interval);
+    }
+
+    public function rewind(DateInterval $interval): void
+    {
+        $this->currentTime = $this->currentTime->sub($interval);
+    }
+
+    public function addSecond(): void
+    {
+        $this->advance(new DateInterval("PT1S"));
+    }
+
+    public function addSeconds(int $seconds): void
+    {
+        $this->advance(new DateInterval("PT{$seconds}S"));
+    }
+
+    public function addMinutes(int $minutes): void
+    {
+        $this->advance(new DateInterval("PT{$minutes}M"));
+    }
+
+    public function addHours(int $hours): void
+    {
+        $this->advance(new DateInterval("PT{$hours}H"));
+    }
+
+    public function subSeconds(int $seconds): void
+    {
+        $this->rewind(new DateInterval("PT{$seconds}S"));
+    }
+
+    public function subMinutes(int $minutes): void
+    {
+        $this->rewind(new DateInterval("PT{$minutes}M"));
+    }
+}