Artisan API reference

At a glance

The Artisan package (nextpdf/artisan) exposes two related API groups. The Chrome rendering surface — ChromeRendererConfig, ChromeHtmlRenderer, ChromeSecurityPolicy, ChromeRenderResult, ViewportCalculator, and BrowserPool — turns a Hypertext Markup Language (HTML) fragment into a Chrome-produced Portable Document Format (PDF) file. The parser and importer surface — PdfReader, PageImporter, ImportedFormXObject, and supporting tokenizer and cross-reference classes — embeds that rendered output back into a NextPDF document as a text-selectable Form XObject.

Start here: if you only need a PDF from HTML, you rarely use this package directly. Attach a ChromeRendererConfig to a NextPDF Document and call writeHtmlChrome(); see the quickstart. Use the classes below when you embed a renderer in a worker or run parser diagnostics. The first example under Common tasks shows the one-call path.

Common tasks

The three flows below cover nearly all production use, from the highest-level call to the explicit render-and-import pipeline. Each sample is verified against nextpdf-Artisan/src (and the package README.md / ci/tests/).

Render an HTML fragment to a text-selectable PDF with the canonical call.

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Artisan\ChromeRendererConfig;

require __DIR__ . '/vendor/autoload.php';

$config = new ChromeRendererConfig(chromeBinaryPath: '/usr/bin/chromium');

$doc = Document::createStandalone();
$doc->setChromeRendererConfig($config);
$doc->addPage();
$doc->writeHtmlChrome('<div style="display:flex;gap:20px"><h2>Revenue</h2><p>$124,500</p></div>');
$doc->save('/tmp/report.pdf');

What it does: Chrome lays out the fragment. The bridge embeds page 0 as a Form XObject, so the text remains selectable. writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static auto-fits height when $height is null.

Run the renderer and import the page yourself when you need the explicit pipeline behind writeHtmlChrome(), such as in workers or custom placement flows.

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\ImportedFormXObject;
use NextPDF\Artisan\PageImporter;
use NextPDF\Parser\PdfReader;

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig(renderTimeout: 30));

try {
    $result = $renderer->render($html, widthPt: 595.28);

    $reader = new PdfReader($result->getPdfData());
    $reader->parse();

    $form = (new PageImporter())->import($reader);
} finally {
    $renderer->close();
}

What it does: renders Chrome PDF bytes, parses them, and imports page 0 into an ImportedFormXObject you can place. Always call close() on the renderer to release the Chrome process.

Build the config from a framework-style array for config/*.php or bundle parameters instead of hard-coded constructor arguments.

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeRendererConfig;

$config = ChromeRendererConfig::fromArray([
    'chrome_binary'  => '/usr/bin/chromium',
    'render_timeout' => 45,
    'max_html_size'  => 2_000_000,
    'no_sandbox'     => false,
]);

What it does: maps a snake-case config array to the constructor. Unset keys use defaults, and chrome_binary is applied only when it is a non-empty string.

Chrome renderer

These types run the render path. Build a ChromeRendererConfig, pass it to a ChromeHtmlRenderer, then call render() to get a ChromeRenderResult.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`new ChromeRendererConfig(?string $chromeBinaryPath = null, int $renderTimeout = 30, string $defaultCss = '', int $maxHtmlSize = 5000000, bool $noSandbox = false)`	Binary path, timeout, Cascading Style Sheets (CSS), HTML size limit, sandbox flag.	Auto-detect Chrome when binary path is `null`; sandbox remains enabled unless disabled.	`ChromeRendererConfig`	none expected.	Set `noSandbox` only when the runtime requires it.
`ChromeRendererConfig::fromArray(array $config)`	`chrome_binary`, `render_timeout`, `default_css`, `max_html_size`, `no_sandbox`.	Missing values use constructor defaults.	`ChromeRendererConfig`	Type mismatches fall back to defaults for optional keys.	Matches framework-style configuration arrays.
`new ChromeHtmlRenderer(ChromeRendererConfig $config, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null)`	Config, optional logger, optional parse-layer HTML policy.	Uses `DefaultHtmlSecurityPolicy` when no policy is supplied.	`ChromeHtmlRenderer`	Chrome setup errors occur on first render.	Renderer owns a browser pool until `close()`.
`ChromeHtmlRenderer::render(string $html, float $widthPt, float $heightPt = 0)`	`html`: input fragment; `widthPt`: paper width; `heightPt`: target height or auto.	Auto-calculates content height when `heightPt <= 0`.	`ChromeRenderResult`	`ChromeRenderException`; HTML size validation failure.	Blocks subresource network requests through Chrome DevTools Protocol (CDP).
`ChromeHtmlRenderer::getHtmlSecurityPolicy()`	none.	Returns the configured parse-layer policy.	`HtmlSecurityPolicyInterface`	none expected.	Complements Chrome transport-level controls.
`ChromeHtmlRenderer::close()`	none.	Closes the browser pool and clears it.	`void`	Browser shutdown errors may surface from the underlying library.	Call during worker shutdown.

HTML security policy

Use these APIs when you validate and wrap external HTML before rendering instead of calling ChromeHtmlRenderer::render() directly, which already calls them.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`ChromeSecurityPolicy::validate(string $html, int $maxSize)`	HTML input and maximum byte size.	Accepts input only when size and disallowed constructs pass validation.	`void`	`ChromeRenderException` or validation exception.	Run before browser rendering when accepting external HTML.
`ChromeSecurityPolicy::wrapHtml(string $html, int $viewportWidth, string $defaultCss = '')`	HTML fragment, viewport width, optional default CSS.	Produces a complete render document around the fragment.	`string`	Validation or string construction errors.	Keeps renderer-specific CSS separate from application HTML.

Result and conversion helpers

Use these helpers to read a render result (ChromeRenderResult) and convert between PDF points and Chrome CSS pixels when sizing a viewport or computing height.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`new ChromeRenderResult(string $pdfData, float $widthPt, float $heightPt, float $contentHeightCssPx)`	Raw PDF bytes, width, height, measured content height.	No validation beyond typed constructor properties.	`ChromeRenderResult`	none expected.	Usually returned by `ChromeHtmlRenderer::render()`.
`ChromeRenderResult::getPdfData()`	none.	Returns raw Chrome-produced PDF bytes.	`string`	none expected.	Use with `PdfReader` and `PageImporter` when embedding.
`ChromeRenderResult::getWidthPt()`	none.	Returns requested width in points.	`float`	none expected.	Used to size the imported form object.
`ChromeRenderResult::getHeightPt()`	none.	Returns computed or requested height in points.	`float`	none expected.	Auto-height includes a print-layout buffer.
`ViewportCalculator::pointsToCssPx(float $pt)`	`pt`: PDF points.	Converts using 96 CSS px per 72 PDF points.	`int`	none expected.	Rounded for Chrome viewport width.
`ViewportCalculator::cssPxToPoints(float $px)`	`px`: CSS pixels.	Converts using 72 PDF points per 96 CSS px.	`float`	none expected.	Used for auto-height calculation.

Import and parser APIs

This is the import path. Parse Chrome PDF bytes with PdfReader, then pass the reader to PageImporter::import() to get an embeddable page; the remaining PdfReader methods support diagnostics.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`new PdfReader(string $data)`	`data`: complete PDF bytes.	Parser is not run until `parse()`.	`PdfReader`	none expected.	Designed for Chrome-generated PDFs.
`PdfReader::parse()`	none.	Parses the cross-reference (xref) chain and trailer.	`void`	`PdfParseException` for invalid PDF structure.	Must be called before object/page access.
`PdfReader::getObject(int $objNum)`	Object number.	Resolves the parsed object by number.	`PdfObject`	`PdfParseException` when the object is missing or malformed.	Use after `parse()`.
`PdfReader::getTrailer()`	none.	Returns parsed trailer dictionary.	`array`	`PdfParseException` when trailer data is unavailable.	Used by diagnostics and revision analysis.
`PdfReader::getObjectNumbers()`	none.	Returns parsed object numbers.	`array`	none expected after parse.	Useful for importer diagnostics.
`PdfReader::getPage(int $pageIndex)`	`pageIndex`: zero-based page index.	No implicit parse.	`PdfObject`	`PdfParseException` when missing or out of range.	Importer defaults to page `0`.
`PdfReader::getPageContentStream(PdfObject $page)`	`page`: parsed page object.	Resolves content stream.	`string`	`PdfParseException` for invalid streams.	Empty stream causes importer failure.
`PdfReader::getPageResources(PdfObject $page)`	`page`: parsed page object.	Resolves page resources.	`array`	`PdfParseException` for invalid resources.	Resource dictionary is embedded with the form object.
`PdfReader::getPageMediaBox(PdfObject $page)`	`page`: parsed page object.	Falls back to A4-like dimensions when absent.	`array`	Parser failures.	Returns PDF-space coordinates.
`PdfReader::resolveRef(mixed $value)`	Parsed value.	Resolves object references recursively where applicable.	`mixed`	`PdfParseException` for invalid references.	Internal-style helper exposed for importer workflows.
`PdfReader::collectPageResources(PdfObject $page)`	`page`: parsed page object.	Traverses page resource references.	`array`	Parser failures.	Used to embed dependent objects with imported pages.
`PdfReader::getRevisionCount()`	none.	Counts parsed incremental revisions.	`int`	none expected after parse.	Useful for signed or incrementally updated PDFs.
`PdfReader::getRevisionXRef(int $index)`	Zero-based revision index.	Returns one revision xref table.	`RevisionXRefTable`	`PdfParseException` for invalid index.	Use for low-level revision diagnostics.
`PdfReader::getRevisions()`	none.	Returns all parsed revision xref tables.	`array`	none expected after parse.	Read-only parser state view.
`PageImporter::import(PdfReader $reader, int $pageIndex = 0)`	Parsed reader and zero-based page index.	Imports the first page when omitted.	`ImportedFormXObject`	`PdfParseException` when the page cannot be extracted.	Collects content stream, media box, resources, and referenced objects.

Parser support objects

These value objects and helpers are returned by the parser or used internally. Use them when you inspect imported objects, resources, streams, or revision tables.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`new ImportedFormXObject(string $contentStream, array $mediaBox, array $embeddedObjects, array $resourcesDict)`	Decoded content stream, media box, embedded objects, resources dictionary.	Stores a self-contained imported form payload.	`ImportedFormXObject`	none expected.	Usually returned by `PageImporter::import()`.
`ImportedFormXObject::getWidth()`	none.	Returns imported form width in points.	`float`	none expected.	Use when placing Chrome output into a page.
`ImportedFormXObject::getHeight()`	none.	Returns imported form height in points.	`float`	none expected.	Auto-height render results propagate through this value.
`ImportedFormXObject::getEmbeddedObjects()`	none.	Returns objects required by the imported form.	`array`	none expected.	Writer code uses these objects to preserve resources.
`ImportedFormXObject::getResourcesDict()`	none.	Returns the imported resource dictionary.	`array`	none expected.	Used when building the form XObject.
`ImportedFormXObject::getMediaBox()`	none.	Returns the imported media box.	`array`	none expected.	Use for placement diagnostics.
`ImportedFormXObject::getContentStream()`	none.	Returns the imported page content stream.	`string`	none expected.	Intended for writer/import integration.
`new PdfObject(int $objectNumber, int $generation, array $dictionary, ?string $rawStreamData = null, ?string $decodedStreamData = null, ?string $rawDictionaryBytes = null)`	Object number, generation, parsed dictionary, optional stream bytes, optional decoded stream, optional raw dictionary bytes.	Stores parsed object state.	`PdfObject`	none expected.	Created by parser internals.
`PdfObject::getRawDictionaryBytes()`	none.	Returns the original dictionary bytes when available.	`string	null`	none expected.
`PdfObject::getRawStreamData()`	none.	Returns undecoded stream bytes when available.	`string	null`	none expected.
`PdfObject::getDictionary()`	none.	Returns parsed dictionary entries.	`array`	none expected.	Read-only parser view.
`PdfObject::get(string $key)`	Dictionary key.	Returns `null` when the key is absent.	`mixed`	none expected.	Keeps callers from parsing raw dictionaries.
`PdfObject::getRef(string $key)`	Dictionary key.	Returns object reference tuple when the value is a reference.	`array	null`	none expected.
`PdfObject::getArray(string $key)`	Dictionary key.	Returns an array value or an empty array when unavailable.	`array`	none expected.	Convenience wrapper for array-valued dictionary entries.
`PdfObject::hasStream()`	none.	Checks whether stream bytes are present.	`bool`	none expected.	Distinguishes dictionary-only objects.
`PdfObject::getType()`	none.	Reads `/Type`.	`string	null`	none expected.
`PdfObject::getSubtype()`	none.	Reads `/Subtype`.	`string	null`	none expected.
`RevisionExtractor::extractRevision(string $pdfData, PdfReader $reader, int $revision)`	PDF bytes, a parsed reader, and the zero-based revision index.	Extracts one incremental revision.	`string`	`PdfParseException` for invalid boundaries.	Used by parser tests and diagnostics.
`RevisionExtractor::getRevisionBoundaries(string $pdfData, PdfReader $reader)`	PDF bytes and a parsed reader.	Discovers byte ranges for incremental revisions.	`array`	`PdfParseException` for malformed xref structure.	Helps analyze signed or incrementally updated PDFs.
`StreamDecoder::decode(string $data, string	array $filter)`	Stream bytes and one or more PDF filters.	Applies filters in order.	`string`	`PdfParseException` for unsupported or invalid filters.
`new ResourceCollector(PdfReader $reader)`	Parsed reader.	Starts with an empty collected-object set.	`ResourceCollector`	none expected.	Used by `PdfReader::collectPageResources()`.
`ResourceCollector::traverse(mixed $value, int $depth = 0)`	Parsed value and recursion depth.	Traverses resource references up to internal depth limits.	`void`	Parser failures for invalid references.	Internal helper for page import resource closure.
`ResourceCollector::getCollected()`	none.	Returns collected resource objects.	`array`	none expected.	Call after `traverse()`.
`new RevisionXRefTable(int $index, int $xrefOffset, array $xrefEntries, array $trailer, ?int $prevOffset)`	Revision index, xref offset, xref entries, trailer, optional previous offset.	Immutable snapshot of one incremental revision.	`RevisionXRefTable`	none expected.	Created by parser internals.
`RevisionXRefTable::getObjectNumbers()`	none.	Returns object numbers active in the revision table.	`array`	none expected.	Low-level revision diagnostic API.
`RevisionXRefTable::getActiveObjectCount()`	none.	Counts active objects.	`int`	none expected.	Useful for parser assertions.
`RevisionXRefTable::hasRootUpdate()`	none.	Reports whether the revision updates the document root.	`bool`	none expected.	Useful for incremental-update analysis.
`RevisionXRefTable::getSize()`	none.	Returns the xref table size value.	`int`	none expected.	Mirrors parsed PDF xref metadata.

Low-level tokenizer and xref APIs

Use these APIs only for deep parser diagnostics or fixture reduction. They expose the lexer and cross-reference machinery under PdfReader and are not needed for normal import.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`new PdfTokenizer(string $data, int $offset = 0)`	PDF bytes and optional initial offset.	Starts at offset zero.	`PdfTokenizer`	none expected.	Low-level lexical parser.
`PdfTokenizer::getOffset()`	none.	Returns the current byte offset.	`int`	none expected.	Diagnostic helper for parser errors.
`PdfTokenizer::setOffset(int $offset)`	Byte offset.	Moves the tokenizer cursor.	`void`	`PdfParseException` for invalid offset.	Use carefully; callers own parser state.
`PdfTokenizer::isEof()`	none.	Checks whether cursor reached the end.	`bool`	none expected.	Low-level parser loop helper.
`PdfTokenizer::skipWhitespace()`	none.	Advances past PDF whitespace and comments.	`void`	none expected.	Used before token reads.
`PdfTokenizer::readToken()`	none.	Reads the next scalar token.	`string	int	float
`PdfTokenizer::readName()`	none.	Reads a PDF name object.	`string`	`PdfParseException` for malformed name.	Decodes name escapes.
`PdfTokenizer::readLiteralString()`	none.	Reads a literal string.	`string`	`PdfParseException` for malformed string.	Handles nested parentheses and escapes.
`PdfTokenizer::readHexString()`	none.	Reads a hexadecimal string.	`string`	`PdfParseException` for malformed hex.	Pads odd-length hex according to parser rules.
`PdfTokenizer::readNumber()`	none.	Reads an integer or float.	`int	float`	`PdfParseException` for invalid number.
`PdfTokenizer::readKeyword()`	none.	Reads a PDF keyword.	`string`	`PdfParseException` for invalid keyword.	Keeps keyword parsing centralized.
`PdfTokenizer::readDictionary()`	none.	Reads a PDF dictionary.	`array`	`PdfParseException` for malformed dictionaries.	Used for objects, streams, and trailers.
`PdfTokenizer::readArray()`	none.	Reads a PDF array.	`array`	`PdfParseException` for malformed arrays.	Recursive parser helper.
`PdfTokenizer::readValue()`	none.	Reads any supported PDF value.	`mixed`	`PdfParseException` for malformed values.	Common parser primitive.
`PdfTokenizer::readStreamData(int $length)`	Stream length.	Reads exactly the requested stream bytes.	`string`	`PdfParseException` for invalid stream boundaries.	Used after dictionary stream length resolution.
`PdfTokenizer::peek(int $length = 1)`	Byte count.	Reads ahead without advancing.	`string`	none expected.	Useful for parser branching.
`PdfTokenizer::searchBackward(string $pattern, int $startFrom = 0)`	Pattern and optional start offset.	Searches backward from the end or from the provided offset.	`int	false`	none expected.
`PdfTokenizer::readLine()`	none.	Reads a line from the current offset.	`string`	none expected.	Low-level scanner helper.
`CrossRefParser::parseXRefTable(string $data, int $offset)`	PDF bytes and xref table offset.	Parses classic cross-reference table entries.	`array`	`PdfParseException` for malformed xref data.	Low-level parser API.
`CrossRefParser::parseXRefStream(string $data, int $offset)`	PDF bytes and xref stream offset.	Parses cross-reference stream entries.	`array`	`PdfParseException` for malformed stream data.	Supports modern PDF xref streams.

Optional factories and browser pool

EInvoiceServiceFactory lazily resolves optional Premium e-invoice contracts and returns null when they are absent. BrowserPool manages the renderer-owned Chrome lifecycle; manage it directly only in long-running workers.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`EInvoiceServiceFactory::makeEmbedder()`	none.	Returns `null` unless Premium Pro e-invoice support is installed.	`EmbedderInterface	null`	Optional package construction errors.
`EInvoiceServiceFactory::makeValidator()`	none.	Returns `null` unless Premium Enterprise validation support is installed.	`ValidatorInterface	null`	Optional package construction errors.
`EInvoiceServiceFactory::makeDefaultProfile()`	none.	Returns the default e-invoice profile when available.	`ProfileInterface	null`	Optional package errors.
`EInvoiceServiceFactory::makeSchematronRunner()`	none.	Returns `null` unless Premium Enterprise Schematron support is installed.	`SchematronRunnerInterface	null`	Optional package construction errors.
`new BrowserPool(ChromeRendererConfig $config, ?LoggerInterface $logger = null)`	Renderer config and optional logger.	Browser starts lazily on first `getBrowser()`.	`BrowserPool`	none expected until browser startup.	Renderer-owned lifecycle helper.
`BrowserPool::getBrowser()`	none.	Starts or returns the current Chrome browser instance.	`Browser`	Browser startup errors.	Renderer-owned lifecycle helper.
`BrowserPool::incrementRenderCount()`	none.	Increments render counter and rotates when pool policy requires it.	`void`	Browser lifecycle errors.	Used by long-running workers.
`BrowserPool::close()`	none.	Closes the managed browser instance.	`void`	Browser shutdown errors.	Call during worker shutdown.

Development notes

The renderer is not a browser sandbox for untrusted HTML. Validate size, resource policy, and caller authorization before rendering.
Parser APIs are intentionally narrow. Use them for Chrome-output import, not general PDF repair.
Close renderers explicitly in long-lived workers.