stability: Beta

Artisan configuration

At a glance

ChromeRendererConfig is an immutable, final readonly value object with five constructor parameters. Use it as the bridge’s single configuration surface.

API surface

new ChromeRendererConfig(
    ?string $chromeBinaryPath = null,
    int     $renderTimeout    = 30,
    string  $defaultCss       = '',
    int     $maxHtmlSize      = 5_000_000,
    bool    $noSandbox        = false,
);

Source: src/Artisan/ChromeRendererConfig.php.

Options

Option	Type	Default	Effect
`chromeBinaryPath`	`?string`	`null`	Absolute path to the Chrome/Chromium binary. `null` uses the `chrome-php/chrome` auto-detection default.
`renderTimeout`	`int`	`30`	Maximum seconds for a single render. Used as both the `setHtml` content-load timeout and the Chrome DevTools Protocol (CDP) `sendSyncDefaultTimeout` (passed to Chrome in milliseconds — `renderTimeout * 1000`).
`defaultCss`	`string`	`''`	Cascading Style Sheets (CSS) injected into the wrapped document before the user fragment. `</style>` sequences are stripped before injection (style-break-out defense).
`maxHtmlSize`	`int`	`5_000_000`	Maximum Hypertext Markup Language (HTML) input length in bytes. Inputs over this throw before Chrome is contacted.
`noSandbox`	`bool`	`false`	When `true`, launches Chrome with its operating system (OS) sandbox disabled. Container-only escape hatch with a documented security cost.

Tests assert the timeout-to-milliseconds conversion and the exact Chrome launch flags in tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand and ::getBrowserCreatesAndReusesInstanceWithExpectedOptions.

Construction from an array

Use ChromeRendererConfig::fromArray() to map a snake-case array in framework-style config files:

$config = ChromeRendererConfig::fromArray([
    'chrome_binary'  => '/usr/bin/chromium',
    'render_timeout' => 45,
    'default_css'    => 'body { font-family: "Noto Sans TC", sans-serif; }',
    'max_html_size'  => 2_000_000,
    'no_sandbox'     => false,
]);

Unset keys fall back to the constructor defaults. The chrome_binary key applies only when its value is a non-empty string. Source: ChromeRendererConfig::fromArray().

Fixed Chrome launch flags

BrowserPool always launches Chrome with these flags, regardless of configuration:

--disable-gpu
--disable-dev-shm-usage
--disable-extensions
--disable-background-networking
--disable-translate
--disable-remote-fonts
--disable-domain-reliability
--no-first-run

plus headless: true, keepAlive: true, windowSize: [1200, 800], and noSandbox from configuration. These values are not user-tunable; they serve as hardening and stability defaults. A test asserts the exact set and count (8 custom flags) in tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu.

Choosing values

renderTimeout — set it higher than the slowest expected document. A timeout surfaces as a ChromeRenderException. Long timeouts on user-facing paths create a denial-of-service surface; pair a generous timeout with an upstream request budget. The /integrations/artisan/security-and-operations/ page discusses boundary protection and resource-exhaustion controls for untrusted input. That page cites the Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) and the 2025 Common Weakness Enumeration (CWE) Top 25.
maxHtmlSize — keep the default unless a known workload needs more. The limit is the first line of defense against resource-exhaustion input; raising it expands that surface.
defaultCss — use it for fonts and resets. The value is not a sandbox; it is concatenated into the wrapped document’s <style> block after </style> stripping.
noSandbox — leave it false outside containers. See /integrations/artisan/security-and-operations/ for the precise meaning and limits of disabling it.

Edge cases & gotchas

ChromeRendererConfig is readonly; create a new instance to change a value. There is no setter.
renderTimeout is an int in seconds; sub-second precision is not representable.
If a defaultCss value contains </style> (any case), those closing tags are removed before the document is assembled (asserted by ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss). Plan around that if you template CSS.

Security notes

noSandbox and maxHtmlSize are security-relevant. The /integrations/artisan/security-and-operations/ page covers their threat context and states explicitly what the Chrome sandbox does and does not protect. This page documents the surface; that page documents the boundary.