External Cache

tc-lib-pdf can reuse generated font subsets and processed images across Tcpdf instances and PHP processes through an optional external cache that you provide.

No cache backend is shipped: you implement an interface that bridges to your own store (filesystem, APCu, Redis, a PSR-16 cache, and so on). Caching is disabled by default.

One cache instance is reused by every cacheable subsystem (font subsets and images), so a single backend, connection, and configuration serves them all.

The CacheInterface

Implement Com\Tecnick\Pdf\Cache\CacheInterface:

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 image library treats a throwing backend as a cache miss, but the font library calls the cache directly and does not catch exceptions, so a throwing implementation will break PDF generation.

An image entry read from the store is validated before it is used, and an entry that does not match the expected shape is discarded as a miss.

Enabling the Cache

Pass your implementation as the cache argument of the Tcpdf constructor (the last parameter):

$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:

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

The cached types are also available as the backed enum Com\Tecnick\Pdf\Cache\CacheType (font, image), whose values match the TYPE_* constants.

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, for example 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:

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:

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]).

Related Guides

• Font generation and subsetting that feeds the font cache: /docs/fonts/
• Remote and local asset controls: /docs/remote-resources/
• Development and validation workflow: /docs/development/

Previous: /docs/pdf-import/

Overview: /docs/

Next: /docs/fonts/