tc-lib-pdf-parser

Parser library for reading and extracting PDF document structures.

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

---

Overview

tc-lib-pdf-parser parses raw PDF data into the cross-reference and trailer data of the document and an array of its objects, each decoded into a token array.

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

---

Features

Parsing

• Cross-reference tables and cross-reference streams, including /Prev chains and incremental updates
• Object streams (/ObjStm)
• Indirect references, resolved on demand and bounded against cycles
• Stream decoding through tc-lib-pdf-filter, including the Predictor of DecodeParms

Limits

• Maximum decoded size of a single stream
• Maximum nesting depth of arrays and dictionaries
• Maximum depth of indirect object resolutions
• Maximum number of chained cross-reference sections

---

Requirements

• PHP 8.2 or later
• Extension: pcre
• Composer

---

Configuration

The constructor accepts an array of parameters:

Parameter	Type	Default	Meaning
ignore_filter_errors	bool	false	If true, a stream that fails to decode is kept as raw data instead of raising an exception
decode_streams	bool	true	If true, decode the stream payloads of the indirect objects while parsing
max_stream_size	int	33554432	Maximum size in bytes of a single decoded stream; 0 means unlimited
max_resolution_depth	int	64	Maximum number of indirect object resolutions in flight at once; values below 1 are clamped to 1
max_nesting_depth	int	256	Maximum nesting depth of array and dictionary objects; values below 1 are clamped to 1
strict_limits	bool	false	If true, raise a LimitException as soon as a limit or a reference cycle leaves an object unresolved

---

Parsing Limits

Two limits bound the work a document can ask the parser to do. Both bound a recursion and cannot be disabled: a value below 1 is clamped to 1.

Exceeding max_nesting_depth always raises Com\Tecnick\Pdf\Parser\LimitException, a subclass of Com\Tecnick\Pdf\Parser\Exception: a dictionary or array that cannot be tokenized has no usable value to fall back to.

Reaching max_resolution_depth, or meeting a reference cycle, leaves the reference unresolved and lets the rest of the document parse. Both cases are recorded and readable after parse():

$parser = new \Com\Tecnick\Pdf\Parser\Parser();
[$xref, $objects] = $parser->parse((string) $raw);

foreach ($parser->getLimitWarnings() as $warning) {
    // "the indirect object resolution depth limit (64) left a reference
    //  unresolved 7 times, first at object 128_0"
}

One warning is reported per kind of event, with the number of occurrences and the first object affected. Setting strict_limits turns the first such event into a LimitException instead, and getLimitWarnings() then always returns an empty list.

---

Installation

composer require tecnickcom/tc-lib-pdf-parser

---

Quick Start

<?php

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

$raw = file_get_contents('/path/to/document.pdf');
$parser = new \Com\Tecnick\Pdf\Parser\Parser(['ignore_filter_errors' => true]);

// $xref holds the cross-reference and trailer data,
// $objects the parsed objects keyed as "[object number]_[generation number]"
[$xref, $objects] = $parser->parse((string) $raw);

---

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/Parser/autoload.php';

---

Contributing

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