Configurazione del bridge Chrome di Artisan

In breve

ChromeRendererConfig è un value object immutabile final readonly con cinque parametri del costruttore. Rappresenta l’unica superficie di configurazione del bridge.

Superficie dell’API

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

Origine: src/Artisan/ChromeRendererConfig.php.

Opzioni

Opzione	Tipo	Predefinito	Effetto
chromeBinaryPath	?string	null	Percorso assoluto del binario Chrome/Chromium. null delega al rilevamento automatico predefinito di chrome-php/chrome.
renderTimeout	int	30	Numero massimo di secondi per un singolo rendering. Usato sia come timeout di caricamento del contenuto di setHtml, sia come sendSyncDefaultTimeout di CDP (passato a Chrome in millisecondi — renderTimeout * 1000).
defaultCss	string	''	CSS inserito nel documento incapsulato prima del frammento dell’utente. Le sequenze </style> vengono rimosse prima dell’inserimento (difesa contro la fuoriuscita dal blocco di stile).
maxHtmlSize	int	5_000_000	Lunghezza massima dell’input HTML in byte. Gli input che superano questo limite generano un’eccezione prima di contattare Chrome.
noSandbox	bool	false	Se impostato su true, avvia Chrome con la sandbox del sistema operativo disabilitata. È una soluzione di emergenza riservata ai container, con un costo di sicurezza documentato.

La conversione del timeout in millisecondi e i flag esatti per l’avvio di Chrome sono verificati da tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand e ::getBrowserCreatesAndReusesInstanceWithExpectedOptions.

Costruzione da un array

Per i file di configurazione in stile framework, ChromeRendererConfig::fromArray() mappa un array in formato snake-case:

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

Le chiavi non impostate usano i valori predefiniti del costruttore. chrome_binary viene applicato solo quando è una stringa non vuota. Origine: ChromeRendererConfig::fromArray().

Flag di avvio fissi di Chrome

BrowserPool avvia sempre Chrome con questi flag, indipendentemente dalla configurazione:

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

oltre a headless: true, keepAlive: true, windowSize: [1200, 800] e a noSandbox dalla configurazione. Non sono configurabili dall’utente; sono impostazioni predefinite di hardening e stabilità. L’insieme e il numero esatti (8 flag personalizzati) sono verificati da tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu.

Scelta dei valori

• renderTimeout — impostarlo su un valore superiore al tempo del documento più lento previsto. Un superamento del timeout si manifesta come ChromeRenderException. Timeout lunghi su un percorso esposto agli utenti costituiscono una superficie di denial-of-service; abbinare un timeout generoso a un budget di richieste a monte. La protezione dei confini e i controlli contro l’esaurimento delle risorse per input non attendibili sono trattati nella pagina /integrations/artisan/security-and-operations/. Quella pagina cita OWASP ASVS e la CWE Top 25 del 2025.
• maxHtmlSize — mantenere il valore predefinito a meno che un carico di lavoro noto non richieda un valore più alto. Il limite è la prima linea di difesa contro gli input che mirano all’esaurimento delle risorse; aumentarlo amplia tale superficie.
• defaultCss — usarlo per font e reset. Non è una sandbox; viene concatenato nel blocco <style> del documento incapsulato dopo la rimozione di </style>.
• noSandbox — lasciarlo false al di fuori dei container. Consultare /integrations/artisan/security-and-operations/ per il significato preciso e i limiti della sua disabilitazione.

Casi limite e insidie

• ChromeRendererConfig è readonly; per modificare un valore occorre creare una nuova istanza. Non esistono setter.
• renderTimeout è un int di secondi; la precisione inferiore al secondo non è rappresentabile.
• Un valore di defaultCss contenente </style> (in qualsiasi combinazione di maiuscole e minuscole) subisce la rimozione di quei tag di chiusura prima dell’assemblaggio del documento (verificato da ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss). Tenerne conto se si utilizzano template CSS.

Note sulla sicurezza

noSandbox e maxHtmlSize sono rilevanti per la sicurezza. Il contesto di minaccia correlato e la dichiarazione esplicita di ciò che la sandbox di Chrome protegge e non protegge si trovano nella pagina /integrations/artisan/security-and-operations/. Questa pagina documenta la superficie; quella pagina documenta il confine.

Vedere anche

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