Configure the NextPDF Laravel package

At a glance

config/nextpdf.php is published by php artisan vendor:publish --tag=nextpdf-config. Every key has an environment-variable fallback and a hard-coded default. This page lists each key as it appears in the package’s config/nextpdf.php.

Install

php artisan vendor:publish --tag=nextpdf-config

During register(), the provider also merges the package defaults under the nextpdf config key. Unset keys then fall back to the values below, even before you publish the config file.

Conceptual overview

Most environment variables accept either a NEXTPDF_* name or a legacy TCPDF_* name. The legacy prefix is available during the transition period documented in UPGRADE.md. Use NEXTPDF_* for new deployments. The config file resolves values in this order: environment variable → published file value → package default.

API surface — configuration keys

Document layout

Key	Env (primary)	Default	Effect
`page_format`	`NEXTPDF_PAGE_FORMAT`	`A4`	Default page format: A4, A3, A5, Letter, Legal, or Tabloid
`orientation`	`NEXTPDF_ORIENTATION`	`P`	Portrait (`P`) or landscape (`L`)
`unit`	`NEXTPDF_UNIT`	`mm`	Measurement unit: pt, mm, cm, or in
`defaults.creator`	`NEXTPDF_CREATOR`	`NextPDF`	Document creator metadata; applied to the `PdfDocumentInterface` binding
`defaults.author`	`NEXTPDF_AUTHOR`	(empty)	Author metadata; applied only when non-empty
`defaults.language`	`NEXTPDF_LANG`	`en`	Document language; applied to the document binding
`defaults.margin_top` / `_right` / `_bottom` / `_left`	—	`10`	Default margins
`defaults.font_family`	—	`dejavusans`	Default font family
`defaults.font_size`	—	`12`	Default font size
`defaults.trim_box`	—	`null`	TrimBox `[left, bottom, right, top]` in points, or `null`
`defaults.bleed_box`	—	`null`	BleedBox `[left, bottom, right, top]` in points, or `null`

The provider applies defaults.creator, defaults.language, and (when set) defaults.author to each newly resolved document. The provider skips defaults.author when the value is empty.

Archival and color

Key	Env (primary)	Default	Effect
`pdfa`	`NEXTPDF_PDFA`	`null`	PDF/A archival level: `null`, `4`, `4e`, or `4f`. A non-null value enables PDF/A on the document binding and requires `nextpdf/premium`
`fonts_path`	`NEXTPDF_FONTS_PATH`	`resource_path('fonts')`	Directory for additional TrueType fonts; sets the font registry search path
`cache_path`	`NEXTPDF_CACHE_PATH`	`storage_path('framework/cache/tcpdf')`	Parsed-font and temporary-file cache directory
`icc_profile.rgb`	`NEXTPDF_ICC_PROFILE_RGB`	`null`	RGB ICC profile path; required for PDF/A
`icc_profile.cmyk`	`NEXTPDF_ICC_PROFILE_CMYK`	`null`	Optional CMYK ICC profile for print workflows
`font_cache_locking`	`NEXTPDF_FONT_CACHE_LOCKING`	`true`	Use `flock` for the font cache to prevent corruption when concurrent queue workers write

A non-null pdfa value requires the Premium tier. Without nextpdf/premium, resolving the document binding with pdfa set raises a class-not-found error for the PDF/A version type. This page does not document Premium archival behavior. See the Premium documentation.

Worker memory (long-lived runtimes)

Key	Env (primary)	Default	Effect
`preload_fonts`	—	`[]`	Absolute font-file paths parsed at worker boot. The font registry is locked after warmup
`image_cache_mb`	`NEXTPDF_IMAGE_CACHE_MB`	`50`	Least recently used (LRU) image-cache budget in megabytes (MB). `0` disables caching. No upper bound is enforced at the provider level

The image-cache budget has no provider-enforced upper bound. Use a container memory limit or php.inimemory_limit to bound it. The config file recommends a practical maximum of 256 MB.

Digital signature (Premium)

Key	Env (primary)	Default	Effect
`signature.enabled`	`NEXTPDF_SIGN_ENABLED`	`false`	When false, or when the certificate is empty, `SignerInterface` resolves to `null`
`signature.certificate`	`NEXTPDF_SIGN_CERT`	`null`	Signing certificate path
`signature.private_key`	`NEXTPDF_SIGN_KEY`	`null`	Private key path
`signature.password`	`NEXTPDF_SIGN_PASSWORD`	(empty)	Key passphrase
`signature.extra_certs`	—	`[]`	Intermediate CA certificate paths
`signature.level`	`NEXTPDF_SIGN_LEVEL`	`B-B`	PDF Advanced Electronic Signatures (PAdES) baseline level passed to the signer

The Core package documented here does not ship a signer implementation; SignerInterface resolves to null until nextpdf/premium provides one. With Premium, level: B-B produces a PAdES B-B baseline signature. Higher PAdES baselines depend on a configured timestamp authority and Premium capability; this page does not document those levels.

Timestamp authority

Key	Env (primary)	Default	Effect
`tsa.url`	`NEXTPDF_TSA_URL`	`null`	Timestamp authority (TSA) endpoint. When empty, `TsaClient` resolves to `null`
`tsa.username` / `tsa.password`	`NEXTPDF_TSA_USERNAME` / `_PASSWORD`	(empty)	TSA HTTP credentials
`tsa.cert` / `tsa.key`	`NEXTPDF_TSA_CERT` / `_KEY`	`null`	Client certificate / key for mutual Transport Layer Security (mTLS) to the TSA
`tsa.timeout`	`NEXTPDF_TSA_TIMEOUT`	`30`	HTTP timeout in seconds for the PSR-18 client
`tsa.pinned_public_keys`	—	`[]`	Base64 SHA-256 SubjectPublicKeyInfo (SPKI) pins (RFC 7469). Empty disables pinning
`tsa.warn_on_key_rotation`	`NEXTPDF_TSA_WARN_ROTATION`	`true`	Emit a warning when the TSA presents a non-pinned SPKI
`tsa.allow_insecure_http`	`NEXTPDF_TSA_ALLOW_INSECURE_HTTP`	`false`	Permit plaintext HTTP to the TSA. Leave false in production

OCSP response cache

Key	Env (primary)	Default	Effect
`ocsp_cache.enabled`	`NEXTPDF_OCSP_CACHE_ENABLED`	`true`	Cache Online Certificate Status Protocol (OCSP) responses during validation
`ocsp_cache.ttl`	`NEXTPDF_OCSP_CACHE_TTL`	`86400`	Cache TTL in seconds
`ocsp_cache.directory`	`NEXTPDF_OCSP_CACHE_DIR`	`null`	Cache directory; `null` keeps the cache in memory only

Queue

Key	Env (primary)	Default	Effect
`queue.connection`	`NEXTPDF_QUEUE_CONNECTION`	`null`	Queue connection; `null` uses the default connection
`queue.queue`	`NEXTPDF_QUEUE_NAME`	`pdf`	Queue that `GeneratePdfJob` is pushed to
`queue.timeout`	`NEXTPDF_QUEUE_TIMEOUT`	`120`	Per-job timeout in seconds

Chrome CDP renderer (Artisan extension)

Key	Env (primary)	Default	Effect
`artisan.chrome_binary`	`NEXTPDF_ARTISAN_CHROME_BINARY`	env value or unset	Path to the Chrome/Chromium binary
`artisan.render_timeout`	`NEXTPDF_ARTISAN_RENDER_TIMEOUT`	`30`	Render timeout in seconds
`artisan.default_css`	`NEXTPDF_ARTISAN_DEFAULT_CSS`	(empty)	Default CSS injected into rendered HTML
`artisan.no_sandbox`	`NEXTPDF_ARTISAN_NO_SANDBOX`	`false`	Disable the Chrome sandbox
`artisan.max_html_size`	`NEXTPDF_ARTISAN_MAX_HTML_SIZE`	`5000000`	Maximum HTML input size in bytes

The artisan section applies to the document binding only when a Chrome browser-factory class is present (the nextpdf/artisan extension). When that class is absent, the section is ignored.

Code sample — Production

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

Edge cases & gotchas

signature.enabled = true with an empty signature.certificate still resolves SignerInterface to null; both values must be set.
tsa.url = null forces TsaClient to null, even if other tsa.* keys are populated.
signature.level = null falls back to PAdES B-B on the signer.
image_cache_mb set to null (not 0) falls back to the 50 MB default; 0 explicitly disables caching.
Legacy TCPDF_* environment variables remain readable but are deprecated. Migrate to NEXTPDF_*.

Performance

Reading config uses O(1) array access. preload_fonts trades a one-time O(f) parse at worker boot for lower first-request latency. A larger image_cache_mb reduces repeated image decoding at the cost of process-resident memory.

Security notes

tsa.allow_insecure_http weakens timestamp trust and must stay false in production. TSA URLs should come from trusted configuration only. If you expose them through an admin surface, use egress firewall or DNS policy to mitigate request forgery. See /integrations/laravel/security-and-operations/.

Conformance

No normative standard governs the configuration file shape. All keys are verified against the package’s config/nextpdf.php at the documented revision. Premium governs signature-level semantics, which are outside the scope of this Core page.

Commercial context

The signature and tsa sections drive Premium signing when nextpdf/premium is installed. This optional Enterprise capability requires no Core package code changes. See https://nextpdf.dev/get-license/?intent=laravel-signing.