Configuración del puente Chrome de Artisan

De un vistazo

ChromeRendererConfig es un objeto de valor inmutable, final readonly, con cinco parámetros en el constructor. Constituye la única superficie de configuración del puente.

Superficie de la API

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

Fuente: src/Artisan/ChromeRendererConfig.php.

Opciones

Opción	Tipo	Predeterminado	Efecto
chromeBinaryPath	?string	null	Ruta absoluta del binario de Chrome/Chromium. null delega en el valor predeterminado de autodetección de chrome-php/chrome.
renderTimeout	int	30	Número máximo de segundos para un único renderizado. Se usa como tiempo de espera para la carga de contenido de setHtml y también como sendSyncDefaultTimeout de CDP (pasado a Chrome en milisegundos: renderTimeout * 1000).
defaultCss	string	''	CSS inyectado en el documento envolvente antes del fragmento del usuario. Las secuencias </style> se eliminan antes de la inyección (como defensa contra el cierre prematuro del bloque de estilos).
maxHtmlSize	int	5_000_000	Longitud máxima de la entrada HTML en bytes. Las entradas que superan este límite lanzan un error antes de comunicarse con Chrome.
noSandbox	bool	false	Cuando es true, Chrome se inicia con la sandbox del sistema operativo deshabilitada. Es una vía de escape exclusiva para contenedores, con un costo de seguridad documentado.

La conversión del tiempo de espera a milisegundos y las marcas exactas de inicio de Chrome se verifican mediante tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand y ::getBrowserCreatesAndReusesInstanceWithExpectedOptions.

Construcción a partir de un array

En archivos de configuración al estilo de frameworks, ChromeRendererConfig::fromArray() mapea un array 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,
]);

Las claves ausentes usan los valores predeterminados del constructor. chrome_binary solo se aplica cuando es una cadena no vacía. Fuente: ChromeRendererConfig::fromArray().

Marcas fijas de inicio de Chrome

BrowserPool siempre inicia Chrome con estas marcas, independientemente de la configuración:

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

además de headless: true, keepAlive: true, windowSize: [1200, 800] y noSandbox de la configuración. No son ajustables por el usuario; son valores predeterminados de endurecimiento y estabilidad. El conjunto y el número exactos (8 marcas personalizadas) se verifican mediante tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu.

Elegir los valores

• renderTimeout: configurarlo por encima del documento más lento previsto. Cuando se agota el tiempo de espera, se manifiesta como una ChromeRenderException. Los tiempos de espera largos en una ruta expuesta al usuario constituyen una superficie de denegación de servicio; conviene combinar un tiempo de espera generoso con un presupuesto de solicitud en la capa superior. La protección de límites y los controles de agotamiento de recursos para entradas no confiables se tratan en la página /integrations/artisan/security-and-operations/. Esa página cita OWASP ASVS y el CWE Top 25 de 2025.
• maxHtmlSize: mantener el valor predeterminado a menos que una carga de trabajo conocida requiera más. El límite es la primera línea de defensa frente a entradas que agotan recursos; elevarlo amplía esa superficie.
• defaultCss: usarlo para fuentes y restablecimientos. No es una sandbox; se concatena en el bloque <style> del documento envolvente tras la eliminación de </style>.
• noSandbox: dejarlo en false fuera de los contenedores. Consultar /integrations/artisan/security-and-operations/ para conocer el significado preciso y los límites de deshabilitarlo.

Casos límite y errores habituales

• ChromeRendererConfig es readonly; para cambiar un valor, hay que construir una nueva instancia. No hay setter.
• renderTimeout es un int de segundos; la precisión por debajo del segundo no puede representarse.
• Si un valor de defaultCss contiene </style> (en cualquier combinación de mayúsculas y minúsculas), esas etiquetas de cierre se eliminan antes de ensamblar el documento (verificado por ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss). Tenerlo en cuenta si el CSS se genera a partir de plantillas.

Notas de seguridad

noSandbox y maxHtmlSize son relevantes para la seguridad. Su contexto de amenazas y la declaración explícita de qué protege y qué no protege la sandbox de Chrome están en la página /integrations/artisan/security-and-operations/. Esta página documenta la superficie; esa página documenta el límite.

Véase también

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