De Artisan Chrome-brug configureren

In een oogopslag

ChromeRendererConfig is een onveranderlijk final readonly-waardeobject met vijf constructorparameters. Gebruik het als enige configuratielaag voor de brug.

API-oppervlak

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

Bron: src/Artisan/ChromeRendererConfig.php.

Opties

Optie	Type	Standaard	Effect
chromeBinaryPath	?string	null	Absoluut pad naar de Chrome/Chromium-binary. null gebruikt de standaard autodetectie van chrome-php/chrome.
renderTimeout	int	30	Maximaal aantal seconden voor één renderactie. Wordt gebruikt als time-out voor zowel het laden van de inhoud via setHtml als de sendSyncDefaultTimeout van het Chrome DevTools Protocol (CDP) (aan Chrome doorgegeven in milliseconden — renderTimeout * 1000).
defaultCss	string	''	Cascading Style Sheets (CSS) die vóór het gebruikersfragment in het ingepakte document worden geïnjecteerd. </style>-reeksen worden vóór injectie verwijderd (verdediging tegen style-break-out).
maxHtmlSize	int	5_000_000	Maximale lengte van de Hypertext Markup Language (HTML)-invoer in bytes. Invoer die deze waarde overschrijdt, veroorzaakt een uitzondering voordat Chrome wordt aangeroepen.
noSandbox	bool	false	Wanneer true, start Chrome met de sandbox van het besturingssysteem (OS) uitgeschakeld. Een noodvoorziening die uitsluitend voor containers is bedoeld en gedocumenteerde beveiligingskosten met zich meebrengt.

Tests bevestigen de conversie van time-out naar milliseconden en de exacte Chrome-startvlaggen in tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand en ::getBrowserCreatesAndReusesInstanceWithExpectedOptions.

Constructie vanuit een array

Gebruik ChromeRendererConfig::fromArray() om een snake-case array uit framework-achtige configuratiebestanden te mappen:

$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,
]);

Niet-ingestelde sleutels vallen terug op de standaardwaarden van de constructor. De sleutel chrome_binary wordt alleen toegepast als de waarde een niet-lege string is. Bron: ChromeRendererConfig::fromArray().

Vaste Chrome-startvlaggen

BrowserPool start Chrome altijd met deze vlaggen, ongeacht de configuratie:

--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] en noSandbox uit de configuratie. Deze waarden kunnen niet door de gebruiker worden aangepast; ze dienen als vaste defaults voor hardening en stabiliteit. Een test bevestigt de exacte set en het aantal (8 aangepaste vlaggen) in tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu.

Waarden kiezen

• renderTimeout — stel deze hoger in dan de verwachte rendertijd van het traagste document. Een time-out verschijnt als een ChromeRenderException. Lange time-outs op gebruikersgerichte paden vergroten het aanvalsoppervlak voor denial-of-service; combineer een ruime time-out met een upstream-aanvraagbudget. De pagina /integrations/artisan/security-and-operations/ behandelt grensbescherming en maatregelen tegen resource-uitputting voor onvertrouwde invoer. Die pagina verwijst naar de Application Security Verification Standard (ASVS) van het Open Worldwide Application Security Project (OWASP) en de Common Weakness Enumeration (CWE) Top 25 van 2025.
• maxHtmlSize — houd de standaardwaarde aan, tenzij een bekende werklast meer vereist. De limiet is de eerste verdedigingslinie tegen invoer die bronnen uitput; door deze te verhogen vergroot je dat aanvalsoppervlak.
• defaultCss — gebruik dit voor lettertypen en resets. De waarde is geen sandbox; die wordt na het verwijderen van </style> samengevoegd in het <style>-blok van het ingepakte document.
• noSandbox — laat deze buiten containers op false staan. Zie /integrations/artisan/security-and-operations/ voor wat dit precies betekent en waar de grenzen van het uitschakelen liggen.

Randgevallen en valkuilen

• ChromeRendererConfig is readonly; maak een nieuwe instantie om een waarde te wijzigen. Er is geen setter.
• renderTimeout is een int in seconden; precisie onder een seconde is niet weer te geven.
• Als een defaultCss-waarde </style> bevat (ongeacht schrijfwijze), worden die sluit-tags verwijderd voordat het document wordt samengesteld (bevestigd door ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss). Houd hier rekening mee als je CSS via templates samenstelt.

Beveiligingsnotities

noSandbox en maxHtmlSize zijn relevant voor de beveiliging. De pagina /integrations/artisan/security-and-operations/ behandelt de dreigingscontext ervan en geeft expliciet aan waartegen de Chrome-sandbox wel en niet beschermt. Deze pagina documenteert het oppervlak; die pagina documenteert de grens.

Zie ook

• /integrations/artisan/install/
• /integrations/artisan/quickstart/
• /integrations/artisan/chrome-renderer-setup/
• /integrations/artisan/security-and-operations/
• /integrations/artisan/production-usage/