README

Image import and embedding utilities for PDF streams.

💖 Part of the tc-lib-pdf / TCPDF ecosystem (100M+ installs). Sponsor its maintenance →

Overview

tc-lib-pdf-image handles image import, conversion, and output structures used by PDF generators.

The library isolates image pipeline concerns such as format handling, normalization, and object generation for PDF embedding. Keeping this logic separate helps reduce complexity in document-level code and makes image behavior easier to validate and maintain.

Features

Import Support

• Native handling for PNG and JPEG
• Additional format handling through GD processing paths
• Transparency and palette-related metadata handling

PDF Integration

• Image caching keys for repeated assets
• Alternate image support for print/display contexts
• Output helpers for embedding image objects

Requirements

• PHP 8.2 or later
• Extensions: gd, zlib
• Composer

Installation

composer require tecnickcom/tc-lib-pdf-image

Quick Start

<?php

require_once __DIR__ . '/vendor/autoload.php';

$encrypt = new \Com\Tecnick\Pdf\Encrypt\Encrypt();
$fileHelper = new \Com\Tecnick\File\File();

$img = new \Com\Tecnick\Pdf\Image\Import(
	kunit: 1.0,
	encrypt: $encrypt,
	fileHelper: $fileHelper,
);
$imageId = $img->add('/path/to/image.png');

var_dump($imageId);

You can configure the \Com\Tecnick\File\File helper with host/path allowlists:

$fileHelper = new \Com\Tecnick\File\File(
	allowedHosts: ['example.com', 'cdn.example.com'],
	allowedPaths: ['/srv/app/images', __DIR__ . '/images'],
);

For full file-loading options, see the tc-lib-file documentation: https://tcpdf.org/docs/srcdoc/tc-lib-file

Persistent image cache

Processing an image (decode, resize, re-encode, alpha-mask extraction) is the expensive part of importing. By default the result is cached in memory for the lifetime of the Import instance, so reusing the same image within one document is cheap.

To reuse processed images across documents and processes (e.g. brand assets reused on thousands of PDFs), inject an optional external cache. The library ships only the contract — \Com\Tecnick\Pdf\Image\ImageCacheInterface — and you provide the backend (filesystem, APCu, Redis, a PSR-16 cache, ...):

interface ImageCacheInterface
{
	/** @return array|null Stored image data, or null on a miss. */
	public function get(string $key): ?array;

	public function set(string $key, array $data): void;
}

Pass an implementation to the constructor (default null keeps the current in-memory-only behaviour):

$img = new \Com\Tecnick\Pdf\Image\Import(
	kunit: 1.0,
	encrypt: $encrypt,
	fileHelper: $fileHelper,
	imageCache: $myCache, // any ImageCacheInterface implementation
);

On a miss the processed data is written through to the cache; on a later run a hit short-circuits all processing. For local files the persistent key folds in the file modification time and size, so editing an image in place invalidates its stale entry automatically.

Security: the cache store is a trust boundary. Stored bytes (image data, palette, ICC profile) are embedded verbatim into generated PDFs, so use a store only your application can write to. If your implementation serializes entries, deserialize with object restoration disabled, e.g. unserialize($s, ['allowed_classes' => false]).

A minimal example implementation:

use Com\Tecnick\Pdf\Image\ImageCacheInterface;

final class FilesystemImageCache implements ImageCacheInterface
{
	public function __construct(private readonly string $dir) {}

	public function get(string $key): ?array
	{
		$file = $this->dir . '/' . hash('xxh128', $key) . '.cache';
		if (!is_file($file)) {
			return null;
		}
		$data = unserialize((string) file_get_contents($file), ['allowed_classes' => false]);
		return is_array($data) ? $data : null;
	}

	public function set(string $key, array $data): void
	{
		$file = $this->dir . '/' . hash('xxh128', $key) . '.cache';
		file_put_contents($file, serialize($data), LOCK_EX);
	}
}

Development

make deps
make help
make qa

Packaging

make rpm
make deb

For system packages, bootstrap with:

require_once '/usr/share/php/Com/Tecnick/Pdf/Image/autoload.php';

Contributing

Contributions are welcome. Please review CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.