generated from jric11/baseProject
119 lines
4.5 KiB
Markdown
119 lines
4.5 KiB
Markdown
# External Cache
|
|
|
|
Back to root overview: [README.md](../README.md#in-depth-documentation)
|
|
|
|
Generating font subsets and processing images (decode, resize, re-encode) is computationally expensive. `tc-lib-pdf` can reuse these results across `Tcpdf` instances and PHP processes through an **optional external cache** that you provide.
|
|
|
|
No cache backend is shipped: you implement a tiny interface that bridges to whatever store you already use (filesystem, APCu, Redis, a PSR-16 cache, ...). Caching is **disabled by default**: when no cache is supplied, behavior is unchanged.
|
|
|
|
One cache instance is reused by every cacheable subsystem (currently font subsets and images, more may be added later), so a single backend, connection, and configuration serves them all.
|
|
|
|
## The CacheInterface
|
|
|
|
Implement `Com\Tecnick\Pdf\Cache\CacheInterface`:
|
|
|
|
```php
|
|
namespace Com\Tecnick\Pdf\Cache;
|
|
|
|
interface CacheInterface
|
|
{
|
|
public function get(string $key): mixed; // stored value, or null on a miss
|
|
public function set(string $key, mixed $value): void;
|
|
}
|
|
```
|
|
|
|
Both methods MUST be **best-effort** and **MUST NOT throw**: a backend miss or transient failure must surface as `null` (on `get`) or a silent no-op (on `set`). The font and image libraries call the cache directly and do not catch exceptions, so a throwing implementation will break PDF generation.
|
|
|
|
## Enabling the Cache
|
|
|
|
Pass your implementation as the `cache` argument of the `Tcpdf` constructor (the last parameter):
|
|
|
|
```php
|
|
$cache = new MyRedisCache(); // implements Com\Tecnick\Pdf\Cache\CacheInterface
|
|
|
|
$pdf = new \Com\Tecnick\Pdf\Tcpdf(
|
|
unit: 'mm',
|
|
subsetfont: true, // required for the font subset cache to be exercised
|
|
cache: $cache,
|
|
);
|
|
```
|
|
|
|
A minimal in-memory implementation (useful for tests or single-request deduplication):
|
|
|
|
```php
|
|
use Com\Tecnick\Pdf\Cache\CacheInterface;
|
|
|
|
$cache = new class implements CacheInterface {
|
|
/** @var array<string, mixed> */
|
|
private array $store = [];
|
|
|
|
public function get(string $key): mixed
|
|
{
|
|
return $this->store[$key] ?? null;
|
|
}
|
|
|
|
public function set(string $key, mixed $value): void
|
|
{
|
|
$this->store[$key] = $value;
|
|
}
|
|
};
|
|
```
|
|
|
|
## What Gets Cached
|
|
|
|
| Subsystem | Type constant | Cached value | Key prefix |
|
|
|-----------|---------------|--------------|------------|
|
|
| Font subsets | `CacheInterface::TYPE_FONT` | Raw subset font program (`string`, uncompressed) | `tc-lib-pdf-font:subset:v2:` |
|
|
| Images | `CacheInterface::TYPE_IMAGE` | Processed image snapshot (`array`) | `tc-lib-pdf-image:v2:` |
|
|
|
|
Keys are already namespaced and schema-versioned by each sub-library, so a single shared store is collision-safe. The font subset cache is only consulted when font subsetting is enabled (`subsetfont: true`).
|
|
|
|
The library never evicts entries: expiration, size limits, and (de)serialization are entirely the backend's responsibility. When an implementation deserializes data it MUST disable object restoration, e.g. `unserialize($data, ['allowed_classes' => false])`.
|
|
|
|
## Caching Only Some Types
|
|
|
|
To cache only a subset of the subsystems, implement `Com\Tecnick\Pdf\Cache\SelectiveCacheInterface` (which extends `CacheInterface`) and report which types you handle:
|
|
|
|
```php
|
|
namespace Com\Tecnick\Pdf\Cache;
|
|
|
|
interface SelectiveCacheInterface extends CacheInterface
|
|
{
|
|
/** @param CacheInterface::TYPE_* $type */
|
|
public function supports(string $type): bool;
|
|
}
|
|
```
|
|
|
|
When `supports()` returns `false` for a type, that type is disabled entirely: the cache is never queried or written for it, and your implementation never receives its data. A plain `CacheInterface` (without `supports()`) caches every type.
|
|
|
|
For example, to cache font subsets but never images:
|
|
|
|
```php
|
|
use Com\Tecnick\Pdf\Cache\CacheInterface;
|
|
use Com\Tecnick\Pdf\Cache\SelectiveCacheInterface;
|
|
|
|
$cache = new class implements SelectiveCacheInterface {
|
|
/** @var array<string, mixed> */
|
|
private array $store = [];
|
|
|
|
public function supports(string $type): bool
|
|
{
|
|
return $type === CacheInterface::TYPE_FONT;
|
|
}
|
|
|
|
public function get(string $key): mixed
|
|
{
|
|
return $this->store[$key] ?? null;
|
|
}
|
|
|
|
public function set(string $key, mixed $value): void
|
|
{
|
|
$this->store[$key] = $value;
|
|
}
|
|
};
|
|
```
|
|
|
|
## Security
|
|
|
|
The cache store is a **trust boundary**. Cached values are embedded verbatim into generated PDFs, so anyone able to write to the backend can influence document output. Use a store only your application can write to, and always deserialize with object restoration disabled (`['allowed_classes' => false]`).
|