feat: add PDF import subsystem (single page, append, n-up region)

Author: nicolaasuni

Makefile

@@ -225,9 +225,9 @@ endif
 .PHONY: lint
 lint:
 	#./vendor/bin/phpcbf --config-set ignore_non_auto_fixable_on_exit 1
-	./vendor/bin/phpcs --standard=phpcs.xml
-	./vendor/bin/phpmd src text unusedcode,naming,design --exclude vendor
-	./vendor/bin/phpmd test text unusedcode,naming,design --exclude */vendor/*
+	./vendor/bin/phpcs --standard=phpcs.xml --cache=$(TARGETDIR)/phpcs.cache
+	./vendor/bin/phpmd src text unusedcode,naming,design --exclude vendor --cache --cache-file $(TARGETDIR)/phpmd-src.cache
+	./vendor/bin/phpmd test text unusedcode,naming,design --exclude */vendor/* --cache --cache-file $(TARGETDIR)/phpmd-test.cache
 	php -r 'exit((int)version_compare(PHP_MAJOR_VERSION, "7", ">"));' || ./vendor/phpstan.phar analyse
 
 ## Run all tests and reports

README.md

@@ -24,6 +24,7 @@ If this project is useful to you, please consider [supporting development via Gi
 - [Installation](#installation)
 - [Font Setup](#font-setup)
 - [Quick Start](#quick-start)
+- [PDF Import](#pdf-import)
 - [Remote Resources and fileOptions](#remote-resources-and-fileoptions)
 - [Digital Signatures](#digital-signatures)
 - [PDF/X Conformance](#pdfx-conformance)
@@ -124,6 +125,12 @@ The fastest way to evaluate the library is to follow the installation and font s
 - **PDF/X** (generic alias, PDF/X-1a, PDF/X-3, PDF/X-4, PDF/X-5) — print-exchange conformance: per-variant OutputIntent identifiers, GTS_PDFXVersion in Info dict and XMP, PDF version enforcement, CMYK color forcing for restrictive profiles (X-1a, X-3), transparency restrictions, and suppression of encryption and JavaScript
 - **PDF/UA** (generic alias, PDF/UA-1, PDF/UA-2) — accessibility conformance: tagged structure tree (`StructTreeRoot` / `ParentTree`), `MarkInfo /Marked true`, document language (`/Lang`), `DisplayDocTitle true`, `ActualText` for ligatures and special glyphs, figure alt-text tagging, and heading-level clamping to prevent skipped levels; PDF/UA-2 targets PDF 2.0
 
+### PDF Import
+- Import pages from existing PDFs as **Form XObjects** and place them on any destination page
+- Import a single page at a user-defined position and scale (`importPage` / `useImportedPage`)
+- Append full documents page-by-page, auto-sized to the source page dimensions (`addPageFromImport`)
+- Load source PDFs from a file path or raw byte string (`setImportSourceFile` / `setImportSourceData`)
+
 ### Other
 - **1D and 2D barcodes** via [`tc-lib-barcode`](https://github.com/tecnickcom/tc-lib-barcode)
 - Interactive AcroForm fields (buttons, checkboxes, radio buttons, text, combo boxes, list boxes)
@@ -277,6 +284,78 @@ If the minimal example fails on first run, verify these two points first:
 
 ---
 
+## PDF Import
+
+`tc-lib-pdf` can import pages from existing PDFs as Form XObjects and place them on destination pages.
+
+### Source registration and page count
+
+```php
+$sourceId = $pdf->setImportSourceFile('/path/to/source.pdf');
+// or: $sourceId = $pdf->setImportSourceData($rawPdfBytes);
+
+$count = $pdf->getSourcePageCount($sourceId);
+```
+
+### Import one page and place it
+
+```php
+$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
+
+```php
+// 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](examples/E065_import_single_page.php)
+- Full document append: [examples/E066_import_document_append.php](examples/E066_import_document_append.php)
+- Advanced N-up composition from imported pages: [examples/E067_import_page_region_nup.php](examples/E067_import_page_region_nup.php)
+
+### Migrating from FPDI-style workflows
+
+If you are migrating legacy FPDI-like code paths, map concepts to the native API as follows:
+
+- `setSourceFile()` -> `setImportSourceFile()` + `getSourcePageCount()`
+- `importPage()` -> `importPage()` (returns a typed `PageTemplate` value object)
+- `useTemplate()` -> `useImportedPage()`
+- manual page-loop append flows -> `appendDocument()`
+
+Unlike FPDI numeric template IDs, `tc-lib-pdf` returns typed `PageTemplate` objects and keeps import behavior inside the same library stack (`tc-lib-*`) without external importer dependencies.
+
+### 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.
+
+---
+
 ## Remote Resources and `fileOptions`
 
 By default `tc-lib-pdf` **does not fetch any remote URLs**. Images, fonts, and SVG files referenced by HTTP or HTTPS are blocked unless you explicitly allow the originating hosts. Local file paths are never restricted.

VERSION

@@ -1 +1 @@
-8.11.3
+8.12.0

composer.json

@@ -37,7 +37,8 @@
     "tecnickcom/tc-lib-unicode-data": "^2.0",
     "tecnickcom/tc-lib-unicode": "^2.1",
     "tecnickcom/tc-lib-pdf-page": "^4.3",
-    "tecnickcom/tc-lib-pdf-graph": "^2.4"
+    "tecnickcom/tc-lib-pdf-graph": "^2.4",
+    "tecnickcom/tc-lib-pdf-parser": "*"
   },
   "minimum-stability": "dev",
   "prefer-stable": true,

examples/E000_overview.php

@@ -166,7 +166,7 @@
 );
 
 $pdf->page->addContent($bodyFont['out']);
-$features = '<ul style="font-size:10pt; line-height:1.35; color:rgb(22,37,61); margin:0; padding-left:12pt;">'
+$features = '<ul style="font-size:10pt; color:rgb(22,37,61); margin:0; padding-left:12pt;">'
     . '<li>Native SVG rendering</li>'
     . '<li>JPEG/PNG with transparency</li>'
     . '<li>1D/2D barcodes (QR, DataMatrix)</li>'

examples/E065_import_single_page.php

@@ -0,0 +1,67 @@
+<?php
+/**
+ * E065_import_single_page.php
+ *
+ * @since       2026-05-03
+ * @category    Library
+ * @package     Pdf
+ * @author      Nicola Asuni <info@tecnick.com>
+ * @copyright   2002-2026 Nicola Asuni - Tecnick.com LTD
+ * @license     https://www.gnu.org/copyleft/lesser.html GNU-LGPL v3 (see LICENSE.TXT)
+ * @link        https://github.com/tecnickcom/tc-lib-pdf
+ *
+ * This file is part of tc-lib-pdf software library.
+ */
+
+// NOTE: run make deps fonts in the project root to generate the dependencies and example fonts.
+
+// autoloader when using Composer
+require(__DIR__ . '/../vendor/autoload.php');
+
+// define fonts directory
+\define('K_PATH_FONTS', \realpath(__DIR__ . '/../vendor/tecnickcom/tc-lib-pdf-font/target/fonts'));
+
+// ---- Step 1: create a source PDF to import from ----
+
+$src = new \Com\Tecnick\Pdf\Tcpdf();
+$bfont = $src->font->insert($src->pon, 'helvetica', '', 14);
+
+$srcPage = $src->addPage();
+$src->page->addContent($bfont['out']);
+$src->addHTMLCell('<h1>Source document</h1><p>This page will be imported.</p>', 15, 20, 160);
+
+$sourcePdfData = $src->getOutPDFString();
+
+// ---- Step 2: create a new document and import the source page ----
+
+$pdf = new \Com\Tecnick\Pdf\Tcpdf();
+$bfont = $pdf->font->insert($pdf->pon, 'helvetica', '', 12);
+
+// Register the source document from its raw bytes.
+$sourceId = $pdf->setImportSourceData($sourcePdfData);
+
+// Count pages available in the source.
+$pageCount = $pdf->getSourcePageCount($sourceId);
+
+// Import page 1 as a reusable Form XObject template.
+$tpl = $pdf->importPage($sourceId, 1);
+
+// Add a new page to the destination document.
+$page = $pdf->addPage();
+$pdf->page->addContent($bfont['out']);
+
+// Place the imported page as a thumbnail (100 mm wide) at (20, 20).
+// The height is computed automatically to preserve the aspect ratio.
+$placed = $pdf->useImportedPage($tpl, 20, 20, 140);
+
+// Add an annotation below the imported page.
+$pdf->addHTMLCell(
+    '<p>Imported ' . $pageCount . ' page(s). Placed page 1 above (scaled).</p>',
+    15,
+    (float) $placed['y'] + (float) $placed['height'] + 5,
+    160
+);
+
+// Get and render the PDF content.
+$rawpdf = $pdf->getOutPDFString();
+$pdf->renderPDF($rawpdf);

examples/E066_import_document_append.php

@@ -0,0 +1,81 @@
+<?php
+/**
+ * E066_import_document_append.php
+ *
+ * @since       2026-05-03
+ * @category    Library
+ * @package     Pdf
+ * @author      Nicola Asuni <info@tecnick.com>
+ * @copyright   2002-2026 Nicola Asuni - Tecnick.com LTD
+ * @license     https://www.gnu.org/copyleft/lesser.html GNU-LGPL v3 (see LICENSE.TXT)
+ * @link        https://github.com/tecnickcom/tc-lib-pdf
+ *
+ * This file is part of tc-lib-pdf software library.
+ */
+
+// NOTE: run make deps fonts in the project root to generate the dependencies and example fonts.
+
+// autoloader when using Composer
+require(__DIR__ . '/../vendor/autoload.php');
+
+// define fonts directory
+\define('K_PATH_FONTS', \realpath(__DIR__ . '/../vendor/tecnickcom/tc-lib-pdf-font/target/fonts'));
+
+// ---- Step 1: build a multi-page source PDF ----
+
+$src = new \Com\Tecnick\Pdf\Tcpdf();
+$bfont = $src->font->insert($src->pon, 'helvetica', '', 14);
+
+$pages = ['First page', 'Second page', 'Third page'];
+foreach ($pages as $idx => $label) {
+    $srcPage = $src->addPage();
+    $src->page->addContent($bfont['out']);
+    $src->addHTMLCell(
+        '<h2>Source: ' . \htmlspecialchars($label) . '</h2>'
+        . '<p>Page ' . ($idx + 1) . ' of ' . \count($pages) . ' in the source document.</p>',
+        15,
+        20,
+        160
+    );
+}
+
+$sourcePdfData = $src->getOutPDFString();
+
+// ---- Step 2: create destination document with an intro page ----
+
+$pdf = new \Com\Tecnick\Pdf\Tcpdf();
+$bfont = $pdf->font->insert($pdf->pon, 'helvetica', '', 12);
+
+$pdf->addPage();
+$pdf->page->addContent($bfont['out']);
+$pdf->addHTMLCell(
+    '<h1>Document append demo</h1>'
+    . '<p>The following pages are imported from a separate source document.</p>',
+    15,
+    20,
+    160
+);
+
+// ---- Step 3: register source and append all its pages ----
+
+$sourceId = $pdf->setImportSourceData($sourcePdfData);
+$pageCount = $pdf->getSourcePageCount($sourceId);
+
+// appendDocument adds one new destination page per source page and places the template.
+$templates = $pdf->appendDocument($sourceId);
+
+// ---- Step 4: add a closing page with a summary ----
+
+$pdf->addPage();
+$pdf->page->addContent($bfont['out']);
+$pdf->addHTMLCell(
+    '<p>Appended ' . \count($templates) . ' page(s) from source ('
+    . $pageCount . ' available).</p>',
+    15,
+    20,
+    160
+);
+
+// Render
+$rawpdf = $pdf->getOutPDFString();
+$pdf->renderPDF($rawpdf);