Artisan Chrome ブリッジの構成

概要

ChromeRendererConfig は、5 個のコンストラクターパラメーターを持つイミュータブルな 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`	1 回のレンダリングに許容する最大秒数。`setHtml` のコンテンツ読み込みタイムアウトと、CDP の `sendSyncDefaultTimeout`（ミリ秒単位で Chrome に渡される — `renderTimeout * 1000`）の両方に使用される値。
`defaultCss`	`string`	`''`	ラップされたドキュメントで、ユーザーのフラグメントより前に挿入される CSS。`</style>` シーケンスは、挿入前に除去される仕様（スタイルブレイクアウト対策）。
`maxHtmlSize`	`int`	`5_000_000`	HTML 入力の最大長（バイト単位）。この上限を超える入力は、Chrome に接続される前に例外がスローされる仕様。
`noSandbox`	`bool`	`false`	指定が `true` の場合、OS サンドボックスを無効にして 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/ のページで説明しています。同ページでは、OWASP ASVS と 2025 CWE Top 25 を引用しています。
maxHtmlSize — 既知のワークロードでより大きな値が必要でない限り、デフォルト値のままにします。この上限は、リソース枯渇を狙う入力に対する第一の防御線です。値を上げると、その攻撃対象が広がります。
defaultCss — フォントやリセットに使用します。これはサンドボックスではありません。ラップされたドキュメントの <style> ブロックに、</style> の除去後に連結されます。
noSandbox — コンテナーの外では false のままにします。サンドボックスを無効にすることの正確な意味と制限については、/integrations/artisan/security-and-operations/ を参照してください。

エッジケースと注意点

ChromeRendererConfig は readonly です。値を変更するには、新しいインスタンスを構築します。セッターはありません。
renderTimeout は秒単位の int です。1 秒未満の精度は表現できません。
指定した defaultCss の値に </style>（大文字小文字を問わず）が含まれる場合、ドキュメントが組み立てられる前にそれらの終了タグが除去されます（ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss によって検証されます）。CSS をテンプレート化する場合は、この点を考慮して設計してください。

セキュリティに関する注意

noSandbox と maxHtmlSize は、セキュリティに関わる設定です。これらに関する脅威の文脈と、Chrome サンドボックスが保護するものと保護しないものの明示的な説明は、/integrations/artisan/security-and-operations/ のページに記載されています。本ページはインターフェイスを、同ページは境界を文書化しています。