Menginstal NextPDF Gotenberg

Gambaran umum

Menginstal bridge terdiri atas dua bagian: paket PHP beserta dependensi HTTP PHP Standard Recommendation (PSR)-nya, yang diinstal dengan Composer, dan layanan Gotenberg yang dipanggil oleh paket tersebut. Bridge mengonversi berkas dengan mengirimkan pekerjaan ke layanan tersebut, sehingga bridge tidak dapat mengonversi apa pun sampai instance Gotenberg dapat dijangkau.

Selesaikan kedua bagian sebelum Anda menulis kode konversi.

Persyaratan

Persyaratan	Batasan	Alasan
PHP	>=8.4 <9.0	Dideklarasikan oleh paket di composer.json.
NextPDF core	^3.0	Dideklarasikan sebagai dependensi langsung di composer.json.
Klien HTTP PSR-18	^1.0	Bridge mengirim permintaan melalui Psr\Http\Client\ClientInterface yang disuntikkan.
Factory HTTP PSR-17	^1.1	Bridge membangun permintaan dan stream dengan factory PSR-17 yang disuntikkan.
Logger PSR-3	^3.0 (opsional)	Anda dapat menyuntikkan logger untuk pencatatan debug di tingkat permintaan.
Layanan Gotenberg	Dapat dijangkau melalui HTTPS	Layanan eksternal yang melakukan konversi; paket ini tidak melakukannya sendiri.

Bridge tidak menyertakan klien PSR-18 maupun factory PSR-17. Pilih implementasi yang sesuai dengan aplikasi Anda. Misalnya, pasangkan klien berbasis Guzzle dengan factory PSR-17 pendampingnya, atau gunakan klien HTTP Symfony dengan nyholm/psr7. Implementasi apa pun yang sesuai dengan kontrak PSR terkait akan berfungsi karena bridge bergantung pada antarmuka, bukan pada pustaka tertentu.

Langkah 1 — instal paket

Tambahkan paket dengan Composer:

composer require nextpdf/gotenberg

Composer menyelesaikan dependensi nextpdf/core ^3.0 dan kontrak HTTP PSR: psr/http-client, psr/http-factory, dan psr/log. Composer tidak menginstal klien HTTP konkret.

Langkah 2 — instal klien PSR-18 dan factory PSR-17

Instal satu klien PSR-18 dan satu set factory PSR-17 yang sesuai. Jika menggunakan Guzzle:

composer require guzzlehttp/guzzle guzzlehttp/psr7

Atau, jika menggunakan klien HTTP Symfony dan Nyholm PSR-7:

composer require symfony/http-client nyholm/psr7

Teruskan implementasi ini ke konstruktor bridge. Bridge tidak pernah membangun klien HTTP sendiri. Anda memilih implementasinya saat merangkai bridge. Lihat /integrations/gotenberg/configuration/ untuk bentuk konstruktor dan /integrations/gotenberg/quickstart/ untuk contoh perangkaian yang lengkap.

Langkah 3 — siapkan layanan Gotenberg

Bridge memanggil rute konversi LibreOffice milik Gotenberg, jadi jalankan instance Gotenberg yang dapat dijangkau oleh bridge. Proyek upstream menerbitkan image container. Untuk pengembangan lokal, gunakan:

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Ini mengekspos Gotenberg pada port 3000 melalui HTTP biasa. Gunakan ini hanya untuk pengembangan lokal. Bridge mewajibkan HTTPS untuk URL application programming interface (API) yang dikonfigurasi dan menolak http:// biasa sebelum mengirim permintaan apa pun. Untuk apa pun yang melampaui eksperimen lokal, tempatkan Gotenberg di belakang reverse proxy atau service mesh yang melakukan terminasi Transport Layer Security (TLS), lalu arahkan bridge ke endpoint HTTPS. /integrations/gotenberg/security-and-operations/ membahas bentuk penerapan produksi, paparan jaringan, dan autentikasi.

Tag image yang ditampilkan di sini (gotenberg/gotenberg:8) adalah lini mayor Gotenberg upstream. README proyek ini dan baseline integrasi merujuk pada lini tersebut. Di lingkungan produksi, sematkan ke tag patch tertentu alih-alih mengikuti tag mayor yang berubah-ubah. Verifikasi juga jalur rute (/forms/libreoffice/convert, /health) terhadap versi Gotenberg yang Anda terapkan. Bridge mengasumsikan kedua jalur tersebut dan tidak membuat asumsi lain apa pun tentang layanan tersebut.

Langkah 4 — verifikasi perangkaian

Sampai di sini, paket dan klien HTTP telah terinstal, dan Gotenberg dapat dijangkau melalui HTTPS. Sebelum menjalankan konversi nyata, pastikan bridge dapat menjangkau layanan dengan probe kesehatan bawaan:

<?php

declare(strict_types=1);

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

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

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

if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable — check the URL, TLS, and network path.');
}

isAvailable() memvalidasi URL yang dikonfigurasi terlebih dahulu. Metode ini mengembalikan false untuk URL kosong, URL non-HTTPS, atau URL dengan alamat privat tanpa mengirim lalu lintas jaringan. Setelah itu, metode ini mengirim permintaan HEAD ke <apiUrl>/health dan melaporkan layanan sebagai tersedia ketika statusnya di bawah 500. Jika terjadi kesalahan jaringan, bridge menangkapnya dan melaporkan layanan sebagai tidak tersedia, alih-alih melempar exception.

Catatan versi

Dokumentasi ini menjelaskan paket pada lini ^3.0. Lini tersebut selaras dengan persyaratan composer.json dan matriks dukungan SECURITY.md, di mana 3.x didukung dan 2.x tidak. Referensi 0.x yang lebih lama di halaman skeleton dalam repositori mendahului lini 3.0. Batasan composer.json menggantikannya.

Lihat juga

• /integrations/gotenberg/overview/ — apa yang dilakukan bridge dan format apa saja yang dikonversinya.
• /integrations/gotenberg/configuration/ — setiap argumen konstruktor dan kolom konfigurasi.
• /integrations/gotenberg/quickstart/ — konversi pertama yang lengkap dan dapat dijalankan.
• /integrations/gotenberg/security-and-operations/ — cara mengoperasikan dependensi Gotenberg dengan aman.
• /integrations/gotenberg/boot-and-discovery/ — perangkaian otomatis framework.