README

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.

tecnickcom / tc-lib-pdf-parser

Package info

Security

Fund package maintenance!

Statistics