Konfigurasi NextPDF Gotenberg

Sekilas pandang

Konfigurasi terdiri atas dua bagian: objek nilai (value object) immutable GotenbergConfig, yang mendeskripsikan layanan beserta batasannya, dan konstruktor GotenbergBridge, yang menerima kolaborator PHP Standard Recommendation (PSR) untuk Hypertext Transfer Protocol (HTTP). Anda menyediakan keduanya melalui injeksi konstruktor secara eksplisit. Paket ini tidak memiliki status global, tidak membaca variabel lingkungan apa pun, dan tidak mendefinisikan endpoint standar tersembunyi.

Objek konfigurasi

GotenbergConfig adalah objek nilai final readonly. Buat objek ini secara langsung dengan named argument, atau bangun dari array asosiatif menggunakan GotenbergConfig::fromArray().

Bidang

Bidang	Tipe	Standar	Efek
apiUrl	string	''	Base Uniform Resource Locator (URL) untuk layanan Gotenberg. Wajib: nilai kosong membuat konfigurasi tidak valid dan setiap konversi langsung gagal. Harus menggunakan Hypertext Transfer Protocol Secure (HTTPS).
timeout	int	30	Batas waktu transfer keras dalam detik. Transport cURL-pinned menerapkannya saat dipilih.
maxFileSize	int	52_428_800	Ukuran input maksimum dalam byte (50 MiB). Input yang lebih besar dari batas ini ditolak sebelum permintaan apa pun dibuat.
apiKey	string	''	Token Bearer. Jika tidak kosong, token ini dikirim sebagai header Authorization: Bearer <token>. Ditandai #[\SensitiveParameter] sehingga disensor dalam stack trace.
pinnedPublicKeys	list<string>	[]	Pin Transport Layer Security (TLS) SubjectPublicKeyInfo (SPKI) primer dalam bentuk sha256/<base64>. Nilai kosong menonaktifkan pinning.
backupPublicKeys	list<string>	[]	Pin TLS SPKI cadangan, dipisahkan agar rotasi dapat divalidasi secara independen.

Mengonstruksi secara langsung

<?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,
);

Mengonstruksi dari array

fromArray() menerima kunci snake_case dan mengabaikan nilai yang tidak valid alih-alih melempar eksepsi. api_url non-string menjadi ''. timeout non-int kembali ke 30. max_file_size non-int kembali ke nilai standar 50 MiB. Daftar pin non-array menjadi []. Entri non-string di dalam array pin akan dibuang.

<?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='],
]);

Penguraian yang toleran ini disengaja. Anda dapat meneruskan array konfigurasi framework secara langsung, tanpa lapisan validasi awal, dan tetap memperoleh objek dengan tipe yang benar. Penguraian ini tidak memverifikasi bahwa URL dapat dijangkau atau bahwa pin sudah benar. Bridge melakukan pemeriksaan tersebut saat konversi.

Validitas

isValid() mengembalikan true hanya jika apiUrl adalah string yang tidak kosong. Metode ini tidak melakukan pemeriksaan jaringan maupun skema. Kebijakan keamanan menangani HTTPS dan penyaringan alamat privat saat konversi. Jika konfigurasi tidak valid, convertFile() dan convertString() melempar GotenbergConvertException dengan pesan Invalid Gotenberg configuration: apiUrl is empty. Konfigurasi yang tidak valid juga membuat isAvailable() mengembalikan false tanpa panggilan jaringan apa pun.

Konstruktor bridge

GotenbergBridge menerima konfigurasi beserta kolaborator PSR:

Argumen	Tipe	Wajib	Efek
config	GotenbergConfig	ya	Deskriptor layanan dan batasan yang dijelaskan di atas.
httpClient	Psr\Http\Client\ClientInterface	ya	Klien PSR-18 yang digunakan untuk health probe dan transport cadangan.
requestFactory	Psr\Http\Message\RequestFactoryInterface	ya	Membangun permintaan PSR-7.
streamFactory	Psr\Http\Message\StreamFactoryInterface	ya	Membangun stream badan permintaan.
logger	Psr\Log\LoggerInterface|null	tidak (standar null)	Jika disediakan, mencatat satu entri tingkat debug per permintaan konversi.
htmlSecurityPolicy	HtmlSecurityPolicyInterface|null	tidak	Standarnya adalah kebijakan keamanan Hypertext Markup Language (HTML) inti. Berlaku pada lapisan parse dan melengkapi kebijakan lapisan transport.
responseFactory	Psr\Http\Message\ResponseFactoryInterface|null	tidak (standar null)	Diperlukan untuk mengaktifkan transport cURL-pinned. Tanpa itu, bridge selalu menggunakan klien PSR-18 yang diinjeksikan.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

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

Pemilihan transport

Bridge mendukung dua transport dan memilih salah satunya untuk setiap permintaan konversi:

• Transport cURL-pinned — digunakan saat sebuah responseFactory diinjeksikan dan ada sesuatu yang dapat di-pin (URL teresolusi ke satu atau lebih alamat Internet Protocol (IP), atau pin SPKI telah dikonfigurasi). Transport ini mengikat himpunan alamat yang teresolusi dengan CURLOPT_RESOLVE. Transport ini memberlakukan pinning SPKI dengan CURLOPT_PINNEDPUBLICKEY saat pin tersedia. Transport ini memverifikasi peer dan host (CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST = 2). Transport ini menerapkan batas waktu yang dikonfigurasi dan menonaktifkan pengikutan redirect (CURLOPT_FOLLOWLOCATION = false, CURLOPT_MAXREDIRS = 0).
• Klien PSR-18 yang diinjeksikan — digunakan dalam semua kasus lainnya, termasuk saat URL application programming interface (API) berupa literal IP publik polos (tidak ada Domain Name System (DNS) untuk di-pin) dan tidak ada pin SPKI yang dikonfigurasi, atau saat tidak ada responseFactory yang disediakan.

Untuk koneksi yang tahan terhadap DNS rebinding dan menggunakan pinning TLS, injeksikan sebuah responseFactory dan konfigurasikan pin. Health probe selalu menggunakan klien PSR-18 yang diinjeksikan, terlepas dari pemilihan transport.

Pinning kunci publik TLS

Pinning menggunakan model fingerprint SPKI Secure Hash Algorithm 256-bit (SHA-256). Setiap pin adalah string berbentuk sha256/<base64-encoded-spki-hash>. Transport juga menerima bentuk cURL-native sha256//<base64> dan mengonversi bentuk garis miring tunggal menjadi bentuk tersebut. Setiap prefiks lain memunculkan InvalidSpkiPinException.

allPublicKeyPins() mengembalikan gabungan tanpa duplikat dari pinnedPublicKeys dan backupPublicKeys. Lapisan TLS menerima sertifikat yang hash SPKI-nya cocok dengan salah satu anggota himpunan gabungan tersebut. Untuk keperluan operasional, konfigurasikan minimal satu pin cadangan agar rotasi sertifikat atau kunci yang terencana tidak membuat bridge terkunci dari layanan selama kunci baru menyebar. Memisahkan daftar cadangan dari daftar primer memungkinkan Anda memvalidasi dan merotasi pin cadangan secara independen dari pin yang aktif. Lihat /integrations/gotenberg/security-and-operations/ untuk prosedur rotasi.

Opsi konversi per permintaan

Tipe payload multipart (GotenbergConvertPayload) membawa berkas beserta dua opsi konversi Gotenberg opsional:

• landscape (bool, standar false) — dikirim sebagai bidang formulir landscape dengan "true" atau "false".
• nativePageRanges (string, standar '') — dikirim sebagai bidang formulir nativePageRanges hanya saat tidak kosong; menerima sintaks rentang Gotenberg, seperti 1-3 atau 1,3,5-9.

Titik masuk publik convertFile() dan convertString() membangun payload dengan nilai standar untuk kedua bidang. Bidang-bidang ini merupakan bagian dari kontrak payload, dan rangkaian pengujian mencakupnya. Ekspos keduanya dari lapisan integrasi Anda jika Anda memerlukan keluaran lanskap atau pemilihan halaman.

Lihat juga

• /integrations/gotenberg/install/ — instalasi dan baseline Gotenberg.
• /integrations/gotenberg/quickstart/ — contoh ujung ke ujung yang dapat dijalankan.
• /integrations/gotenberg/production-usage/ — pengambilan konfigurasi, rahasia, batas waktu, percobaan ulang.
• /integrations/gotenberg/security-and-operations/ — model keamanan lengkap dan rotasi pin.
• /integrations/gotenberg/troubleshooting/ — makna eksepsi terkait konfigurasi.