NextPDF Gotenberg'i yapılandırma

Bir bakışta

Yapılandırma iki bölümden oluşur: hizmeti ve sınırlarını tanımlayan değişmez GotenbergConfig değer nesnesi ve HTTP’ye yönelik PSR bağımlılıklarını alan GotenbergBridge yapıcısı. Her ikisini de açık yapıcı enjeksiyonuyla sağlarsınız. Paket global durum tutmaz; ortam değişkenlerini okumaz ve gizli bir varsayılan uç nokta tanımlamaz.

Yapılandırma nesnesi

GotenbergConfig, bir final readonly değer nesnesidir. Doğrudan adlandırılmış bağımsız değişkenlerle veya GotenbergConfig::fromArray() ile ilişkisel bir diziden oluşturun.

Alanlar

Alan	Tür	Varsayılan	Etki
apiUrl	string	''	Gotenberg hizmetinin temel URL’si. Zorunludur: boş bir değer yapılandırmayı geçersiz kılar ve her dönüştürmenin hızlı biçimde başarısız olmasına neden olur. HTTPS kullanmalıdır.
timeout	int	30	Saniye cinsinden katı aktarım zaman aşımı. Seçilirse cURL sabitlemeli aktarım bunu uygular.
maxFileSize	int	52_428_800	Bayt cinsinden izin verilen en yüksek giriş boyutu (50 MiB). Daha büyük girişler, herhangi bir istek gönderilmeden önce reddedilir.
apiKey	string	''	Bearer belirteci. Boş değilse, Authorization: Bearer <token> başlığı olarak gönderilir. Yığın izlerinde gizlenebilmesi için #[\SensitiveParameter] olarak işaretlenmiştir.
pinnedPublicKeys	list<string>	[]	Birincil TLS SubjectPublicKeyInfo (SPKI) sabitlemeleri; sha256/<base64> biçimindedir. Boş değer sabitlemeyi devre dışı bırakır.
backupPublicKeys	list<string>	[]	Rotasyonun bağımsız doğrulanabilmesi için ayrı tutulan yedek TLS SPKI sabitlemeleri.

Doğrudan oluşturma

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    maxFileSize: 20 * 1024 * 1024,
    apiKey: $secretFromYourSecretStore,
);

Bir diziden oluşturma

fromArray(), snake_case anahtarları kabul eder ve hatalı biçimli değerler için özel durum oluşturmak yerine bunları yok sayar. Dize olmayan bir api_url değeri '' olarak alınır. Tamsayı olmayan bir timeout değeri 30 varsayılanına döner. Tamsayı olmayan bir max_file_size değeri 50 MiB varsayılanına döner. Dizi olmayan sabitleme listeleri [] olur. Sabitleme dizilerindeki dize olmayan girişler atılır.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergConfig;

$config = GotenbergConfig::fromArray([
    'api_url' => 'https://gotenberg.example.com',
    'timeout' => 45,
    'max_file_size' => 20_000_000,
    'api_key' => $secretFromYourSecretStore,
    'pinned_public_keys' => ['sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg='],
    'backup_public_keys' => ['sha256/Vjs8r4z+80wjNcr1YKepWQboSIRi63WsWXhIMN+eWys='],
]);

Bu toleranslı ayrıştırma bilinçli bir tercihtir. Bir çerçeve yapılandırma dizisini ön doğrulama katmanı olmadan doğrudan geçirebilir ve yine de doğru türlenmiş bir nesne elde edebilirsiniz. URL’ye erişilebilir olduğunu veya sabitlemelerin doğru olduğunu doğrulamaz. Köprü, bu denetimleri dönüştürme sırasında gerçekleştirir.

Geçerlilik

isValid(), true değerini yalnızca apiUrl boş olmayan bir dize olduğunda döndürür. Ağ veya şema denetimi gerçekleştirmez. Güvenlik ilkesi, HTTPS’i ve özel adres taramasını dönüştürme sırasında yönetir. Yapılandırma geçersizse, convertFile() ve convertString() bir GotenbergConvertException oluşturur; iletisi Invalid Gotenberg configuration: apiUrl is empty şeklindedir. Geçersiz bir yapılandırma ayrıca isAvailable() işlevinin, herhangi bir ağ çağrısı yapmadan false döndürmesine neden olur.

Köprü yapıcısı

GotenbergBridge, yapılandırmayı ve PSR bağımlılıklarını alır:

Bağımsız değişken	Tür	Zorunlu	Etki
config	GotenbergConfig	evet	Yukarıda açıklanan hizmet tanımlayıcısı ve sınırları.
httpClient	Psr\Http\Client\ClientInterface	evet	Sağlık yoklaması ve yedek aktarım için kullanılan PSR-18 istemcisi.
requestFactory	Psr\Http\Message\RequestFactoryInterface	evet	PSR-7 isteğini oluşturur.
streamFactory	Psr\Http\Message\StreamFactoryInterface	evet	İstek gövdesi akışını oluşturur.
logger	Psr\Log\LoggerInterface|null	hayır (varsayılan null)	Sağlandığında, her dönüştürme isteği için debug düzeyinde bir günlük girdisi yazar.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	hayır	Varsayılan olarak çekirdek HTML güvenlik ilkesini kullanır. Ayrıştırma katmanında uygulanır ve aktarım katmanı ilkesini tamamlar.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	hayır (varsayılan null)	cURL sabitlemeli aktarımı etkinleştirmek için gereklidir. Bu olmadan köprü her zaman enjekte edilen PSR-18 istemcisini kullanır.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    logger: $psrLogger,
    responseFactory: $psrResponseFactory,
);

Aktarım seçimi

Köprü iki aktarımı destekler ve her dönüştürme isteği için birini seçer:

• cURL sabitlemeli aktarım — bir responseFactory enjekte edildiğinde ve sabitlenecek bir şey olduğunda (URL bir veya daha fazla IP adresine çözümlendiğinde ya da SPKI sabitlemeleri yapılandırıldığında) kullanılır. Bu aktarım, çözümlenen adres kümesini CURLOPT_RESOLVE ile bağlar. Sabitlemeler mevcut olduğunda, SPKI sabitlemesini CURLOPT_PINNEDPUBLICKEY ile zorunlu kılar. Eş sertifikayı ve ana bilgisayar adını doğrular (CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2). Yapılandırılan zaman aşımını uygular ve yeniden yönlendirmeyi izlemeyi devre dışı bırakır (CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0).
• Enjekte edilen PSR-18 istemcisi — diğer her durumda kullanılır; API URL’sinin salt bir genel IP değişmezi olduğu (sabitlenecek DNS bulunmayan) ve hiçbir SPKI sabitlemesinin yapılandırılmadığı durumlar ya da hiçbir responseFactory sağlanmadığı durum dâhil.

DNS yeniden bağlamasına dayanıklı bağlantılar ve TLS sabitlemesi için bir responseFactory enjekte edin ve sabitlemeleri yapılandırın. Sağlık yoklaması, aktarım seçiminden bağımsız olarak her zaman enjekte edilen PSR-18 istemcisini kullanır.

TLS ortak anahtar sabitlemesi

Sabitleme, 256 bitlik SHA-256 SPKI parmak izi modelini kullanır. Her sabitleme, sha256/<base64-encoded-spki-hash> biçiminde bir dizedir. Aktarım ayrıca cURL’ye özgü sha256//<base64> biçimini de kabul eder ve tek eğik çizgili biçimi buna dönüştürür. Bunun dışındaki herhangi bir ön ek bir InvalidSpkiPinException oluşturur.

allPublicKeyPins(), pinnedPublicKeys ve backupPublicKeys öğelerinin yinelenenlerden arındırılmış birleşimini döndürür. TLS katmanı, SPKI karması bu birleşik kümenin herhangi bir üyesiyle eşleşen bir sertifikayı kabul eder. Operasyonel açıdan, planlı bir sertifika veya anahtar rotasyonunun, yeni anahtar yayılırken köprünün hizmete erişimini kilitlememesi için en az bir yedek sabitleme yapılandırın. Yedek listeyi birincil listeden ayrı tutmak, yedek sabitlemeyi etkin olandan bağımsız olarak doğrulamanıza ve değiştirmenize olanak tanır. Rotasyon yordamı için bkz. /integrations/gotenberg/security-and-operations/.

İstek başına dönüştürme seçenekleri

Çok parçalı yük türü (GotenbergConvertPayload), dosyayı ve iki isteğe bağlı Gotenberg dönüştürme seçeneğini taşır:

• landscape (bool, varsayılan false) — landscape form alanı olarak "true" veya "false" değeriyle gönderilir.
• nativePageRanges (string, varsayılan '') — yalnızca boş olmadığında bir nativePageRanges form alanı olarak gönderilir; Gotenberg’in 1-3 veya 1,3,5-9 gibi aralık söz dizimini kabul eder.

Genel convertFile() ve convertString() giriş noktaları, yükü her iki alan için varsayılan değerlerle oluşturur. Bu alanlar yük sözleşmesinin bir parçasıdır ve test paketi bunları kapsar. Yatay çıktıya veya sayfa seçimine ihtiyacınız varsa bunları tümleştirme katmanınızdan açığa çıkarın.

Ayrıca bkz.

• /integrations/gotenberg/install/ — kurulum ve temel Gotenberg yapılandırması.
• /integrations/gotenberg/quickstart/ — uçtan uca çalıştırılabilir bir örnek.
• /integrations/gotenberg/production-usage/ — yapılandırma kaynağı, gizli değerler, zaman aşımları, yeniden denemeler.
• /integrations/gotenberg/security-and-operations/ — eksiksiz güvenlik modeli ve sabitleme rotasyonu.
• /integrations/gotenberg/troubleshooting/ — yapılandırmayla ilgili özel durumların anlamları.