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 imports images, converts them to the formats a PDF can embed, and generates the corresponding PDF image objects.


Namespace	`\Com\Tecnick\Pdf\Image`
Author	Nicola Asuni info@tecnick.com
License	GNU LGPL v3 - see LICENSE
API docs	https://tcpdf.org/docs/srcdoc/tc-lib-pdf-image
Packagist	https://packagist.org/packages/tecnickcom/tc-lib-pdf-image

Features

Import

Native PNG and JPEG parsing
Other formats re-encoded to PNG or JPEG through GD
Transparency, palette and ICC profile handling

PDF integration

Cache keys to reuse repeated images
Alternate images for print and display contexts
Output of the image XObjects and of the XObject dictionary

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();

// the file helper allows nothing by default: list the directories and hosts
// the images may be loaded from
$fileHelper = new \Com\Tecnick\File\File(
	allowedPaths: ['/path/to'],
);

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

var_dump($imageId);

Remote images require a host allowlist as well:

$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

The processed image data is cached in memory for the lifetime of the Import instance, so the same image imported twice within one document is processed once.

To reuse processed images across documents and processes, inject an external cache. The library defines only the contract, \Com\Tecnick\Pdf\Image\ImageCacheInterface, and the backend (filesystem, APCu, Redis, a PSR-16 cache, ...) is provided by the application:

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; the default null keeps the in-memory cache only:

$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; a hit skips the processing. For local files the key includes the file modification time and size, so editing an image in place invalidates its stale entry.

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

An 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.

tecnickcom / tc-lib-pdf-image

Maintainers

Package info

Fund package maintenance!

Statistics

Security