Integrasi NextPDF dengan Gotenberg

Sekilas pandang

Halaman ini menunjukkan cara menghubungkan jembatan dengan bagian lain aplikasi Anda. Pasang paketnya, hubungkan, lalu teruskan hasil konversi Portable Document Format (PDF) ke alur kerja pascapemrosesan NextPDF. Jembatan mengonversi dokumen Office menjadi PDF; alur kerja menangani semua tahap setelah konversi. Untuk memahami rancangan di balik penyusunan ini, lihat /integrations/gotenberg/boot-and-discovery/.

Pemasangan

composer require nextpdf/gotenberg

Memasang paket ini juga memasang nextpdf/core ^3.0 serta kontrak PHP Standards Recommendation (PSR) Hypertext Transfer Protocol (HTTP). Pasang klien PSR-18 dan factory PSR-17 sebagai paket terpisah. Jembatan hanya bergantung pada antarmuka, sehingga Anda bebas memilih pustaka konkret yang digunakan. Untuk langkah pemasangan lengkap, termasuk cara menjalankan layanan Gotenberg melalui Hypertext Transfer Protocol Secure (HTTPS), lihat /integrations/gotenberg/install/.

Penyusunan

Susun jembatan dari objek konfigurasi dan kolaborator PSR. Suntikkan juga response factory; ini mengaktifkan transport dengan pinning Domain Name System (DNS) dan pinning Transport Layer Security (TLS):

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: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

Jembatan mewajibkan HTTPS untuk URL yang dikonfigurasi. Ia menolak http:// biasa sebelum mengirim permintaan apa pun. Jalankan Gotenberg di belakang terminasi TLS, lalu arahkan jembatan ke endpoint HTTPS.

Binding container

Daftarkan tiga entri dalam container host Anda: GotenbergConfig yang dibuat dari sumber konfigurasi Anda, klien PSR-18 beserta factory PSR-17 Anda, dan GotenbergBridge yang disusun dari dependensi tersebut. Paket ini tidak menyertakan binding sendiri. Binding native untuk framework menjadi tanggung jawab paket integrasi framework khusus. Lihat /integrations/gotenberg/boot-and-discovery/.

Konfigurasi

Semua bidang deskriptor layanan dan batasnya berada di GotenbergConfig. Bidang ini mencakup URL application programming interface (API), timeout, batas ukuran, bearer token, dan pin TLS. Sebaliknya, opsi per permintaan, yaitu landscape dan nativePageRanges, berada pada tipe payload. /integrations/gotenberg/configuration/ mendokumentasikan setiap bidang, termasuk tipe, nilai standar, dan efeknya.

Memasukkan PDF hasil konversi ke alur kerja NextPDF

Alur menyeluruh yang umum:

1. Konversikan dokumen Office dengan convertFile() atau convertString().
2. Ambil $result->pdfData, yang berisi byte mentah PDF, lalu muat ke dalam dokumen NextPDF.
3. Terapkan pascapemrosesan, seperti penyusunan halaman, pemberian tanda air, konversi PDF/A, atau tanda tangan digital.

Langkah 3 menjadi tanggung jawab NextPDF, bukan jembatan. Paket nextpdf/premium menyediakan penandatanganan, profil PDF/A, dan pemberian tanda air. Pertahankan konversi dan pascapemrosesan sebagai tahap terpisah agar setiap kegagalan dapat didiagnosis secara tersendiri.

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Conversion-layer failure — handle per your retry policy.
    throw $e;
}

// $result->pdfData is now an ordinary PDF byte stream ready for
// NextPDF post-processing.

Dukungan untuk PDF Advanced Electronic Signatures (PAdES) pada edisi Pro hanya mencakup baseline B-B. Dukungan ini tidak menyediakan B-T, B-LT, atau B-LTA. Konversi dokumen melalui jembatan ini tidak menyiratkan adanya kemampuan timestamp atau validasi jangka panjang.

Smoke test

Setelah penyusunan, verifikasi integrasinya tanpa mengonversi dokumen sungguhan:

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

isAvailable() memvalidasi URL tanpa lalu lintas jaringan. Setelah itu, ia mengirim permintaan HEAD ke <apiUrl>/health. Berikutnya, konversi satu dokumen kecil yang sudah diketahui valid. Ini menguji seluruh jalur multipart ke <apiUrl>/forms/libreoffice/convert dan memvalidasi responsnya.

Titik masuk API publik

Permukaan publik yang digunakan oleh integrasi ini:

• GotenbergConfig — deskriptor layanan dan batas yang imutabel; fromArray() membangunnya dari array konfigurasi.
• GotenbergBridge::convertFile(string $path) — mengonversi berkas di disk.
• GotenbergBridge::convertString(string $bytes, string $fileName) — mengonversi byte yang tersimpan di memori.
• GotenbergBridge::isAvailable() — pemeriksaan kesiapan yang tidak melemparkan eksepsi.
• GotenbergConvertResult — membawa pdfData, sourceFormat, isValid(), dan size().
• GotenbergConvertException — tipe eksepsi pada lapisan konversi.

Kontrak lengkapnya tersedia di /integrations/gotenberg/configuration/ dan /integrations/gotenberg/troubleshooting/. Kontrak ini mencakup pemilihan transport dan katalog eksepsi.

Lihat juga

• /integrations/gotenberg/boot-and-discovery/ — alasan susunannya dibuat seperti ini.
• /integrations/gotenberg/quickstart/ — panduan konversi pertama.
• /integrations/gotenberg/production-usage/ — rahasia, percobaan ulang, timeout, observabilitas.
• /integrations/gotenberg/install/ — pemasangan paket dan layanan Gotenberg.