Configure a ponte do Artisan para Chrome

Visão geral

ChromeRendererConfig é um objeto de valor imutável, final readonly, com cinco parâmetros no construtor. Use-o como a única superfície de configuração da ponte.

Superfície da API

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

Fonte: src/Artisan/ChromeRendererConfig.php.

Opções

Opção	Tipo	Padrão	Efeito
chromeBinaryPath	?string	null	Caminho absoluto para o binário do Chrome/Chromium. null usa o padrão de detecção automática do chrome-php/chrome.
renderTimeout	int	30	Máximo de segundos para uma única renderização. Usado tanto como o tempo limite de carregamento de conteúdo do setHtml quanto como o sendSyncDefaultTimeout do Chrome DevTools Protocol (CDP) (passado ao Chrome em milissegundos — renderTimeout * 1000).
defaultCss	string	''	Cascading Style Sheets (CSS) injetado no documento encapsulado antes do fragmento do usuário. Sequências </style> são removidas antes da injeção (defesa contra escape do bloco de estilo).
maxHtmlSize	int	5_000_000	Tamanho máximo da entrada Hypertext Markup Language (HTML) em bytes. Entradas acima desse limite lançam uma exceção antes que o Chrome seja contatado.
noSandbox	bool	false	Quando true, inicia o Chrome com o sandbox do sistema operacional (OS) desativado. É uma válvula de escape apenas para contêineres, com um custo de segurança documentado.

Os testes verificam a conversão do tempo limite para milissegundos e os flags exatos de inicialização do Chrome em tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand e ::getBrowserCreatesAndReusesInstanceWithExpectedOptions.

Construção a partir de um array

Use ChromeRendererConfig::fromArray() para mapear um array em snake-case a partir de arquivos de configuração no estilo de framework:

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

Chaves não definidas recorrem aos padrões do construtor. A chave chrome_binary só é aplicada quando seu valor é uma string não vazia. Fonte: ChromeRendererConfig::fromArray().

Flags de inicialização fixos do Chrome

BrowserPool sempre inicia o Chrome com estes flags, independentemente da configuração:

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

além de headless: true, keepAlive: true, windowSize: [1200, 800] e noSandbox definidos pela configuração. Esses valores não são ajustáveis pelo usuário; servem como padrões de reforço de segurança e estabilidade. Um teste verifica o conjunto e a contagem exatos (8 flags personalizados) em tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu.

Escolhendo valores

• renderTimeout — defina-o como um valor maior que o tempo esperado para o documento mais lento. Um tempo limite se manifesta como uma ChromeRenderException. Tempos limite longos em caminhos voltados ao usuário criam uma superfície de negação de serviço; combine um tempo limite generoso com um orçamento de requisições upstream. A página /integrations/artisan/security-and-operations/ discute proteção de fronteira e controles de esgotamento de recursos para entrada não confiável. Essa página cita o Application Security Verification Standard (ASVS) do Open Worldwide Application Security Project (OWASP) e o Common Weakness Enumeration (CWE) Top 25 de 2025.
• maxHtmlSize — mantenha o padrão, a menos que uma carga de trabalho conhecida precise de mais. O limite é a primeira linha de defesa contra entradas que esgotam recursos; aumentá-lo expande essa superfície.
• defaultCss — use-o para fontes e resets. O valor não é um sandbox; ele é concatenado ao bloco <style> do documento encapsulado depois da remoção de </style>.
• noSandbox — deixe-o como false fora de contêineres. Consulte /integrations/artisan/security-and-operations/ para o significado preciso e os limites de desativá-lo.

Casos extremos e pegadinhas

• ChromeRendererConfig é readonly; crie uma nova instância para alterar um valor. Não há setter.
• renderTimeout é um int em segundos; precisão de frações de segundo não é representável.
• Se um valor de defaultCss contiver </style> (em qualquer combinação de maiúsculas e minúsculas), essas tags de fechamento serão removidas antes da montagem do documento (verificado por ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss). Planeje-se considerando isso se você gerar CSS por template.

Notas de segurança

noSandbox e maxHtmlSize são relevantes para a segurança. A página /integrations/artisan/security-and-operations/ aborda o contexto de ameaça desses parâmetros e declara explicitamente o que o sandbox do Chrome protege e o que não protege. Esta página documenta a superfície; aquela página documenta a fronteira.

Consulte também

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