From c36999d9b0182dd2752ef7b7199557254ea033fe Mon Sep 17 00:00:00 2001 From: Joao Gilberto Magalhaes Date: Fri, 6 Nov 2026 09:03:03 -0500 Subject: [PATCH] Add PhpFileCacheEngine: entries as PHP files read through OPcache Each entry is a PHP file (get(); | [RedisCacheEngine](docs/class-redis-cache-engine.md) | Redis-based caching | | [SessionCacheEngine](docs/class-session-cache-engine.md) | PHP session-based caching | | [TmpfsCacheEngine](docs/class-tmpfs-cache-engine.md) | Tmpfs-based caching | +| [PhpFileCacheEngine](docs/class-php-file-cache-engine.md) | PHP files read through OPcache, for entries written once (a DI container) | ### Advanced Features - [Atomic Operations](docs/atomic-operations.md) diff --git a/docs/class-php-file-cache-engine.md b/docs/class-php-file-cache-engine.md new file mode 100644 index 0000000..011289d --- /dev/null +++ b/docs/class-php-file-cache-engine.md @@ -0,0 +1,37 @@ +--- +sidebar_position: 10 +--- + +# PhpFileCacheEngine + +Each entry is a PHP file (`set('key', ['a' => 1]); +``` + +## When to use it + +For entries **written once and read on every request**: a DI container (byjg/config's `withCache()`), compiled +data, a configuration. A web request (PHP-FPM) reads them from OPcache instead of opening and unserializing a file. + +**Not** for values that change often (sessions, query results, counters): each write compiles the file again, and +OPcache keeps the previous version as wasted memory until it restarts (`opcache.max_wasted_percentage`), which +empties the whole OPcache at once. Use `FileSystemCacheEngine`, `RedisCacheEngine` or `MemcachedEngine` for those. + +## Details + +- **Files readable by their owner only (0600)**: an entry can hold secrets (a cached configuration has the + passwords). The user that reads the cache (PHP-FPM) must be the one that writes it. +- **Never read half written**: a file is written to a temporary file and renamed, then invalidated in OPcache + (`opcache_invalidate()`), so a change is seen even with `opcache.validate_timestamps=0`. +- **TTL**: an expired entry is removed when it is read. There is no garbage collector nor atomic operation. +- A `null` value removes the entry, as `FileSystemCacheEngine` does. +- `isAvailable()` is false when the directory does not exist or cannot be written. diff --git a/src/Psr16/PhpFileCacheEngine.php b/src/Psr16/PhpFileCacheEngine.php new file mode 100644 index 0000000..18a8a3e --- /dev/null +++ b/src/Psr16/PhpFileCacheEngine.php @@ -0,0 +1,204 @@ +prefix = $prefix; + $this->path = $path ?? sys_get_temp_dir(); + $this->logger = $logger ?? new NullLogger(); + } + + /** + * @throws ContainerExceptionInterface + * @throws NotFoundExceptionInterface + * @throws InvalidArgumentException + */ + #[Override] + public function get(string $key, mixed $default = null): mixed + { + $entry = $this->read($this->fileName($this->getKeyFromContainer($key))); + if ($entry === null) { + $this->logger->info("[PhpFile cache] Not found '$key'"); + return $default; + } + + $this->logger->info("[PhpFile cache] Get '$key'"); + [, $serialized, $value] = $entry; + return $serialized ? unserialize($value) : $value; + } + + /** + * @throws ContainerExceptionInterface + * @throws NotFoundExceptionInterface + * @throws InvalidArgumentException + */ + #[Override] + public function set(string $key, mixed $value, DateInterval|int|null $ttl = null): bool + { + $file = $this->fileName($this->getKeyFromContainer($key)); + + // As FileSystemCacheEngine: a null value removes the entry + if (is_null($value)) { + $this->remove($file); + return true; + } + + $this->logger->info("[PhpFile cache] Set '$key'"); + $serialized = !self::isExportable($value); + $entry = [$this->addToNow($ttl), $serialized, $serialized ? serialize($value) : $value]; + $code = "logger->warning("[PhpFile cache] Could not write '$key' in '$this->path'"); + return false; + } + chmod($temp, 0600); + if (!rename($temp, $file)) { + @unlink($temp); + $this->logger->warning("[PhpFile cache] Could not write '$key' in '$this->path'"); + return false; + } + $this->invalidate($file); + + return true; + } + + /** + * @throws ContainerExceptionInterface + * @throws NotFoundExceptionInterface + * @throws InvalidArgumentException + */ + #[Override] + public function delete(string $key): bool + { + $this->remove($this->fileName($this->getKeyFromContainer($key))); + return true; + } + + #[Override] + public function clear(): bool + { + foreach (glob($this->fileName('*')) ?: [] as $file) { + $this->remove($file); + } + return true; + } + + /** + * @throws ContainerExceptionInterface + * @throws NotFoundExceptionInterface + * @throws InvalidArgumentException + */ + #[Override] + public function has(string $key): bool + { + return $this->read($this->fileName($this->getKeyFromContainer($key))) !== null; + } + + #[Override] + public function isAvailable(): bool + { + return is_dir($this->path) && is_writable($this->path); + } + + /** + * The file of a key (or of a glob pattern) + */ + protected function fileName(string $key): string + { + return $this->path . '/' . $this->prefix . '-' . preg_replace("/[\/\\\\]/", "#", $key) . '.php'; + } + + /** + * The entry of a file: [expires at, serialized, value]; null when there is none or it expired (then removed) + * + * @return array{0: int|null, 1: bool, 2: mixed}|null + */ + protected function read(string $file): ?array + { + if (!is_file($file)) { + return null; + } + $entry = include $file; + if (!is_array($entry) || count($entry) !== 3) { + return null; + } + if ($entry[0] !== null && time() >= $entry[0]) { + $this->remove($file); + return null; + } + return $entry; + } + + protected function remove(string $file): void + { + if (is_file($file)) { + unlink($file); + $this->invalidate($file); + } + } + + /** + * OPcache must not serve the previous version of a file that changed (with opcache.validate_timestamps off, + * it would never see the change) + */ + protected function invalidate(string $file): void + { + if (function_exists('opcache_invalidate')) { + @opcache_invalidate($file, true); + } + } + + /** + * Whether var_export() writes the value as PHP code that gives it back as it is: scalars and arrays of them + */ + protected static function isExportable(mixed $value): bool + { + if (is_array($value)) { + foreach ($value as $item) { + if (!self::isExportable($item)) { + return false; + } + } + return true; + } + // A float that var_export() cannot write back exactly (INF, NAN) is serialized + return is_null($value) || is_bool($value) || is_int($value) || is_string($value) + || (is_float($value) && is_finite($value)); + } +} diff --git a/tests/PhpFileCacheEngineTest.php b/tests/PhpFileCacheEngineTest.php new file mode 100644 index 0000000..0d03639 --- /dev/null +++ b/tests/PhpFileCacheEngineTest.php @@ -0,0 +1,96 @@ + [new PhpFileCacheEngine('test-phpfile')], + ]; + } + + private function engine(): PhpFileCacheEngine + { + return $this->cacheEngine = new PhpFileCacheEngine('test-phpfile'); + } + + private function file(string $key): string + { + return sys_get_temp_dir() . "/test-phpfile-$key.php"; + } + + /** + * Scalars and arrays are written as PHP code (OPcache keeps them in memory), the rest serialized: both come back + * as they were + */ + public function testAValueComesBackAsItWas(): void + { + $engine = $this->engine(); + $values = [ + 'string' => "it's a \"string\"\n\\ with \0 and ΓΌ", + 'int' => PHP_INT_MAX, + 'float' => 0.1 + 0.2, + 'bool' => false, + 'array' => ['a' => [1, 2.5, 'x', true, null], 7 => 'seven'], + 'object' => new DateTime('2024-01-02 03:04:05'), + 'infinite' => INF, + ]; + foreach ($values as $key => $value) { + $engine->set($key, $value); + } + + foreach ($values as $key => $value) { + $this->assertEquals($value, $engine->get($key), $key); + } + $this->assertSame($values['float'], $engine->get('float')); + $this->assertStringNotContainsString('serialize', file_get_contents($this->file('array'))); + $this->assertStringContainsString('O:8:\"DateTime\"', addslashes(file_get_contents($this->file('object')))); + } + + /** + * An entry can hold a secret (a cached configuration): only its owner can read the file + */ + public function testTheFileIsReadableByItsOwnerOnly(): void + { + $this->engine()->set('secret', 'password'); + + $this->assertSame(0600, fileperms($this->file('secret')) & 0777); + } + + public function testAValueReplacedIsReadAsItIsNow(): void + { + $engine = $this->engine(); + $engine->set('key', 'first'); + $this->assertSame('first', $engine->get('key')); + + $engine->set('key', 'second'); + + $this->assertSame('second', $engine->get('key')); + // No temporary file is left behind + $this->assertSame([$this->file('key')], glob(sys_get_temp_dir() . '/test-phpfile-key.php*')); + } + + public function testAFileThatIsNotAnEntryIsNotFound(): void + { + file_put_contents($this->file('other'), "assertFalse($this->engine()->has('other')); + $this->assertSame('default', $this->engine()->get('other', 'default')); + } + + public function testAnEngineInADirectoryThatDoesNotExistIsNotAvailable(): void + { + $engine = new PhpFileCacheEngine('test-phpfile', sys_get_temp_dir() . '/does-not-exist-' . uniqid()); + + $this->assertFalse($engine->isAvailable()); + $this->assertFalse($engine->set('key', 'value')); + } +}