feat(cache): add FileCache implementation for file-based caching

- Introduce FileCache class implementing PSR-16 CacheInterface
- Store cache items as serialized files with expiration timestamps
- Support single and multiple get, set, delete operations
- Automatically create cache directory if it does not exist
- Handle cache expiration and invalid data by deleting stale files
- Use hashed keys to generate cache file names in a dedicated folder

Signed-off-by: guanguans <[email protected]>

Author: guanguans

baselines/disallowed.function.neon

@@ -1,4 +1,4 @@
-# total 7 errors
+# total 8 errors
 
 parameters:
     ignoreErrors:
@@ -12,6 +12,11 @@ parameters:
             count: 1
             path: ../src/Foundation/Authenticators/WsseAuthenticator.php
 
+        -
+            message: '#^Calling hash\(\) is forbidden, use hash\(\) with at least SHA\-256 for secure hash, or password_hash\(\) for passwords\.$#'
+            count: 1
+            path: ../src/Foundation/Caches/FileCache.php
+
         -
             message: '#^Calling var_dump\(\) is forbidden, use some logger instead\.$#'
             count: 1

baselines/loader.neon

@@ -1,4 +1,4 @@
-# total 16 errors
+# total 17 errors
 
 includes:
     - assign.propertyType.neon

composer-dependency-analyser.php

@@ -46,7 +46,6 @@
             'guzzlehttp/psr7',
             'psr/http-factory',
             'psr/http-message',
-            // 'psr/simple-cache',
         ],
         [ErrorType::SHADOW_DEPENDENCY]
     )
@@ -60,6 +59,7 @@
             'illuminate/collections',
             'illuminate/support',
             'symfony/var-dumper',
+            'psr/simple-cache',
         ],
         [ErrorType::DEV_DEPENDENCY_IN_PROD]
     );

composer-updater

@@ -82,8 +82,9 @@ $status = (new SingleCommandApplication)
                 $this->highestComposerBinary = $this->getComposerBinary($composerBinary, $highestPhpBinary);
                 $this->composerBinary = $this->getComposerBinary($composerBinary);
                 $this->exceptPackages = array_merge([
-                    'php',
                     'ext-*',
+                    'php',
+                    'psr/*',
                 ], $exceptPackages);
                 $this->exceptDependencyVersions = array_merge([
                     '\*',

composer.json

@@ -109,6 +109,7 @@
         "phpstan/phpstan-deprecation-rules": "^2.0",
         "phpstan/phpstan-webmozart-assert": "^2.0",
         "povils/phpmnd": "^3.6",
+        "psr/simple-cache": "^1.0 || ^2.0 || ^3.0",
         "rector/rector": "^2.2",
         "rector/swiss-knife": "^2.3",
         "rector/type-perfect": "^2.1",

rector-php82.php

@@ -51,4 +51,9 @@
             'token',
             'webHook',
         ],
+    ])
+    ->withSkip([
+        AddSensitiveParameterAttributeRector::class => [
+            __DIR__.'/src/Foundation/Caches/',
+        ],
     ]);

src/Foundation/Caches/FileCache.php

@@ -0,0 +1,205 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Copyright (c) 2021-2025 guanguans<[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ *
+ * @see https://github.com/guanguans/notify
+ */
+
+namespace Guanguans\Notify\Foundation\Caches;
+
+use Psr\SimpleCache\CacheInterface;
+
+/**
+ * @see https://github.com/pestphp/pest-plugin-mutate/blob/4.x/src/Cache/FileStore.php
+ */
+class FileCache implements CacheInterface
+{
+    /** @var string */
+    private const CACHE_FOLDER_NAME = 'pest-mutate-cache';
+
+    /** @readonly */
+    private string $directory;
+
+    public function __construct(?string $directory = null)
+    {
+        $this->directory = $directory ?? (sys_get_temp_dir().\DIRECTORY_SEPARATOR.self::CACHE_FOLDER_NAME); // @pest-mutate-ignore
+
+        if (!is_dir($this->directory)) { // @pest-mutate-ignore
+            mkdir($this->directory, recursive: true);
+        }
+    }
+
+    public function get(string $key, mixed $default = null): mixed
+    {
+        return $this->getPayload($key) ?? $default;
+    }
+
+    public function set(string $key, mixed $value, null|\DateInterval|int $ttl = null): bool
+    {
+        $payload = serialize($value);
+
+        $expire = $this->expiration($ttl);
+
+        $content = $expire.$payload;
+
+        $result = file_put_contents($this->filePathFromKey($key), $content);
+
+        return false !== $result; // @pest-mutate-ignore FalseToTrue
+    }
+
+    public function delete(string $key): bool
+    {
+        return unlink($this->filePathFromKey($key));
+    }
+
+    public function clear(): bool
+    {
+        foreach ((array) glob($this->directory.\DIRECTORY_SEPARATOR.'*') as $fileName) {
+            // @pest-mutate-ignore
+            if (false === $fileName) {
+                continue;
+            }
+
+            if (!str_starts_with(basename($fileName), 'cache-')) {
+                continue;
+            }
+
+            // @pest-mutate-ignore
+            unlink($fileName);
+        }
+
+        return true;
+    }
+
+    public function getMultiple(iterable $keys, mixed $default = null): iterable
+    {
+        $result = [];
+
+        foreach ($keys as $key) {
+            $result[$key] = $this->get($key, $default);
+        }
+
+        return $result;
+    }
+
+    /**
+     * @param iterable<string, mixed> $values
+     *
+     * @throws \Psr\SimpleCache\InvalidArgumentException
+     */
+    public function setMultiple(iterable $values, null|\DateInterval|int $ttl = null): bool
+    {
+        $result = true;
+
+        foreach ($values as $key => $value) {
+            if (!$this->set($key, $value, $ttl)) {
+                $result = false;
+            }
+        }
+
+        return $result;
+    }
+
+    /**
+     * @param iterable<string> $keys
+     *
+     * @throws \Psr\SimpleCache\InvalidArgumentException
+     */
+    public function deleteMultiple(iterable $keys): bool
+    {
+        $result = true;
+
+        foreach ($keys as $key) {
+            if (!$this->delete($key)) {
+                $result = false;
+            }
+        }
+
+        return $result;
+    }
+
+    public function has(string $key): bool
+    {
+        return file_exists($this->filePathFromKey($key));
+    }
+
+    public function directory(): string
+    {
+        return $this->directory;
+    }
+
+    protected function emptyPayload(): mixed
+    {
+        return null;
+    }
+
+    private function filePathFromKey(string $key): string
+    {
+        return $this->directory.\DIRECTORY_SEPARATOR.'cache-'.hash('md5', $key); // @pest-mutate-ignore
+    }
+
+    private function expiration(null|\DateInterval|int $seconds): int
+    {
+        if ($seconds instanceof \DateInterval) {
+            return (new \DateTimeImmutable)->add($seconds)->getTimestamp();
+        }
+
+        $seconds ??= 0;
+
+        if (0 === $seconds) {
+            return 9_999_999_999; // @pest-mutate-ignore
+        }
+
+        return time() + $seconds;
+    }
+
+    /**
+     * @throws \Psr\SimpleCache\InvalidArgumentException
+     */
+    private function getPayload(string $key): mixed
+    {
+        if (!file_exists($this->filePathFromKey($key))) {
+            return $this->emptyPayload();
+        }
+
+        $content = file_get_contents($this->filePathFromKey($key));
+
+        if (false === $content) { // @pest-mutate-ignore
+            return $this->emptyPayload();
+        }
+
+        try {
+            $expire = (int) substr(
+                $content,
+                0,
+                10
+            );
+        } catch (\Exception) {
+            $this->delete($key);
+
+            return $this->emptyPayload();
+        }
+
+        if (time() >= $expire) {
+            $this->delete($key);
+
+            return $this->emptyPayload();
+        }
+
+        try {
+            $data = unserialize(substr($content, 10));
+        } catch (\Exception) {
+            $this->delete($key);
+
+            return $this->emptyPayload();
+        }
+
+        return $data;
+    }
+}