Install NextPDF Artisan

At a glance

Install nextpdf/artisan with Composer. Composer also installs the chrome-php/chrome runtime dependency. Then make a Chrome or Chromium binary available to the PHP process.

Install

composer require nextpdf/artisan

The package declares these constraints in composer.json:

Requirement	Constraint	Notes
`php`	`>=8.4 <9.0`	PHP 8.4 only
`nextpdf/core`	`^3.0 \|\| ^5.2`	The open-source NextPDF engine
`chrome-php/chrome`	`^1.15`	Chrome DevTools Protocol (CDP) client library; pulled in transitively
`psr/log`	`^3.0`	Optional logger injection point

Composer resolves chrome-php/chrome automatically. Composer never installs the Chrome binary; that binary is a system dependency.

Provision the Chrome binary

The bridge requires an executable Chrome or Chromium binary. By default, chrome-php/chrome looks for a binary in common paths. To pin an explicit path, pass it through configuration. See /integrations/artisan/configuration/ and the dedicated /integrations/artisan/chrome-renderer-setup/ page.

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

Before you wire the binary into the application, verify that it runs headless:

chromium --headless --dump-dom about:blank

A successful run prints an empty Document Object Model (DOM) document and exits 0. A non-zero exit means the binary or its shared libraries are missing. Fix that before continuing, because the bridge surfaces the same failure as a ChromeRenderException at render time.

Verify the package is wired

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\ChromeHtmlRenderer;

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

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig());

echo $renderer->getHtmlSecurityPolicy()->getName(), PHP_EOL;
// Prints: default

This constructs the renderer and reads the default Hypertext Markup Language (HTML) security policy without launching Chrome. It confirms that autoloading and the nextpdf/core contract bindings resolve. (Behavior asserted by tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected.)

Container installs

In Docker, the Chrome sandbox usually cannot start as process ID (PID) 1 / root without extra kernel capabilities. The package exposes a noSandbox switch for that case. Disabling the Chrome sandbox has a real security cost. The /integrations/artisan/security-and-operations/ page and /integrations/artisan/chrome-renderer-setup/ document that cost and state its limits explicitly. Do not set the switch without reading that section.

Edge cases & gotchas

chrome-php/chrome present but no binary. Composer succeeds; the first render throws ChromeRenderException and wraps the launch failure. The library check is separate from the binary check.
chrome-php/chrome absent. If the library is removed from the autoloader, BrowserPool::getBrowser() throws ChromeNotAvailableException with the exact remediation command. (Asserted by tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable.)
Version constraint. nextpdf/core: ^3.0 || ^5.2 — Artisan supports both core major lines. Pin the core version your application targets.

Security notes

Installing the bridge introduces an external process (Chrome) into the trust boundary. Review /integrations/artisan/security-and-operations/ before you expose any render path to user-supplied HTML.