Artisan-Chrome-Brücke konfigurieren

Auf einen Blick

ChromeRendererConfig ist ein unveränderliches final readonly Value Object mit fünf Konstruktorparametern. Es ist die einzige Konfigurationsschnittstelle für die Brücke.

API-Oberfläche

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

Quelle: src/Artisan/ChromeRendererConfig.php.

Optionen

Option	Typ	Standard	Wirkung
chromeBinaryPath	?string	null	Absoluter Pfad zur Chrome-/Chromium-Binärdatei. null überlässt die Auswahl standardmäßig der Auto-Erkennung von chrome-php/chrome.
renderTimeout	int	30	Maximale Dauer in Sekunden für einen einzelnen Rendervorgang. Wird sowohl als Timeout für das Laden des Inhalts durch setHtml als auch als CDP-sendSyncDefaultTimeout verwendet (Übergabe an Chrome in Millisekunden — renderTimeout * 1000).
defaultCss	string	''	CSS, das vor dem Benutzerfragment in das eingebettete Dokument eingefügt wird. </style>-Sequenzen werden vor dem Einfügen entfernt (Schutz vor dem Ausbruch aus dem Style-Kontext).
maxHtmlSize	int	5_000_000	Maximale HTML-Eingabelänge in Bytes. Eingaben darüber lösen einen Fehler aus, bevor Chrome kontaktiert wird.
noSandbox	bool	false	Wenn true, startet Chrome mit deaktivierter OS-Sandbox. Nur als Ausweichlösung für Container gedacht, mit dokumentiertem Sicherheitsrisiko.

Die Umrechnung des Timeouts in Millisekunden und die exakten Chrome-Startflags werden durch tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand und ::getBrowserCreatesAndReusesInstanceWithExpectedOptions abgesichert.

Konstruktion aus einem Array

Für typische Framework-Konfigurationsdateien bildet ChromeRendererConfig::fromArray() ein snake_case-Array ab:

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

Nicht gesetzte Schlüssel verwenden die Konstruktorstandardwerte. chrome_binary wird nur angewendet, wenn es ein nicht leerer String ist. Quelle: ChromeRendererConfig::fromArray().

Feste Chrome-Startflags

BrowserPool startet Chrome immer mit diesen Flags, unabhängig von der Konfiguration:

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

plus headless: true, keepAlive: true, windowSize: [1200, 800] und noSandbox aus der Konfiguration. Diese Werte sind nicht benutzerseitig einstellbar; es sind Härtungs- und Stabilitätsstandardwerte. Die genaue Menge und Anzahl (8 eigene Flags) wird durch tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu abgesichert.

Werte auswählen

• renderTimeout — setzen Sie ihn höher als die Laufzeit des langsamsten zu erwartenden Dokuments. Ein Timeout erscheint als ChromeRenderException. Lange Timeouts in einem benutzerseitig erreichbaren Ausführungspfad sind eine Denial-of-Service-Fläche; kombinieren Sie ein großzügiges Timeout mit einem vorgelagerten Anfragebudget. Grenzwerte und Kontrollen gegen Ressourcenerschöpfung für nicht vertrauenswürdige Eingaben werden auf der Seite /integrations/artisan/security-and-operations/ behandelt. Diese Seite zitiert OWASP ASVS und die CWE Top 25 von 2025.
• maxHtmlSize — behalten Sie den Standardwert bei, sofern eine bekannte Last nicht mehr erfordert. Das Limit ist die erste Verteidigungslinie gegen ressourcenerschöpfende Eingaben; eine Anhebung vergrößert diese Angriffsfläche.
• defaultCss — nutzen Sie es für Schriftarten und Resets. Es ist keine Sandbox; es wird an den <style>-Block des eingebetteten Dokuments angehängt, nachdem </style> entfernt wurde.
• noSandbox — lassen Sie false außerhalb von Containern. Siehe /integrations/artisan/security-and-operations/ für die genaue Bedeutung und die Grenzen der Deaktivierung.

Sonderfälle & Stolperfallen

• ChromeRendererConfig ist readonly; erstellen Sie eine neue Instanz, um einen Wert zu ändern. Es gibt keinen Setter.
• renderTimeout ist ein int in Sekunden; Genauigkeit im Subsekundenbereich ist nicht darstellbar.
• Bei einem defaultCss-Wert, der </style> (unabhängig von Groß-/Kleinschreibung) enthält, werden diese schließenden Tags entfernt, bevor das Dokument zusammengesetzt wird (abgesichert durch ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss). Planen Sie das ein, wenn Sie CSS per Template erzeugen.

Sicherheitshinweise

noSandbox und maxHtmlSize sind sicherheitsrelevant. Ihr Bedrohungskontext und die ausdrückliche Aussage darüber, was die Chrome-Sandbox schützt und was nicht, stehen auf der Seite /integrations/artisan/security-and-operations/. Diese Seite dokumentiert die Oberfläche; jene Seite dokumentiert die Grenze.

Siehe auch

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