Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion docs/en/CONFORMANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ summary page.
| Check | Standard | Tool | References |
|---|---|---|---|
| PDF/A validation | ISO 19005 | [veraPDF](https://verapdf.org) — the industry-standard open-source validator | PDF/A-1b, 1a, 2b, 2u, 3b, and a signed PDF/A-2b with a signature stamp |
| PDF/UA validation | ISO 14289-1 | veraPDF, PDF/UA-1 profile (its machine-checkable rules) | a tagged PDF/UA-1 document built on the low-level writer (headings, a link in its Link element, a table with header scope, artifacts), and the same document as PDF/A-2u + PDF/UA-1, checked against both |
| PDF/X structure | ISO 15930 | Ghostscript render (`-dPDFSTOPONERROR`) + byte-level assertions (OutputIntent `/GTS_PDFX`, CMYK profile and RGB-operator ban for X-1a, Info keys, trailer `/ID`, TrimBox/ArtBox per page, no encryption) | PDF/X-1a, X-3, X-4 |
| Visual regression | — | poppler `pdftoppm` render diffed against committed golden PNGs (ImageMagick, 5% fuzz, ≤0.5% differing pixels) | reference pages, form fill, signature stamps |
| Signatures | ETSI EN 319 142 (PAdES), RFC 5652, RFC 3161 | OpenSSL CLI: `openssl cms -verify` over the exact `/ByteRange` bytes up to a test root CA, `openssl ts -verify` for timestamps; tampering must break verification. [pyHanko](https://github.com/MatthiasValvekens/pyHanko) validates the signed PDFs as a whole (trust, timestamp, whole-file coverage) | test suite (`Signature*Test`, `PadesSignatureTest`, `CmsBuilderTest`) |
Expand All @@ -35,7 +36,7 @@ with the sRGB2014 ICC profile vendored in
bash scripts/fetch-fonts.sh
php scripts/conformance/generate.php

# PDF/A — requires veraPDF (https://verapdf.org, or `brew install verapdf`)
# PDF/A and PDF/UA — requires veraPDF (https://verapdf.org, or `brew install verapdf`)
bash scripts/conformance/verapdf.sh

# PDF/X — requires Ghostscript
Expand All @@ -59,6 +60,12 @@ vendor/bin/phpunit tests/Pdf/SignatureOpenSslTest.php
not sufficient, conditions.
- veraPDF emits "Nested MCID" *warnings* (not violations) for tagged
documents; tightening the tagged emission is tracked as future work.
- **PDF/UA** has rules no validator can check — that alternate text
describes the image, that the reading order makes sense, that the tags
match what the content is. veraPDF checks the machine-checkable ones;
the rest needs a person with a screen reader (or the PAC/Matterhorn
human checks). `enablePdfUa()` writes the identification and metadata;
tagging the content correctly is the caller's job.
- Signature verification by the OpenSSL CLI proves cryptographic
correctness over `/ByteRange`; the Acrobat signature panel is verified
manually as part of the [viewer matrix](VIEWER-MATRIX.md).
123 changes: 122 additions & 1 deletion scripts/conformance/generate.php
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@
* Usage: php scripts/conformance/generate.php [output-dir]
*
* Output: one PDF per flavour (pdfa-1b, pdfa-1a, pdfa-2b, pdfa-2u, pdfa-3b,
* plus pdfa-2b-signed — signed, with a signature stamp), built with embedded
* plus pdfa-2b-signed — signed, with a signature stamp — and pdfa-1b-annotated /
* pdfa-2b-annotated — links and a full /Info dictionary), built with embedded
* Liberation fonts (run scripts/fetch-fonts.sh first), plus pdfa-1b-cff,
* pdfa-2u-cff and pdfa-2u-cff-cid — CFF-outline OpenType fonts (Source Sans 3
* and the CID-keyed test font in tests/fixtures/fonts) — and the vendored sRGB
Expand All @@ -18,8 +19,10 @@
*/

use Dskripchenko\PhpPdf\Document;
use Dskripchenko\PhpPdf\Element\Bookmark;
use Dskripchenko\PhpPdf\Element\Cell;
use Dskripchenko\PhpPdf\Element\Heading;
use Dskripchenko\PhpPdf\Element\Hyperlink;
use Dskripchenko\PhpPdf\Element\Paragraph;
use Dskripchenko\PhpPdf\Element\Row;
use Dskripchenko\PhpPdf\Element\Run;
Expand Down Expand Up @@ -171,6 +174,37 @@
$failures += $ok ? 0 : 1;
}

// Links and a full /Info dictionary: link annotations need the Print flag,
// and every /Info entry has to match its XMP property.
$annotated = new Section([
new Heading(1, [new Run('Annotated Reference Document')]),
new Paragraph([
new Run('An external link to '),
Hyperlink::external('https://www.pdfa.org/', [new Run('the PDF Association')]),
new Run(', and an internal link to '),
Hyperlink::internal('tables', [new Run('the table below')]),
new Run('.'),
]),
new Heading(2, [new Bookmark('tables', [new Run('Tabular data')])]),
new Paragraph([new Run('The link above jumps here.')]),
]);
foreach (['pdfa-1b-annotated' => PdfAConfig::PART_1, 'pdfa-2b-annotated' => PdfAConfig::PART_2] as $name => $part) {
$ok = $emit($name, new Document(
$annotated,
metadata: [
'Title' => 'php-pdf conformance reference — '.strtoupper($name),
'Author' => 'dskripchenko/php-pdf',
'Subject' => 'Links and document information',
'Keywords' => 'PDF/A, links, metadata',
'Creator' => 'scripts/conformance/generate.php',
'Producer' => 'dskripchenko/php-pdf conformance',
],
lang: 'en',
pdfA: new PdfAConfig($iccPath, iccProfileName: 'sRGB2014', lang: 'en', part: $part),
));
$failures += $ok ? 0 : 1;
}

// CFF-outline OpenType fonts: CIDFontType0 + FontFile3/CIDFontType0C. PDF/A-1
// is the strictest case (PDF 1.4 base), the CID-keyed font checks that CIDs
// are written through the CFF charset.
Expand Down Expand Up @@ -327,4 +361,91 @@
signature: $signature,
)) ? 0 : 1;

// PDF/UA-1: a tagged document built on the low-level writer, as a layout
// engine on top of php-pdf would — headings, a paragraph with a link held
// in its Link element, a table whose header cells have a scope, and a
// running footer marked as an artifact. pdfua-1 is PDF/UA alone;
// pdfa-2u-ua1 is the same document as PDF/A-2u too, checked against both.
$pdfUaReference = function (?PdfAConfig $pdfA) use ($fontDir): PdfDocument {
$regular = new PdfFont(TtfFile::fromFile($fontDir.'/LiberationSans-Regular.ttf'));
$bold = new PdfFont(TtfFile::fromFile($fontDir.'/LiberationSans-Bold.ttf'));
$pdf = PdfDocument::new();
if ($pdfA !== null) {
$pdf->enablePdfA($pdfA);
}
$pdf->enablePdfUa();
$pdf->setLang('en');
$pdf->metadata(
title: 'php-pdf conformance reference — PDF/UA-1',
author: 'dskripchenko/php-pdf',
creationDate: new DateTimeImmutable('2026-01-01 00:00:00', new DateTimeZone('UTC')),
);
$page = $pdf->addPage();
$leaf = function (string $type, \Closure $draw, array $attributes = []) use ($pdf, $page): void {
$mcid = $page->nextMcid();
$pdf->addStructElement($type, $mcid, $page, attributes: $attributes);
$page->beginMarkedContent($type, $mcid);
$draw();
$page->endMarkedContent();
};

$pdf->beginStructContainer('Document', $page);
$leaf('H1', fn () => $page->showEmbeddedText('Accessible Reference Document', 72, 760, $bold, 20));
$leaf('P', fn () => $page->showEmbeddedText('Every piece of content here is tagged, and the footer is an artifact.', 72, 730, $regular, 11));

$pdf->beginStructContainer('P', $page);
$leaf('Span', fn () => $page->showEmbeddedText('Read more at ', 72, 710, $regular, 11));
$pdf->beginStructContainer('Link', $page);
$leaf('Span', fn () => $page->showEmbeddedText('the PDF Association', 140, 710, $regular, 11, 0.1, 0.2, 0.6));
$page->addExternalLink(140, 706, 104, 14, 'https://pdfa.org/', 'The PDF Association website');
$pdf->placeLinkInStructure($page);
$pdf->endStructContainer();
$leaf('Span', fn () => $page->showEmbeddedText('.', 244, 710, $regular, 11));
$pdf->endStructContainer();

$leaf('H2', fn () => $page->showEmbeddedText('Standards', 72, 670, $bold, 14));
$rows = [['Standard', 'Number'], ['PDF/A-2', 'ISO 19005-2'], ['PDF/UA-1', 'ISO 14289-1']];
$pdf->beginStructContainer('Table', $page);
foreach ($rows as $r => $cells) {
$y = 645 - $r * 20;
$pdf->beginStructContainer('TR', $page);
foreach ($cells as $c => $text) {
$header = $r === 0;
$leaf(
$header ? 'TH' : 'TD',
fn () => $page->showEmbeddedText($text, 72 + $c * 150, $y, $header ? $bold : $regular, 11),
$header ? ['O' => 'Table', 'Scope' => 'Column'] : [],
);
}
$pdf->endStructContainer();
$page->beginArtifact('Layout');
$page->strokeLine(72, $y - 6, 372, $y - 6, 0.5, 0.6, 0.6, 0.6);
$page->endMarkedContent();
}
$pdf->endStructContainer();
$pdf->endStructContainer();

$page->beginArtifact('Pagination');
$page->showEmbeddedText('Page 1', 72, 40, $regular, 9);
$page->endMarkedContent();

return $pdf;
};
foreach (['pdfua-1' => null, 'pdfa-2u-ua1' => new PdfAConfig(
$iccPath,
iccProfileName: 'sRGB2014',
lang: 'en',
part: PdfAConfig::PART_2,
conformance: PdfAConfig::CONFORMANCE_U,
)] as $name => $pdfA) {
$path = $outDir.'/'.$name.'.pdf';
try {
file_put_contents($path, $pdfUaReference($pdfA)->toBytes());
echo "generated $path\n";
} catch (\Throwable $e) {
fwrite(STDERR, "FAILED $name: {$e->getMessage()}\n");
$failures++;
}
}

exit($failures > 0 ? 1 : 0);
25 changes: 15 additions & 10 deletions scripts/conformance/verapdf.sh
Original file line number Diff line number Diff line change
@@ -1,36 +1,41 @@
#!/usr/bin/env bash
# Validate the reference PDF/A documents with veraPDF.
# Validate the reference PDF/A and PDF/UA documents with veraPDF.
#
# Usage: scripts/conformance/verapdf.sh [dir]
# dir — directory with the generated references (default build/conformance)
#
# Env: VERAPDF — path to the veraPDF CLI (default: `verapdf` on PATH).
#
# Writes per-file JSON reports (<name>.verapdf.json) and a summary.md table
# Writes per-file JSON reports (<name>.<flavour>.verapdf.json) and a summary.md table
# into the same directory. Exits non-zero if any document is non-compliant.
set -euo pipefail

DIR="${1:-build/conformance}"
VERAPDF="${VERAPDF:-verapdf}"

NAMES=(pdfa-1b pdfa-1a pdfa-2b pdfa-2u pdfa-3b pdfa-2b-signed pdfa-1b-cff pdfa-2u-cff pdfa-2u-cff-cid)
# pdfa-2b-signed → 2b
flavour() { local f="${1#pdfa-}"; echo "${f%%-*}"; }
# name, or name:flavour when the flavour isn't the part after "pdfa-"
# (pdfa-2b-signed → 2b). pdfa-2u-ua1 is checked as PDF/A-2u and as PDF/UA-1.
NAMES=(pdfa-1b pdfa-1a pdfa-2b pdfa-2u pdfa-3b pdfa-2b-signed pdfa-1b-annotated pdfa-2b-annotated pdfa-1b-cff pdfa-2u-cff pdfa-2u-cff-cid pdfua-1:ua1 pdfa-2u-ua1 pdfa-2u-ua1:ua1)
flavour() {
if [[ "$1" == *:* ]]; then echo "${1#*:}"; return; fi
local f="${1#pdfa-}"; echo "${f%%-*}"
}

version="$("$VERAPDF" --version 2>/dev/null | head -1 || echo 'veraPDF')"
summary="$DIR/summary.md"
{
echo "## PDF/A conformance — $version"
echo "## PDF/A and PDF/UA conformance — $version"
echo
echo "| Document | Flavour | Compliant | Failed rules |"
echo "|---|---|---|---|"
} > "$summary"

fail=0
for name in "${NAMES[@]}"; do
fl="$(flavour "$name")"
for entry in "${NAMES[@]}"; do
fl="$(flavour "$entry")"
name="${entry%%:*}"
pdf="$DIR/$name.pdf"
json="$DIR/$name.verapdf.json"
json="$DIR/$name.$fl.verapdf.json"

if [[ ! -f "$pdf" ]]; then
echo "MISSING $pdf" >&2
Expand All @@ -40,7 +45,7 @@ for name in "${NAMES[@]}"; do
fi

# veraPDF exits non-zero for non-compliant files — capture, don't abort.
"$VERAPDF" -f "$fl" --format json "$pdf" > "$json" 2> "$DIR/$name.verapdf.log" || true
"$VERAPDF" -f "$fl" --format json "$pdf" > "$json" 2> "$DIR/$name.$fl.verapdf.log" || true

read -r compliant failed_rules < <(python3 - "$json" <<'PY'
import json, sys
Expand Down
Loading
Loading