PDF Import

Back to root overview: README.md

tc-lib-pdf can import pages from existing PDFs as Form XObjects and place them on destination pages.

Source Registration and Page Count

$sourceId = $pdf->setImportSourceFile('/path/to/source.pdf');
// or: $sourceId = $pdf->setImportSourceData($rawPdfBytes);

$count = $pdf->getSourcePageCount($sourceId);

The page count is derived from the page tree actually reachable through /Kids; the declared /Count entry of the /Pages dictionary is ignored, so a forged or wrong /Count cannot influence how many pages are counted or imported. Structurally broken page trees (missing /Kids, unexpected node types, duplicate or cyclic references) raise ImportCorruptedSourceException.

The reachable-page walk runs once per registered source: it produces a flattened page index (one effective page dictionary per page, with inherited attributes already resolved) that is cached and reused by getSourcePageCount(), importPage(), and importPages(). Importing all pages of an n-page document therefore costs a single tree walk plus one index lookup per page, instead of one full walk per page.

Import One Page and Place It

$tpl = $pdf->importPage($sourceId, 1, [
    'box' => 'CropBox',          // MediaBox|CropBox|BleedBox|TrimBox|ArtBox
    'groupXObject' => true,
    'cache' => true,
    'respectRotation' => true,
]);

$pdf->addPage();
$placed = $pdf->useImportedPage($tpl, 20, 20, 120, 80, [
    'keepAspectRatio' => true,
    'align' => 'CC',             // TL|TC|TR|CL|CC|CR|BL|BC|BR
    'clip' => true,
]);

Append Pages from a Source Document

// Append all pages.
$templates = $pdf->appendDocument($sourceId);

// Append only selected pages.
$templates = $pdf->appendDocument($sourceId, [1, 3, 5]);

// Add one imported page sized to the source page.
$tpl = $pdf->addPageFromImport($sourceId, 2);

Import Examples

• Single page import: examples/E065_import_single_page.php
• Full document append: examples/E066_import_document_append.php
• Advanced N-up composition from imported pages: examples/E067_import_page_region_nup.php

Import Limitations and Fidelity Notes

• Form and annotation semantics are not merged into editable destination structures; pages are imported as Form XObjects.
• Digital signatures in source files are not preserved as valid signatures in the destination output.
• Encrypted source PDFs are currently not importable with the bundled parser backend. Password-like options are accepted by the import API, but encrypted inputs fail with an explicit actionable exception.
• For multi-stream page contents, import normalizes by decoding and concatenating stream bytes; this can change low-level byte representation while preserving rendered appearance in typical cases.
• Transparency-group behavior is conformance-aware: when transparency is disallowed by the active PDF mode (for example PDF/X-1a or PDF/X-3), import suppresses transparency groups to remain compliant.
• Setting groupXObject to false can reduce output size, but may change compositing on source pages that rely on transparency blending.