pdftoolkit / pdf-codecs

v0.1.0 2026-10-28 20:15 UTC

Requires

• php: ^8.3
• php-64bit: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.0

Apache-2.0

• Mathias STRASSER

Published on Packagist.org on 2026-10-28 20:21 UTC

README

English | Français

A separate, optional PHP library for JPEG (DCTDecode), JPEG 2000 (JPXDecode) and JBIG2 (JBIG2Decode) image decoding. It accepts encoded bytes and returns explicit component planes. It does not read a PDF document or render a page.

The codec guides record implemented mechanisms, executable validation and explicit exclusions. A passing fixture corpus does not establish universal conformance for every possible codestream.

Installation and use

composer require pdftoolkit/pdf-codecs:^0.1

use PDFToolkit\Codecs\Codec;
use PDFToolkit\Codecs\DecodeLimits;
use PDFToolkit\Codecs\DecodeRequest;
use PDFToolkit\Codecs\PhpDecoder;

$decoder = new PhpDecoder(new DecodeLimits(maxPixels: 4_000_000));
$image = $decoder->decode(new DecodeRequest(Codec::Jpeg2000, $encodedBytes));
$sample = $image->components[0]->sample(0, 0);

The caller supplies the encoded bytes. The explicit local-file application is examples/decode.php.

Guide	Implemented scope
Architecture	Immutable requests/results, component planes and resource ownership.
JPEG	Eight-bit sequential and progressive DCT, sampling, restart markers and PDF colour-transform precedence.
JPEG 2000	PDF JPX component decoding, precision and geometry, codestream transforms and retained colour/alpha metadata.
JBIG2	PDF bilevel arithmetic/Huffman/MMR, symbols, text, refinement, patterns, halftones and global dictionaries.

With Reader, install this package in the same Composer application. Reader detects a compatible native decoder first, then this optional library. If neither can handle the requested profile, it reports the capability and the Composer installation command; it never installs packages itself.

Contract

PhpDecoder selects the requested codec. Each call owns its decoding state and receives configurable DecodeLimits. A DecodedImage retains the image origin, component sampling geometry, precision, sign, colour metadata and alpha association. ComponentPlane::sample() returns the original integer sample; packed rows are MSB first with padding only at the end of each row. Signed samples use two's complement at their declared precision, including 38 bits.

The decoder does not silently reduce precision, invert CMYK samples, convert ICC colour to RGB, apply a PDF Decode array or flatten transparency. These interpretations belong to the consumer. JPEG's PDF colour-transform rules are part of the DCT codec contract and are documented separately.

The library requires 64-bit PHP 8.3 or newer. Its production code has no process, file-path, network, PDF Reader or core dependency. Native-engine discovery and native-first/PHP-fallback selection belong to the optional Reader adapter.

Resource limits and errors

Limits cover encoded bytes (including JBIG2 globals), decoded bytes, dimensions, pixels, component count, work, cumulative accounted allocation, nesting, segments, metadata and tiles. Resource bounds are application policy, not restrictions of the image formats. Allocation accounting is not a replacement for the hosting PHP process's memory limit.

• MalformedImage: the supplied image structure or coded data is invalid.
• UnsupportedFeature: the selected decoder cannot represent or process a declared mechanism.
• ResourceLimit: the configured budget is exhausted.

Do not silently retry invalid input or an exhausted budget with looser limits. Applications may select a different capable backend after an explicit unsupported-capability result.

Development

Install the locked development tools with Composer, then run composer check. Independent codec tools and reproducible source fixtures are kept under tools/ and resources/. Release qualification runs PHP 8.3, 8.4 and 8.5 and the applicable independent decoder/encoder comparisons.

Algorithms adapted from PDF.js retain their Apache-2.0 notices and exact upstream revision in each codec's provenance record. See LICENSE and the resource notices. The package is independent of the MIT-licensed PDFToolkit core.