Конфигурация моста Artisan Chrome

Краткий обзор

ChromeRendererConfig — неизменяемый объект-значение final readonly с пятью параметрами конструктора. Используйте его как единую точку конфигурации моста.

Состав API

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

Источник: src/Artisan/ChromeRendererConfig.php.

Параметры

Параметр	Тип	По умолчанию	Действие
chromeBinaryPath	?string	null	Абсолютный путь к исполняемому файлу Chrome/Chromium. При значении null используется стандартное автоопределение из chrome-php/chrome.
renderTimeout	int	30	Максимальное количество секунд на одну отрисовку. Используется и как тайм-аут загрузки содержимого setHtml, и как sendSyncDefaultTimeout протокола Chrome DevTools Protocol (CDP) (передаётся в Chrome в миллисекундах — renderTimeout * 1000).
defaultCss	string	''	CSS-стили, внедряемые в обёрнутый документ перед пользовательским фрагментом. Последовательности </style> удаляются перед внедрением (защита от выхода за пределы блока стилей).
maxHtmlSize	int	5_000_000	Максимальная длина входного HTML в байтах. Если входные данные превышают это значение, исключение возникает до обращения к Chrome.
noSandbox	bool	false	При значении true запускает Chrome с отключённой песочницей операционной системы (ОС). Это запасной механизм только для контейнеров с задокументированной платой за безопасность.

Тесты проверяют преобразование тайм-аута в миллисекунды и точный набор флагов запуска Chrome в tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand и ::getBrowserCreatesAndReusesInstanceWithExpectedOptions.

Создание из массива

Используйте ChromeRendererConfig::fromArray(), чтобы преобразовать массив в стиле 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,
]);

Для незаданных ключей используются значения по умолчанию из конструктора. Ключ chrome_binary применяется только тогда, когда его значение — непустая строка. Источник: ChromeRendererConfig::fromArray().

Фиксированные флаги запуска Chrome

BrowserPool всегда запускает Chrome с этими флагами, независимо от конфигурации:

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

плюс headless: true, keepAlive: true, windowSize: [1200, 800] и noSandbox из конфигурации. Эти значения пользователь не настраивает; они заданы по умолчанию для повышения безопасности и стабильности. Тест проверяет точный набор и количество (8 пользовательских флагов) в tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu.

Выбор значений

• renderTimeout — задавайте его с запасом относительно самого медленного ожидаемого документа. Истечение тайм-аута проявляется как ChromeRenderException. Длинные тайм-ауты на путях, доступных пользователям, создают поверхность для атак типа “отказ в обслуживании”; сочетайте щедрый тайм-аут с вышестоящим бюджетом на запросы. На странице /integrations/artisan/security-and-operations/ рассматриваются защита границ и средства контроля исчерпания ресурсов для недоверенного ввода. На той же странице есть ссылки на Application Security Verification Standard (ASVS) проекта Open Worldwide Application Security Project (OWASP) и на Common Weakness Enumeration (CWE) Top 25 за 2025 год.
• maxHtmlSize — сохраняйте значение по умолчанию, если только известная рабочая нагрузка не требует большего. Этот предел — первая линия защиты от ввода, который исчерпывает ресурсы; его повышение расширяет эту поверхность.
• defaultCss — используйте его для шрифтов и сбросов стилей. Это значение не является песочницей; оно добавляется к блоку <style> обёрнутого документа после удаления </style>.
• noSandbox — оставляйте его false вне контейнеров. Точное значение и ограничения при его отключении см. на странице /integrations/artisan/security-and-operations/.

Граничные случаи и подводные камни

• ChromeRendererConfig является readonly; чтобы изменить значение, создайте новый экземпляр. Сеттера нет.
• renderTimeout — это int в секундах; точность менее секунды не представима.
• Если значение defaultCss содержит </style> (в любом регистре), эти закрывающие теги удаляются до сборки документа (это проверяется в ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss). Учитывайте это, если формируете CSS по шаблону.

Замечания по безопасности

noSandbox и maxHtmlSize важны для безопасности. На странице /integrations/artisan/security-and-operations/ рассматривается их контекст угроз и явно указано, что защищает песочница Chrome, а что — нет. Эта страница документирует состав параметров; та страница документирует границу.

См. также

• Установка — /integrations/artisan/install/
• Быстрый старт — /integrations/artisan/quickstart/
• Настройка рендерера Chrome — /integrations/artisan/chrome-renderer-setup/
• Безопасность и эксплуатация — /integrations/artisan/security-and-operations/
• Использование в продакшене — /integrations/artisan/production-usage/