Artisan Chrome köprüsünü yapılandırma

Bir bakışta

ChromeRendererConfig, beş kurucu parametresi olan değiştirilemez bir final readonly değer nesnesidir. Köprü için tek yapılandırma yüzeyi olarak bunu kullanın.

API yüzeyi

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

Kaynak: src/Artisan/ChromeRendererConfig.php.

Seçenekler

Seçenek	Tür	Varsayılan	Etki
`chromeBinaryPath`	`?string`	`null`	Chrome/Chromium ikili dosyasının mutlak yolu. `null` değeri, `chrome-php/chrome` otomatik algılama varsayılanını kullanır.
`renderTimeout`	`int`	`30`	Tek bir işleme için izin verilen en yüksek süre (saniye). Hem `setHtml` içerik yükleme zaman aşımı hem de Chrome DevTools Protocol (CDP) `sendSyncDefaultTimeout` değeri olarak kullanılır (Chrome’a milisaniye cinsinden iletilir — `renderTimeout * 1000`).
`defaultCss`	`string`	`''`	Kullanıcı parçasından önce sarmalanmış belgeye eklenen Basamaklı Stil Sayfaları (Cascading Style Sheets, CSS). `</style>` dizileri ekleme öncesinde kaldırılır (style bloğundan kaçışı önlemeye yönelik savunma).
`maxHtmlSize`	`int`	`5_000_000`	Bayt cinsinden izin verilen en yüksek Hypertext Markup Language (HTML) girdi uzunluğu. Bu sınırı aşan girdiler için Chrome’a bağlanılmadan önce özel durum oluşturulur.
`noSandbox`	`bool`	`false`	Değeri `true` olduğunda Chrome, işletim sistemi (operating system, OS) korumalı alanı devre dışı bırakılarak başlatılır. Yalnızca kapsayıcılara özgü, belgelenmiş bir güvenlik bedeli bulunan kaçış noktasıdır.

Testler, zaman aşımının milisaniyeye dönüştürülmesini ve tam Chrome başlatma bayraklarını tests/Unit/Artisan/BrowserPoolTest.php::getBrowserPassesExactTimeoutMultipliedByThousand ve ::getBrowserCreatesAndReusesInstanceWithExpectedOptions içinde doğrular.

Bir diziden oluşturma

Çerçeve biçimli yapılandırma dosyalarında snake_case bir diziyi eşlemek için ChromeRendererConfig::fromArray() yöntemini kullanın:

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

Belirtilmeyen anahtarlar için kurucu varsayılanları kullanılır. chrome_binary anahtarı yalnızca değeri boş olmayan bir dize olduğunda uygulanır. Kaynak: ChromeRendererConfig::fromArray().

Sabit Chrome başlatma bayrakları

BrowserPool, yapılandırmadan bağımsız olarak Chrome’u her zaman bu bayraklarla başlatır:

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

Bunlara ayrıca yapılandırmadan gelen headless: true, keepAlive: true, windowSize: [1200, 800] ve noSandbox değerleri de eklenir. Bu değerler kullanıcı tarafından ayarlanamaz; sıkılaştırma ve kararlılık varsayılanları işlevi görür. Bir test, tam kümeyi ve sayıyı (8 özel bayrak) tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCustomFlagsContainsDisableGpu içinde doğrular.

Değerleri seçme

renderTimeout — beklenen en yavaş belgeden daha yüksek bir değere ayarlayın. Zaman aşımı bir ChromeRenderException olarak ortaya çıkar. Kullanıcıya açık yollarda uzun zaman aşımları bir hizmet reddi yüzeyi oluşturur; geniş bir zaman aşımını üst akış istek bütçesiyle birlikte kullanın. /integrations/artisan/security-and-operations/ sayfası, güvenilmeyen girdiler için sınır koruması ve kaynak tükenmesi denetimlerini ele alır. Aynı sayfa, Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) belgesine ve 2025 Common Weakness Enumeration (CWE) Top 25 listesine atıfta bulunur.
maxHtmlSize — bilinen bir iş yükü daha fazlasını gerektirmedikçe varsayılan değeri koruyun. Bu sınır, kaynak tükenmesine yol açabilecek girdilere karşı ilk savunma hattıdır; bu değeri yükseltmek o yüzeyi genişletir.
defaultCss — bunu yazı tipleri ve sıfırlamalar için kullanın. Bu değer bir korumalı alan değildir; sarmalanmış belgenin <style> bloğuna, </style> kaldırma işleminin ardından bitiştirilir.
noSandbox — kapsayıcılar dışında bunu false olarak bırakın. Bunu devre dışı bırakmanın kesin anlamı ve sınırları için /integrations/artisan/security-and-operations/ sayfasına bakın.

Uç durumlar ve püf noktaları

ChromeRendererConfig readonly niteliğindedir; bir değeri değiştirmek için yeni bir örnek oluşturun. Bir ayarlayıcı yoktur.
renderTimeout, saniye cinsinden bir int değeridir; saniyenin altındaki hassasiyet ifade edilemez.
Bir defaultCss değeri </style> içeriyorsa (büyük/küçük harf fark etmeksizin), bu kapanış etiketleri belge birleştirilmeden önce kaldırılır (ChromeSecurityPolicyTest::wrapHtmlStripsStyleClosingTagsFromDefaultCss tarafından doğrulanır). CSS’yi şablonluyorsanız buna göre planlayın.

Güvenlik notları

noSandbox ve maxHtmlSize güvenlik açısından önemlidir. /integrations/artisan/security-and-operations/ sayfası bunların tehdit bağlamını ele alır ve Chrome korumalı alanının neyi koruyup neyi korumadığını açıkça belirtir. Bu sayfa yapılandırma yüzeyini, o sayfa ise sınırı belgeler.

Ayrıca bkz.

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