added PDF/A documentation and extra notes

Co-authored-by: Copilot <copilot@github.com>

Author: nicolaasuni

README.md

@@ -27,6 +27,7 @@ If this project is useful to you, please consider [supporting development via Gi
 - [PDF Import](#pdf-import)
 - [Remote Resources and fileOptions](#remote-resources-and-fileoptions)
 - [Digital Signatures](#digital-signatures)
+- [PDF/A Archival](#pdfa-archival)
 - [PDF/X Conformance](#pdfx-conformance)
 - [PDF/UA Accessibility](#pdfua-accessibility)
 - [Development](#development)
@@ -121,7 +122,7 @@ The fastest way to evaluate the library is to follow the installation and font s
   - each feature (OCSP, CRL, cert embedding, DSS, VRI) can be enabled independently via `setSignature()` LTV options
 - **PDF annotations**: links, text notes, file attachments, markup, shapes, media, and widgets
 - **JavaScript** embedding
-- **PDF/A** (1/2/3, including a/b/u conformance levels) — see [Factur-X / ZUGFeRD](#other) below
+- **PDF/A** (1/2/3, including a/b/u conformance levels) — see [PDF/A Archival](#pdfa-archival) section and [E001_invoice.php](examples/E001_invoice.php) for a Factur-X / ZUGFeRD example
 - **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
 
@@ -210,6 +211,14 @@ composer update
 composer require ...
 ```
 
+To also cover `composer dump-autoload` (used in many CI pipelines), add the hook to `post-autoload-dump` as well:
+
+```json
+"post-autoload-dump": [
+    "@tc-lib-pdf-fonts"
+]
+```
+
 If you prefer to generate fonts manually, run the build in the `tc-lib-pdf-font` package:
 
 ```bash
@@ -256,7 +265,12 @@ $pdf->page->addContent($bfont['out']);
 
 $html = '<h1>Hello, PDF!</h1><p>Generated with tc-lib-pdf.</p>';
 
-$pdf->addHTMLCell($html, 15, 20, 180);
+$pdf->addHTMLCell(
+    html:   $html,
+    posx:   15,   // mm from left page edge
+    posy:   20,   // mm from top page edge
+    width:  180,  // mm wide (0 = to right margin)
+);
 
 $rawpdf = $pdf->getOutPDFString();
 
@@ -265,6 +279,8 @@ $pdf->renderPDF($rawpdf);
 
 `getOutPDFString()` returns the raw PDF bytes. `renderPDF()` streams those bytes to the browser; if you need file storage or an email attachment, keep the returned string and write or hand it off yourself.
 
+> **Note:** `realpath()` returns `false` when the fonts directory does not yet exist. If you see `K_PATH_FONTS` errors on first run, verify that fonts were generated after `composer install` (see [Font Setup](#font-setup)).
+
 For more complete examples — including invoices, images, barcodes, HTML tables, dedicated HTML selector/form/table showcases, PDF/X, and PDF/UA — see the [examples](examples) directory.
 Annotation-focused runnable example: [examples/E027_annotations.php](examples/E027_annotations.php).
 
@@ -334,17 +350,6 @@ $tpl = $pdf->addPageFromImport($sourceId, 2);
 - 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.
@@ -486,19 +491,57 @@ openssl pkcs12 -export -in tcpdf.crt -inkey tcpdf.key -out tcpdf.p12
 
 ---
 
+## PDF/A Archival
+
+`tc-lib-pdf` supports PDF/A output for long-term archival workflows (ISO 19005). Pass the mode string as the `mode` argument to the `Tcpdf` constructor:
+
+```php
+// PDF/A-1b (default conformance level when suffix is omitted)
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfa1');
+
+// Explicit conformance levels
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfa1a');  // PDF/A-1a
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfa1b');  // PDF/A-1b
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfa2a');  // PDF/A-2a
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfa2b');  // PDF/A-2b
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfa2u');  // PDF/A-2u
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfa3a');  // PDF/A-3a
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfa3b');  // PDF/A-3b
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfa3u');  // PDF/A-3u
+```
+
+| Mode suffix | Conformance | Unicode ToUnicode | Tagged structure |
+|-------------|-------------|-------------------|------------------|
+| `a` | Level A | required | required |
+| `b` | Level B | required | not required |
+| `u` | Level U (parts 2/3 only) | required | not required |
+
+PDF/A-3 supports embedding arbitrary file attachments (for example XML invoice payloads). This is the basis for **Factur-X / ZUGFeRD** workflows — embed the structured XML in a PDF/A-3 document and register the relationship via XMP metadata:
+
+```php
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfa3');
+// ... build document ...
+$pdf->Annotation(/* file attachment annotation pointing to the XML */);
+$pdf->setCustomXMP('x:xmpmeta.rdf:RDF.rdf:Description.pdfaExtension:schemas.rdf:Bag', $xmpBag);
+```
+
+Runnable example (invoice with embedded Factur-X XML): [examples/E001_invoice.php](examples/E001_invoice.php).
+
+---
+
 ## PDF/X Conformance
 
-`tc-lib-pdf` supports multiple PDF/X profiles for print-exchange workflows. Pass the mode string as the fifth argument to the `Tcpdf` constructor:
+`tc-lib-pdf` supports multiple PDF/X profiles for print-exchange workflows. Pass the mode string as the `mode` argument to the `Tcpdf` constructor:
 
 ```php
 // Generic PDF/X alias (maps to the library's baseline print-exchange workflow)
-$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfx');
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfx');
 
 // Specific variants
-$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfx1a'); // PDF/X-1a:2003
-$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfx3');  // PDF/X-3:2003
-$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfx4');  // PDF/X-4:2010
-$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfx5');  // PDF/X-5g:2010
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfx1a'); // PDF/X-1a:2003
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfx3');  // PDF/X-3:2003
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfx4');  // PDF/X-4:2010
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfx5');  // PDF/X-5g:2010
 ```
 
 Each variant automatically applies the appropriate conformance constraints:
@@ -518,15 +561,15 @@ Runnable examples: [examples/E010_pdfx.php](examples/E010_pdfx.php) through [exa
 
 ## PDF/UA Accessibility
 
-`tc-lib-pdf` supports tagged PDF output conforming to PDF/UA (ISO 14289). Pass the mode string as the fifth argument to the `Tcpdf` constructor:
+`tc-lib-pdf` supports tagged PDF output conforming to PDF/UA (ISO 14289). Pass the mode string as the `mode` argument to the `Tcpdf` constructor:
 
 ```php
 // Generic PDF/UA alias
-$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfua');
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfua');
 
 // Specific parts
-$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfua1'); // PDF/UA-1 (PDF 1.7)
-$pdf = new \Com\Tecnick\Pdf\Tcpdf('mm', true, false, true, 'pdfua2'); // PDF/UA-2 (PDF 2.0)
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfua1'); // PDF/UA-1 (PDF 1.7)
+$pdf = new \Com\Tecnick\Pdf\Tcpdf(mode: 'pdfua2'); // PDF/UA-2 (PDF 2.0)
 ```
 
 When a PDF/UA mode is active the library automatically:

VERSION

@@ -1 +1 @@
-8.12.0
+8.12.1

src/Base.php

@@ -190,7 +190,7 @@ abstract class Base
     /**
      * TCPDF version.
      */
-    protected string $version = '8.12.0';
+    protected string $version = '8.12.1';
 
     /**
      * Time is seconds since EPOCH when the document was created.