PHP cookbook

This index lists the PHP-native NextPDF recipes: task-focused, runnable pages written directly against the core PHP API. The nextpdf core repository owns and verifies each recipe under docs/public/cookbook/php/. Each recipe has an examples/*.php script and a tests/Cookbook/Php/ harness test. The aggregator then pulls each page into this site and keeps its source provenance.

Because this page is an index, it does not make behavioral claims about any recipe. Each row records the recipe’s intent, the core module it uses, and its declared reproducibility profile. The profile and any conformance claim belong on the recipe page itself. They come from that page’s front-matter and its in-repo test, not from this index. For the integration (framework / renderer / service) cookbook, see Integration cookbook. For the contract every runnable recipe follows, see Recipe conventions.

How recipe slugs are organized

Every recipe is authored in the core repository under docs/public/cookbook/php/ and published into this site by the aggregator. Each slug follows one convention: a single segment.

/cookbook/php/<recipe>/

<recipe> names the recipe’s intent in kebab-case (for example render-html-to-pdf, not the module name html). It is lowercase, hyphen-separated, has no version numbers, and ends in one trailing slash.

Reproducibility profile, in one line

Each recipe declares the strictest profile it can honestly satisfy:

bitwise — byte-identical across runs (plain deterministic content with all entropy pinned).
structural — identical after normalising volatile atoms (the trailer /ID, creation/modification dates, font-subset prefixes — in practice, every multi-object PDF).
semantic — structural-AST plus metadata equivalence only (signed or timestamped output, or output whose equivalence is inherently non-byte-stable).

The recipe page proves the profile with its harness test. This index only reports the value that page declares.

Foundations

Build, paginate, and style a document.

Recipe	What it does	Module	Profile
`render-html-to-pdf`	Render an HTML document to PDF	Html	structural
`style-with-css`	Apply CSS to an HTML render	Html	structural
`html-table-layout`	Lay out an HTML table	Html	structural
`paginate-long-html`	Paginate a long HTML document	Html	structural
`paginate-large-html-tables`	Paginate a large HTML table across pages	Html	structural
`render-rtl-arabic-html`	Render right-to-left Arabic HTML	Html	structural
`compose-text-and-fonts`	Compose text with typography control	Typography	structural
`embed-and-subset-fonts`	Embed and subset fonts	Font	structural
`cjk-vertical-writing`	Set CJK text in vertical writing mode	Typography	structural
`multi-page-document`	Build a multi-page document	Document	structural
`headers-and-footers`	Add running headers and footers	Layout	structural

Graphics and content

Work with vectors, images, layers, and coordinate space.

Recipe	What it does	Module	Profile
`draw-vector-graphics`	Draw vector graphics	Graphics	structural
`gradients-and-transparency`	Apply gradients and transparency	Graphics	structural
`embed-images`	Embed raster images	Content	structural
`add-watermarks-and-backgrounds`	Add text and image watermarks or backgrounds to pages	Content	structural
`cmyk-spot-color-and-icc-profiles`	Produce print-ready CMYK and spot color	Color	structural
`embed-file-attachments`	Embed files and create PDF portfolios	Content	structural
`optional-content-layers`	Use optional content (layers)	Graphics	structural
`transform-coordinate-space`	Transform the coordinate space	Graphics	structural

Add bookmarks, links, annotations, and AcroForm fields.

Recipe	What it does	Module	Profile
`bookmarks-and-toc`	Build bookmarks and a table of contents	Navigation	structural
`generate-dynamic-table-of-contents`	Generate a dynamic table of contents	Navigation	structural
`links-and-annotations`	Add links and annotations	Navigation	structural
`generate-barcodes`	Generate barcodes	Barcode	bitwise
`gs1-composite-barcodes`	Generate GS1 Composite barcodes (CC-C carrier)	Barcode	structural
`fill-pdf-form`	Fill an AcroForm	Form	structural
`flatten-form-fields`	Flatten form fields	Form	structural
`form-field-validation-and-flatten-with-state`	Validate form fields and flatten with state	Form	structural

Document information

Set metadata and viewer behavior.

Recipe	What it does	Module	Profile
`set-document-metadata`	Set document metadata	Metadata	structural
`set-viewer-preferences`	Set viewer preferences	Document	structural

Document operations

Assemble, split, and optimize existing documents.

Recipe	What it does	Module	Profile
`merge-external-pdfs`	Merge external PDFs or append pages	Document	structural
`split-and-extract-pages`	Split a PDF and extract page ranges	Document	structural
`optimize-pdf-file-size`	Reduce PDF file size with compression and subsetting	Document	structural

Security, signature, and conformance

Use encryption, signing, accessibility, and profile output. These recipes keep the support≠conformance and presence≠validity boundaries on the recipe page.

Recipe	What it does	Module	Profile
`encrypt-aes256`	Encrypt with AES-256 and set permission flags	Security	structural
`encrypt-with-permissions`	Encrypt with permission flags	Security	structural
`sign-pades-b-b`	Apply a PAdES signature (B-B and B-T)	Security	semantic
`inspect-existing-signature`	Inspect an existing signature	Inspect	semantic
`tagged-pdf-ua2`	Emit tagged structure for PDF/UA-2	Accessibility	semantic
`accessible-pdfua2-from-html`	Emit the tagged structure for accessible PDF/UA-2 authoring from HTML	Accessibility	semantic
`pdf-a-4-output`	Produce PDF/A-4 output	Conformance	semantic
`pdfa4-conformance-gate`	Produce PDF/A-4 output and gate on an external validator	Conformance	semantic
`validate-conformance`	Validate against a conformance profile	Compliance	semantic

Inspection and extraction

Read content and structure back out of a PDF.

Recipe	What it does	Module	Profile
`extract-text-content`	Extract text content	Text	semantic
`multilingual-copy-paste-extraction`	Make CJK and Arabic PDFs copy-paste correct	Text	structural
`parse-and-inspect-pdf`	Parse and inspect a PDF	Inspect	semantic
`inspect-layout-boxes`	Inspect layout boxes	Inspect	semantic

Cross-cutting

Use patterns that span several modules.

Recipe	What it does	Spans	Profile
`worker-safe-batch-rendering`	Render safely in a long-running worker (shared registries, bounded memory)	Core · Performance · Support	semantic
`streaming-and-memory`	Profile streaming and memory usage	Performance	bitwise
`exception-aware-error-handling`	Handle errors with the NextPDF exception hierarchy	Exception · Contracts	structural
`custom-error-recovery-patterns`	Implement custom error recovery and retry strategies	Exception	semantic
`observe-with-opentelemetry`	Observe rendering with OpenTelemetry	Observability · Telemetry · Event	semantic

Every recipe above is published with a backing examples/*.php script and a tests/Cookbook/Php/ harness test in the core repository. When a new recipe is authored upstream, it appears here once its example and test land.