Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG-7.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,15 @@ concurrent `increment()` calls on Memcached ended at **8** instead of 20, and tw

## New Features

### PhpFileCacheEngine

A PSR-16 engine whose entries are PHP files (`<?php return [...];`), read with `include`: with OPcache, an entry is
read from memory. Scalars and arrays are written as PHP code (nothing to decode), other values serialized; the files
are `0600`, written to a temporary file and renamed, and invalidated in OPcache. For entries written once and read on
every request, such as byjg/config's cached container: reading php-gluo's container from it instead of
`FileSystemCacheEngine` removes ~300 us of file reads per web request. Not for values that change often: see
[PhpFileCacheEngine](docs/class-php-file-cache-engine.md).

### CompareAndSwapInterface

A new interface for conditional writes that the storage engine resolves in one indivisible step:
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ $value = $item->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)
Expand Down
37 changes: 37 additions & 0 deletions docs/class-php-file-cache-engine.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
sidebar_position: 10
---

# PhpFileCacheEngine

Each entry is a PHP file (`<?php return [...];`), read with `include`. With OPcache, an entry is read from memory,
not from the disk: a value of scalars and arrays is written as PHP code, which OPcache keeps in shared memory with
nothing to decode, and any other value (an object) is written serialized.

```php
<?php
$cache = new \ByJG\Cache\Psr16\PhpFileCacheEngine(
'config', // The start of the file names (default: 'cache')
'/var/cache' // The directory (default: the system temp dir); it must exist
);
$cache->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.
204 changes: 204 additions & 0 deletions src/Psr16/PhpFileCacheEngine.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,204 @@
<?php

namespace ByJG\Cache\Psr16;

use DateInterval;
use Override;
use Psr\Container\ContainerExceptionInterface;
use Psr\Container\NotFoundExceptionInterface;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Psr\SimpleCache\InvalidArgumentException;

/**
* A cache whose entries are PHP files (`<?php return [...];`), read with `include`: with OPcache, an entry is read
* from memory, not from the disk. A value of scalars and arrays is written as PHP code, kept in OPcache's shared
* memory with nothing to decode; any other value is written serialized.
*
* For entries written once and read on every request (a DI container, compiled data). Each write compiles the
* file again, and OPcache keeps the previous version as wasted memory until it restarts: do not use it for values
* that change often (sessions, query results, counters).
*
* The files are readable by their owner only (0600), as an entry may hold secrets (a cached configuration).
*/
class PhpFileCacheEngine extends BaseCacheEngine
{
protected LoggerInterface $logger;

protected string $prefix;

protected string $path;

/**
* @param string $prefix The start of the name of the files
* @param string|null $path The directory of the files; the system temp dir by default
* @param LoggerInterface|null $logger
*/
public function __construct(string $prefix = 'cache', ?string $path = null, ?LoggerInterface $logger = null)
{
$this->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 = "<?php\n\nreturn " . var_export($entry, true) . ";\n";

// Written to a temporary file and renamed: a request never includes a file half written
$temp = $file . '.' . bin2hex(random_bytes(6)) . '.tmp';
if (@file_put_contents($temp, $code) === false) {
$this->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));
}
}
96 changes: 96 additions & 0 deletions tests/PhpFileCacheEngineTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
<?php

namespace Tests;

use ByJG\Cache\Psr16\PhpFileCacheEngine;
use DateTime;

/**
* PhpFileCacheEngine: the PSR-16 tests of every engine (CachePSR16Test), and what is particular to it
*/
class PhpFileCacheEngineTest extends CachePSR16Test
{
public static function CachePoolProvider(): array
{
return [
'PhpFile' => [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'), "<?php\nreturn 'something else';\n");

$this->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'));
}
}
Loading