PHP cookbook
PHP cookbook
Section titled “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 a recipe link resolves
Section titled “How a recipe link resolves”Every [[…]] below is a forward reference to a page authored in the core
repository under docs/public/cookbook/php/. The aggregator then pulls that
page into this site. 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. Until
a target page aggregates, its link is a placeholder and does not resolve. A
recipe with no runnable example yet (the gap list below) cannot publish until
its example and harness test exist, though the link already points to the final
slug.
Reproducibility profile, in one line
Section titled “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.
Recipes already aggregating
Section titled “Recipes already aggregating”The core repository already holds and merges these five recipes today: the Wave 8 set.
| Recipe | What it does | Module | Profile |
|---|---|---|---|
sign-pades (planned upstream) | Apply a CMS/PAdES baseline signature with a software key | Security | semantic |
encrypt-aes256 (planned upstream) | Encrypt with AES-256 and set permission flags | Security | structural |
pdfa4-conformance-gate (planned upstream) | Produce PDF/A-4 output and gate on an external validator | Conformance | semantic |
accessible-pdfua2-from-html (planned upstream) | Emit the tagged structure for accessible PDF/UA-2 authoring | Accessibility | semantic |
validate-signature (planned upstream) | Inspect whether a PDF carries a signature, and the trust boundary | Inspect | semantic |
Foundations
Section titled “Foundations”Build, paginate, and style a document.
| Recipe | What it does | Module | Profile |
|---|---|---|---|
render-html-to-pdf (planned upstream) | Render an HTML document to PDF | Html | structural |
style-with-css (planned upstream) | Apply CSS to an HTML render | Html | structural |
html-table-layout (planned upstream) | Lay out an HTML table | Html | structural |
paginate-long-html (planned upstream) | Paginate a long HTML document | Html | structural |
compose-text-and-fonts (planned upstream) | Compose text with typography control | Typography | structural |
embed-and-subset-fonts (planned upstream) | Embed and subset fonts | Font | structural |
cjk-vertical-writing (planned upstream) | Set CJK text in vertical writing mode | Typography | structural |
multi-page-document (planned upstream) | Build a multi-page document | Document | structural |
headers-and-footers (planned upstream) | Add running headers and footers | Layout | structural |
Graphics and content
Section titled “Graphics and content”Work with vectors, images, layers, and coordinate space.
| Recipe | What it does | Module | Profile |
|---|---|---|---|
draw-vector-graphics (planned upstream) | Draw vector graphics | Graphics | structural |
gradients-and-transparency (planned upstream) | Apply gradients and transparency | Graphics | structural |
embed-images (planned upstream) | Embed raster images | Content | structural |
optional-content-layers (planned upstream) | Use optional content (layers) | Graphics | structural |
transform-coordinate-space (planned upstream) | Transform the coordinate space | Graphics | structural |
Navigation and forms
Section titled “Navigation and forms”Add bookmarks, links, annotations, and AcroForm fields.
| Recipe | What it does | Module | Profile |
|---|---|---|---|
bookmarks-and-toc (planned upstream) | Build bookmarks and a table of contents | Navigation | structural |
links-and-annotations (planned upstream) | Add links and annotations | Navigation | structural |
generate-barcodes (planned upstream) | Generate barcodes | Barcode | bitwise |
fill-pdf-form (planned upstream) | Fill an AcroForm | Form | structural |
flatten-form-fields (planned upstream) | Flatten form fields | Form | structural |
Document information
Section titled “Document information”Set metadata and viewer behavior.
| Recipe | What it does | Module | Profile |
|---|---|---|---|
set-document-metadata (planned upstream) | Set document metadata | Metadata | structural |
set-viewer-preferences (planned upstream) | Set viewer preferences | Document | structural |
Security, signature, and conformance
Section titled “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-with-permissions (planned upstream) | Encrypt with permission flags | Security | structural |
sign-pades-b-b (planned upstream) | Apply a PAdES signature (B-B and B-T) | Security | semantic |
inspect-existing-signature (planned upstream) | Inspect an existing signature | Inspect | semantic |
tagged-pdf-ua2 (planned upstream) | Emit tagged structure for PDF/UA-2 | Accessibility | semantic |
pdf-a-4-output (planned upstream) | Produce PDF/A-4 output | Conformance | semantic |
validate-conformance (planned upstream) | Validate against a conformance profile | Compliance | semantic |
Inspection and extraction
Section titled “Inspection and extraction”Read content and structure back out of a PDF.
| Recipe | What it does | Module | Profile |
|---|---|---|---|
extract-text-content (planned upstream) | Extract text content | Text | semantic |
parse-and-inspect-pdf (planned upstream) | Parse and inspect a PDF | Inspect | semantic |
inspect-layout-boxes (planned upstream) | Inspect layout boxes | Inspect | semantic |
Cross-cutting
Section titled “Cross-cutting”Use patterns that span several modules.
| Recipe | What it does | Spans | Profile |
|---|---|---|---|
worker-safe-batch-rendering (planned upstream) | Render safely in a long-running worker (shared registries, bounded memory) | Core · Performance · Support | semantic |
exception-aware-error-handling (planned upstream) | Handle errors with the NextPDF exception hierarchy | Exception · Contracts | structural |
observe-with-opentelemetry (planned upstream) | Observe rendering with OpenTelemetry | Observability · Telemetry · Event | semantic |
Recipes pending a runnable example
Section titled “Recipes pending a runnable example”These recipes need a new examples/*.php file plus a tests/Cookbook/Php/
harness in the core repository before they can publish. The slug above is
final. The page remains a placeholder until the example lands and its test
runs:
sign-pades-b-b(planned upstream) (covers PAdES B-B and B-T)inspect-existing-signature(planned upstream)extract-text-content(planned upstream)parse-and-inspect-pdf(planned upstream)validate-conformance(planned upstream)inspect-layout-boxes(planned upstream)worker-safe-batch-rendering(planned upstream) (example exists; new memory/GC harness test added)observe-with-opentelemetry(planned upstream) (new PHP-native example added)
Every other recipe above already has a backing examples/*.php file and needs
only a harness wrapper. This index records the slug and the eventual page. It
does not claim that any pending page is already complete.
See also
Section titled “See also”- Integration cookbook — the framework, renderer, and service integration index.
- Recipe conventions — the contract every runnable recipe in this cookbook follows.