Referensi API Gotenberg

Sekilas

Paket Gotenberg mengekspos satu service bridge, GotenbergBridge. Bridge ini mengonversi dokumen Office (docx, xlsx, pptx, odt, ods, odp) menjadi Portable Document Format (PDF) dengan mengirim permintaan POST ke layanan Gotenberg eksternal. Bridge ini bekerja dengan value object yang Anda kirim atau baca: GotenbergConfig (deskriptor layanan beserta batasannya yang bersifat immutable), OfficeFormat (enum format yang didukung), GotenbergConvertPayload (badan permintaan multipart), dan GotenbergConvertResult (respons PDF yang telah diurai). Lapisan kedua, GotenbergSecurityPolicy, GotenbergResponseParser, dan PinnedCurlTransport, menyediakan mesin validasi, penguraian, dan transport ber-pin yang dijalankan bridge secara internal. Gunakan lapisan tersebut hanya saat Anda menulis kode transport kustom atau kode pengujian.

Mulai di sini: Buat GotenbergConfig dengan URL layanan Hypertext Transfer Protocol Secure (HTTPS) Anda, lalu kirimkan ke GotenbergBridge bersama klien PSR-18 dan factory PSR-17 Anda. Panggil convertFile() atau convertString(), lalu baca pdfData dari GotenbergConvertResult yang dikembalikan.

Tugas umum

Gunakan cuplikan kode terverifikasi dan dapat dijalankan berikut untuk tugas paket yang paling mungkin Anda kerjakan.

Mengonversi berkas di disk menjadi PDF

Arahkan bridge ke path. Bridge mendeteksi formatnya dari ekstensi.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

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

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

$result = $bridge->convertFile('/path/to/report.docx');

\file_put_contents('/path/to/report.pdf', $result->pdfData);

Yang dilakukan: memvalidasi URL, path, ukuran, dan nama berkas; mengirim satu permintaan multipart; serta menuliskan byte PDF yang dikembalikan ke disk.

Mengonversi byte di memori menjadi PDF

Gunakan convertString() saat Anda sudah memiliki byte-nya. Nama berkas menentukan deteksi format.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
$result = $bridge->convertString($xlsxBytes, 'spreadsheet.xlsx');

if (! $result->isValid()) {
    throw new \RuntimeException('Conversion did not return a valid PDF.');
}

Yang dilakukan: mendeteksi xlsx dari nama berkas, mengonversi byte-nya, dan memastikan hasilnya diawali dengan tanda %PDF sebelum Anda menggunakannya.

Memeriksa kesiapan layanan sebelum mengonversi

Gunakan isAvailable() sebagai guard sebelum menjalankan pekerjaan. Metode ini memvalidasi URL tanpa lalu lintas jaringan, lalu mengirim satu permintaan HEAD ke /health.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

Yang dilakukan: mengembalikan false (tidak pernah melempar exception) untuk URL yang kosong, non-HTTPS, atau beralamat privat, serta untuk setiap kesalahan jaringan, sehingga Anda dapat gagal lebih awal sebelum mengirim permintaan konversi.

Bridge

Tabel ini mencakup antarmuka bridge. Gunakan saat Anda membangun GotenbergBridge atau memanggil metode konversi maupun pemeriksaan kesiapannya.

Simbol	Parameter	Perilaku standar	Mengembalikan	Melempar atau gagal dengan	Catatan
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	Config, klien PSR-18, factory PSR-17, logger opsional, kebijakan HTML opsional, response factory opsional.	Menggunakan `DefaultHtmlSecurityPolicy` saat Anda tidak menyuplai kebijakan.	`GotenbergBridge`	Kesalahan pemasangan container.	Response factory mengaktifkan transport cURL ber-pin saat pinning diperlukan.
`GotenbergBridge::convertFile(string $filePath)`	Path filesystem ke dokumen Office.	Menggunakan ekstensi berkas untuk deteksi format.	`GotenbergConvertResult`	`GotenbergConvertException`, `RuntimeException`, `ValueError` untuk format yang tidak didukung.	Melakukan resolve pada path sebenarnya dan memeriksa keterbacaan, ukuran, serta nama berkas.
`GotenbergBridge::convertString(string $content, string $fileName)`	Byte mentah dan nama berkas asli.	Menggunakan ekstensi nama berkas untuk deteksi format.	`GotenbergConvertResult`	Sama seperti `convertFile`.	Gunakan saat aplikasi Anda sudah memiliki byte berkas.
`GotenbergBridge::isAvailable()`	tidak ada.	Mengirim HEAD ke `/health` saat config valid.	`bool`	Mengembalikan `false` pada kesalahan.	Hanya digunakan sebagai sinyal kesiapan.
`GotenbergBridge::getHtmlSecurityPolicy()`	tidak ada.	Mengembalikan kebijakan lapisan penguraian yang dikonfigurasi.	`HtmlSecurityPolicyInterface`	tidak ada yang diharapkan.	Melengkapi kebijakan keamanan tingkat transport.

Konfigurasi dan payload

Tabel ini mencakup value object yang Anda bangun langsung: deskriptor layanan GotenbergConfig serta pembawa permintaan dan respons GotenbergConvertPayload/GotenbergConvertResult. Gunakan saat Anda memerlukan kontrol yang lebih rinci daripada yang disediakan kedua titik masuk konversi.

Simbol	Parameter	Perilaku standar	Mengembalikan	Melempar atau gagal dengan	Catatan
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	URL API, timeout, ukuran berkas maksimum, bearer token, kumpulan pin.	URL kosong tidak valid; ukuran maksimum standar adalah 50 MiB.	`GotenbergConfig`	tidak ada yang diharapkan.	Jaga kerahasiaan kunci API.
`GotenbergConfig::fromArray(array $config)`	`api_url`, `timeout`, `max_file_size`, `api_key`, array pin.	Nilai opsional yang tidak diberikan memakai nilai standar konstruktor.	`GotenbergConfig`	tidak ada yang diharapkan.	Daftar string mengabaikan nilai non-string.
`GotenbergConfig::isValid()`	tidak ada.	Valid jika URL API tidak kosong.	`bool`	tidak ada yang diharapkan.	Keamanan URL divalidasi sebelum operasi jaringan apa pun.
`GotenbergConfig::allPublicKeyPins()`	tidak ada.	Menggabungkan pin utama dan cadangan.	`list<string>`	tidak ada yang diharapkan.	Daftar kosong menonaktifkan pinning.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	Nama berkas, byte, format, flag orientasi, rentang halaman.	Potret; semua halaman.	`GotenbergConvertPayload`	tidak ada yang diharapkan.	Payload dikonversi menjadi data formulir multipart.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	Pembatas multipart.	Menyertakan field rentang halaman hanya jika field tersebut tidak kosong.	`string`	tidak ada yang diharapkan.	Bridge menghasilkan pembatas.
`GotenbergConvertPayload::contentType(string $boundary)`	Pembatas multipart.	Menggunakan `multipart/form-data`.	`string`	tidak ada yang diharapkan.	Lampirkan sebagai `Content-Type` permintaan.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	Byte PDF hasil konversi, format sumber, durasi render opsional.	Durasi render adalah `0.0` saat tidak diukur.	`GotenbergConvertResult`	tidak ada yang diharapkan.	Dikembalikan oleh `GotenbergResponseParser::parse()`.
`GotenbergConvertResult::isValid()`	tidak ada.	Valid jika byte PDF hasil konversi tidak kosong dan terlihat seperti data PDF.	`bool`	tidak ada yang diharapkan.	Periksa sebelum menyimpan secara permanen atau melakukan stream pada hasil.
`GotenbergConvertResult::size()`	tidak ada.	Menghitung byte PDF hasil konversi.	`int`	tidak ada yang diharapkan.	Gunakan untuk kuota, telemetri, dan batasan respons.

Format Office

Tabel ini mencakup enum OfficeFormat. Gunakan untuk memetakan ekstensi ke format, membaca tipe MIME unggahannya, atau memeriksa mana dari keenam format yang didukung.

Simbol	Parameter	Perilaku standar	Mengembalikan	Melempar atau gagal dengan	Catatan
`OfficeFormat::fromExtension(string $ext)`	Ekstensi berkas dengan atau tanpa titik di depan.	Mencocokkan tanpa membedakan huruf besar/kecil.	`OfficeFormat`	`ValueError` untuk ekstensi yang tidak didukung.	Nilai yang didukung: `docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.
`OfficeFormat::mimeType()`	tidak ada.	Memetakan case enum ke tipe MIME unggahan.	`string`	tidak ada yang diharapkan.	Digunakan pada bagian berkas multipart.
`OfficeFormat::extension()`	tidak ada.	Mengembalikan nilai backing-nya.	`string`	tidak ada yang diharapkan.	Berguna dalam diagnostik dan nama berkas.

Keamanan, penguraian, dan transport

Tabel ini mencakup mesin internal yang dijalankan bridge untuk Anda. Gunakan hanya saat Anda menulis transport kustom, melakukan panggilan Hypertext Transfer Protocol (HTTP) kustom yang tetap memerlukan penguraian paket, atau memeriksa perilaku keamanan dan pinning tingkat rendah.

Simbol	Parameter	Perilaku standar	Mengembalikan	Melempar atau gagal dengan	Catatan
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	URL dasar API.	Menguraikan dan memvalidasi tujuan sebelum operasi jaringan apa pun.	`array`	`RuntimeException` untuk URL yang tidak aman atau tidak valid.	Menjauhkan kesalahan endpoint bergaya server-side request forgery (SSRF) dari kode konversi.
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	Host dan daftar Internet Protocol (IP) yang di-pin.	Memverifikasi ekspektasi pin Domain Name System (DNS).	`void`	`RuntimeException` saat pin usang atau tidak valid.	Gunakan dalam deployment ber-pin dan diagnostik operasional.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	Ukuran sebenarnya dan maksimum yang dikonfigurasi.	Menerima berkas pada atau di bawah batas yang dikonfigurasi.	`void`	`RuntimeException` saat berkas terlalu besar.	Tegakkan sebelum membangun permintaan.
`GotenbergSecurityPolicy::validateFileName(string $name)`	Nama berkas asli.	Menolak bentuk nama berkas yang tidak aman atau tidak didukung.	`void`	`RuntimeException` untuk nama yang tidak valid.	Mencegah nama berkas multipart yang cacat.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	Respons PSR-7 dan format Office yang diharapkan.	Mengekstrak byte PDF hasil konversi dari respons yang berhasil.	`GotenbergConvertResult`	`GotenbergConvertException` untuk respons yang gagal atau keluaran PDF yang tidak valid.	Parser utama untuk konversi berkas dan string.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	Factory PSR-17, IP yang di-pin, kunci publik yang di-pin, timeout.	Tanpa pin dan timeout 30 detik.	`PinnedCurlTransport`	tidak ada yang diharapkan.	Gunakan hanya saat pinning tingkat cURL diperlukan.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	Permintaan PSR-7.	Mengirim melalui cURL dengan timeout dan kontrol pinning yang dikonfigurasi.	`ResponseInterface`	`GotenbergConvertException` saat kegagalan cURL/transport.	Gunakan saat pinning tidak dapat didelegasikan ke klien HTTP lain.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	Permintaan, host, dan port.	Membangun array opsi cURL yang digunakan `sendRequest()`.	`array`	Kesalahan karena permintaan tidak valid atau konfigurasi pin.	Diagnostik tingkat rendah dan hook pengujian.

Catatan pengembangan

Perlakukan Gotenberg sebagai batas layanan eksternal. Tetapkan timeout, ukuran, URL, dan kebijakan pin dengan saksama.
convertFile() membaca seluruh berkas ke dalam memori sebelum konstruksi permintaan.
Catat metadata seperti nama berkas dan panjang konten, bukan isi berkas.