Configurer le pont Chrome d'Artisan

En un coup d’œil

ChromeRendererConfig est un objet-valeur immuable, final readonly, qui expose cinq paramètres de constructeur. C’est le seul point de configuration du pont.

Surface de l’API

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	Valeur par défaut	Effet
chromeBinaryPath	?string	null	Chemin absolu vers le binaire Chrome/Chromium. null laisse chrome-php/chrome utiliser sa détection automatique par défaut.
renderTimeout	int	30	Nombre maximal de secondes accordées à un rendu. Utilisé à la fois comme délai de chargement du contenu de setHtml et comme sendSyncDefaultTimeout CDP (transmis à Chrome en millisecondes, soit renderTimeout * 1000).
defaultCss	string	''	CSS injecté dans le document encadré avant le fragment fourni par l’utilisateur. Les séquences </style> sont supprimées avant l’injection (défense contre la sortie du bloc style).
maxHtmlSize	int	5_000_000	Taille maximale de l’entrée HTML, en octets. Les entrées qui dépassent cette limite lèvent une exception avant que Chrome ne soit contacté.
noSandbox	bool	false	Lorsque true, lance Chrome avec son sandbox système désactivé. Solution de contournement réservée aux conteneurs, avec le coût de sécurité documenté.

La conversion du délai en millisecondes et les drapeaux exacts de lancement de Chrome sont vérifiés par tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand et ::getBrowserCreatesAndReusesInstanceWithExpectedOptions.

Construction à partir d’un tableau

Pour les fichiers de configuration au format attendu par un framework, ChromeRendererConfig::fromArray() fait correspondre un tableau en 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,
]);

Les clés absentes reprennent les valeurs par défaut du constructeur. chrome_binary n’est appliqué que s’il s’agit d’une chaîne non vide. Source : ChromeRendererConfig::fromArray().

Drapeaux de lancement Chrome figés

BrowserPool lance toujours Chrome avec les drapeaux suivants, indépendamment de la configuration :

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

s’y ajoutent headless: true, keepAlive: true, windowSize: [1200, 800], et noSandbox issu de la configuration. Ils ne sont pas réglables par l’utilisateur ; ce sont des valeurs par défaut de durcissement et de stabilité. Leur liste exacte et leur nombre (8 drapeaux personnalisés) sont vérifiés par tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu.

Choisir les valeurs

• renderTimeout — fixe-le à une valeur supérieure au temps attendu pour le document le plus lent. Un dépassement de délai se manifeste sous la forme d’une ChromeRenderException. Sur un chemin exposé à l’utilisateur, les délais longs constituent une surface de déni de service ; associe un délai généreux à un budget de requête en amont. La protection des limites et les contrôles d’épuisement des ressources pour les entrées non fiables sont traités sur la page /integrations/artisan/security-and-operations/. Cette page cite OWASP ASVS et le CWE Top 25 de 2025.
• maxHtmlSize — garde la valeur par défaut, sauf si une charge de travail connue nécessite davantage. Cette limite est la première ligne de défense contre les entrées qui épuisent les ressources ; l’augmenter élargit cette surface.
• defaultCss — utilise-le pour les polices et les réinitialisations. Ce n’est pas un sandbox ; il est concaténé dans le bloc <style> du document encadré après la suppression des </style>.
• noSandbox — laisse-le à false en dehors des conteneurs. Consulte /integrations/artisan/security-and-operations/ pour connaître la signification précise et les limites de sa désactivation.

Cas limites & pièges

• ChromeRendererConfig est readonly ; construis une nouvelle instance pour changer une valeur. Il n’y a pas de setter.
• renderTimeout est un int exprimé en secondes ; la précision inférieure à la seconde n’est pas représentable.
• Une valeur defaultCss contenant </style> (quelle que soit la casse) voit ces balises de fermeture retirées avant l’assemblage du document (vérifié par ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss). Tiens-en compte si tu génères ton CSS à partir d’un modèle.

Notes de sécurité

noSandbox et maxHtmlSize ont une incidence sur la sécurité. Leur contexte de menace, ainsi que le détail explicite de ce que le sandbox Chrome protège et ne protège pas, se trouvent sur la page /integrations/artisan/security-and-operations/. Cette page documente la surface ; la page de sécurité documente la limite.

Voir aussi

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