Panduan pengembang Gotenberg

Sekilas

Paket Gotenberg mengirim konversi Portable Document Format (PDF) ke layanan eksternal. Dalam kode aplikasi, jaga agar batas layanan tetap eksplisit: validasi masukan, bangun payload, kirim permintaan, parse hasilnya, dan tangani kegagalan layanan.

Gunakan panduan ini saat Anda membangun alur kerja konversi office-ke-PDF, endpoint unggah, pemeriksaan kesehatan layanan, atau kebijakan transport di sekitar nextpdf/gotenberg.

Batasan arsitektur

Lapisan	Dimiliki oleh	Tanggung jawab	Jangan letakkan di sini
Unggahan atau sumber dokumen	Aplikasi	Otorisasi pemanggil, validasi sumber, dan pemilihan kebijakan konversi.	Penentuan endpoint layanan atau penyematan transport.
Deteksi format	nextpdf/gotenberg	Petakan ekstensi yang aman ke OfficeFormat.	Memercayai tipe media yang dideklarasikan tanpa validasi aplikasi.
Jembatan	nextpdf/gotenberg	Bangun permintaan multipart, panggil Gotenberg, dan parse respons PDF.	Kueri domain atau kebijakan penyimpanan.
Layanan Gotenberg	deployment	Konversi dokumen office menjadi PDF.	Otorisasi aplikasi Hypertext Preprocessor (PHP).
Mesin inti	nextpdf/nextpdf	Mengimpor atau menggabungkan data PDF hasil konversi bila diperlukan.	Konversi office.

Siklus hidup runtime

Tahap	Perilaku	Tindakan pengembang
Pembuatan konfigurasi	Endpoint application programming interface (API), timeout, ukuran maksimum, kunci API, dan pin dimuat dari konfigurasi.	Pastikan endpoint layanan dan token tetap berada di luar kode sumber.
Validasi masukan	Path berkas, ukuran berkas, nama berkas, ekstensi, dan keamanan Uniform Resource Locator (URL) diperiksa.	Tolak masukan yang tidak didukung sebelum Anda mengirimnya.
Konstruksi payload	GotenbergConvertPayload membangun data formulir multipart.	Pertahankan nama berkas asli hanya jika aman.
Permintaan layanan	Jembatan mengirim permintaan ke /forms/libreoffice/convert.	Konfigurasikan timeout dan kebijakan transport.
Penguraian hasil	GotenbergResponseParser::parse() mengembalikan byte PDF dan metadata.	Perlakukan respons non-PDF dan respons error sebagai kegagalan konversi.

Struktur aplikasi yang direkomendasikan

Path	Tujuan
app/Pdf/Conversion/*	Pembungkus aplikasi untuk GotenbergBridge.
app/Pdf/Uploads/*	Validasi unggahan, penyimpanan, dan kebijakan nama berkas.
app/Pdf/ConversionPolicy/*	Kebijakan ukuran, format, dan pemilihan layanan.
tests/Pdf/Conversion/*	Pengujian format, berkas, layanan, dan transport.

Pisahkan validasi berkas dari konversi. Layanan konversi Anda sebaiknya menerima masukan yang sudah terotorisasi, lalu tetap mengandalkan validasi paket sebagai lapisan pertahanan tambahan.

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

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

        return $result->pdfData;
    }
}

Pola konversi

Pola	API	Gunakan saat	Kendala
Konversi path berkas	GotenbergBridge::convertFile()	Dokumen sudah tersimpan di disk.	Path harus dapat dibaca dan disetujui oleh kebijakan.
Konversi byte dalam memori	GotenbergBridge::convertString()	Aplikasi Anda sudah memiliki byte dari unggahan atau object store.	Nama berkas tetap mengendalikan deteksi format.
Bangun payload secara langsung	GotenbergConvertPayload	Anda membutuhkan byte multipart untuk pengujian atau kode transport khusus.	Jaga agar pembuatan boundary tetap berada di luar masukan pengguna.
Parse respons secara langsung	GotenbergResponseParser::parse()	Panggilan Hypertext Transfer Protocol (HTTP) khusus tetap membutuhkan parser paket.	Anda harus meneruskan OfficeFormat yang diharapkan.

Kesehatan dan kesiapan

GotenbergBridge::isAvailable() adalah sinyal kesiapan, bukan satu-satunya perlindungan runtime Anda. Layanan dapat lolos pemeriksaan kesiapan, tetapi tetap gagal pada konversi berikutnya.

Pemeriksaan	Tujuan	Catatan operasional
Validitas konfigurasi	Mendeteksi endpoint API yang hilang.	Jalankan ini saat boot aplikasi atau pemeriksaan deployment.
Ketersediaan /health	Mendeteksi apakah layanan dapat dijangkau.	Gunakan ini untuk dasbor kesiapan.
Konversi fixture kecil	Mendeteksi perilaku LibreOffice yang rusak atau regresi layanan.	Jalankan ini dalam smoke test terjadwal, bukan di setiap permintaan.
Pemantauan timeout	Mendeteksi perilaku layanan yang lambat.	Lacak ini berdasarkan format dan ukuran berkas.

Titik ekstensi

Titik ekstensi	Gunakan untuk	Kendala
PHP Standard Recommendation (PSR)-18 ClientInterface	Perilaku klien HTTP khusus.	Harus mengikuti semantik respons dan eksepsi PSR-18.
Factory PSR-17	Pembuatan permintaan dan stream.	Diperlukan untuk konstruksi jembatan.
HtmlSecurityPolicyInterface	Kebijakan pada lapisan parse untuk masukan Hypertext Markup Language (HTML).	Melengkapi kebijakan keamanan Gotenberg.
ResponseFactoryInterface	Konstruksi respons transport cURL yang tersemat (pinned).	Diperlukan hanya saat Anda menggunakan jalur transport paket.
GotenbergSecurityPolicy	Validasi URL, ukuran berkas, nama berkas, dan pin.	Jaga agar otorisasi aplikasi tetap berada di luar lapisan ini.

Alur kerja pengembangan

1. Mulailah dengan convertString() dalam pengujian agar fixture tetap eksplisit.
2. Tambahkan convertFile() hanya setelah path filesystem berada dalam kendali.
3. Jaga agar ukuran berkas maksimum tetap di bawah batas layanan dan infrastruktur.
4. Gunakan isAvailable() untuk sinyal kesiapan, bukan sebagai pengganti penanganan error.
5. Catat nama berkas, format, ukuran, status, dan durasi. Jangan catat byte dokumen.
6. Tambahkan pengujian timeout dan mode kegagalan sebelum Anda mengekspos endpoint unggah.

Penanganan kegagalan

Kegagalan	Di mana seharusnya ditangani	Respons yang direkomendasikan
Ekstensi tidak didukung	Deteksi format.	Tolak sebelum Anda mengirim ke layanan.
Nama berkas tidak aman	Kebijakan keamanan.	Tolak dan normalisasikan kebijakan penamaan unggahan.
Berkas berukuran berlebih	Kebijakan unggahan dan validasi paket.	Tolak sebelum Anda membaca atau mengirim payload besar.
Gotenberg tidak tersedia	Batas jembatan.	Kembalikan error aplikasi yang dapat dicoba ulang bila sesuai.
Respons non-PDF	Parser respons.	Perlakukan sebagai kegagalan konversi dan catat status layanan.
Kegagalan validasi pin atau URL	Kebijakan transport.	Gagal secara tertutup dan beri tahu operator.

Nilai default yang aman

Aspek	Default	Kapan menimpa
Timeout	30 detik.	Naikkan hanya setelah Anda mengukur latensi layanan yang sesungguhnya.
Ukuran berkas maksimum	52,428,800 byte.	Turunkan untuk endpoint publik atau multi-tenant.
Kunci API	Kosong.	Setel untuk deployment Gotenberg privat.
Format yang didukung	docx, xlsx, pptx, odt, ods, odp.	Tambahkan format hanya jika OfficeFormat dan parser mendukungnya.
Set pin	Kosong.	Tambahkan pin dengan pin cadangan dan prosedur rotasi.

Daftar periksa pengujian

• Pengujian format mencakup ekstensi yang didukung dan yang tidak didukung.
• Pengujian berkas mencakup berkas yang hilang, berkas yang tidak dapat dibaca, berkas berukuran berlebih, dan nama berkas yang tidak aman.
• Pengujian layanan mencakup respons non-2xx, badan respons yang tidak valid, dan eksepsi transport.
• Pengujian keamanan mencakup URL layanan yang privat atau tidak valid saat kebijakan melarangnya.
• Pengujian timeout memastikan bahwa timeout yang dikonfigurasi diteruskan ke transport.
• Pengujian fixture memastikan dokumen contoh tetap kecil dan tidak sensitif.