Panduan cepat NextPDF Gotenberg

Sekilas pandang

Panduan langkah demi langkah ini mengonversi satu berkas .docx menjadi Portable Document Format (PDF). Setelah selesai, Anda akan memiliki tiga hal: instans bridge yang berfungsi, koneksi layanan yang terverifikasi, dan sebuah PDF di disk. Program lengkap tersedia di repositori pada examples/convert-office-to-pdf.php. Cuplikan kode di bawah ini diambil dari program tersebut.

Tutorial ini dimulai dengan alur kerja yang paling sederhana. Topik produksi, termasuk pengambilan secret, percobaan ulang, batas waktu, dan observabilitas, dibahas di /integrations/gotenberg/production-usage/.

Sebelum memulai

Sebelum melanjutkan, pastikan tiga hal berikut:

1. Anda telah menjalankan composer require nextpdf/gotenberg, serta klien PHP Standards Recommendation (PSR)-18 dan factory PSR-17 telah terpasang. Lihat /integrations/gotenberg/install/.
2. Layanan Gotenberg dapat dijangkau melalui Hypertext Transfer Protocol Secure (HTTPS). Bridge menolak http:// biasa sebelum permintaan apa pun keluar dari proses.
3. Anda memiliki berkas contoh dalam salah satu format berikut: .docx, .xlsx, .pptx, .odt, .ods, atau .odp. Ekstensi lain akan gagal dengan ValueError.

Langkah 1 — deskripsikan layanan

GotenbergConfig adalah value object yang tidak dapat diubah (immutable). Setidaknya, ia memerlukan URL dasar HTTPS untuk layanan Gotenberg Anda:

use NextPDF\Gotenberg\GotenbergConfig;

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

Transport yang di-pin ke cURL menerapkan timeout sebagai batas waktu transfer dalam detik. Jika apiKey tidak kosong, bridge mengirimkannya sebagai Authorization: Bearer <token>. Biarkan apiKey kosong jika deployment Gotenberg Anda tidak memerlukan token.

Langkah 2 — hubungkan bridge

Berikan konfigurasi dan komponen PSR ke bridge. Injeksikan juga responseFactory untuk mengaktifkan transport cURL dengan pinning Domain Name System (DNS) dan Transport Layer Security (TLS):

use NextPDF\Gotenberg\GotenbergBridge;

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
    responseFactory: $responseFactory,
);

Bridge tidak pernah membuat klien Hypertext Transfer Protocol (HTTP) untuk Anda. Gunakan klien PSR-18 dan factory PSR-17 yang telah Anda pasang. Berkas contoh menunjukkan cara menyambungkan Guzzle di dalam komentar.

Langkah 3 — periksa ketersediaan

Periksa layanan sebelum Anda mengonversi berkas. Pemeriksaan ini memvalidasi URL tanpa lalu lintas jaringan, lalu mengirim permintaan HEAD ke <apiUrl>/health:

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

Untuk URL yang kosong, non-HTTPS, atau beralamat privat, maupun untuk kesalahan jaringan apa pun, isAvailable() mengembalikan false (tidak pernah melempar eksepsi). Status di bawah 500 dari /health berarti layanan tersedia.

Langkah 4 — konversi

Panggil convertFile() dengan path di disk. Bridge mengkanonikalisasi path untuk memblokir traversal. Bridge memetakan ekstensi ke format yang didukung, memeriksa ukuran dan nama berkas, lalu mengirim permintaan multipart ke <apiUrl>/forms/libreoffice/convert:

use NextPDF\Gotenberg\GotenbergConvertException;

try {
    $result = $bridge->convertFile('/path/to/report.docx');
} catch (GotenbergConvertException $e) {
    // Bad config, HTTP failure, non-200, wrong Content-Type, or non-PDF body.
    throw $e;
} catch (\RuntimeException $e) {
    // Non-HTTPS URL, private address, oversized input, or unsafe filename.
    throw $e;
} catch (\ValueError $e) {
    // Extension is not one of the six recognised Office formats.
    throw $e;
}

Untuk mengonversi byte yang sudah berada di memori, gunakan convertString(). Berikan nama berkas asli agar bridge dapat mendeteksi ekstensinya:

$pdf = $bridge->convertString($docxBytes, 'report.docx');

Langkah 5 — gunakan hasilnya

Hasilnya mencakup tiga hal: byte PDF, format sumber, dan pemeriksaan validitas:

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

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

\printf(
    "Converted %s (%d bytes)\n",
    $result->sourceFormat->value,
    $result->size(),
);

isValid() bernilai true ketika body tidak kosong dan diawali dengan %PDF. size() mengembalikan panjang dalam byte. Mulai titik ini, PDF tersebut adalah stream biasa yang dapat Anda berikan ke NextPDF untuk pemrosesan lanjutan.

Program lengkap

Program lengkap yang dapat dijalankan tersedia di examples/convert-office-to-pdf.php di repositori paket. Program ini mencakup penguraian argumen, konfigurasi berbasis environment, pemeriksaan kesehatan, penanganan kesalahan menyeluruh, dan langkah penulisan. Jalankan dengan:

GOTENBERG_URL=https://gotenberg.example.com \
php examples/convert-office-to-pdf.php report.docx report.pdf

Langkah selanjutnya

• /integrations/gotenberg/configuration/ — tinjau setiap opsi dan aturan pemilihan transport.
• /integrations/gotenberg/production-usage/ — tangani secret, percobaan ulang, batas waktu, pencatatan log, dan konkurensi.
• /integrations/gotenberg/troubleshooting/ — pahami setiap eksepsi yang dapat dilempar oleh kode ini dan artinya.
• /integrations/gotenberg/integration/ — jalankan pipeline rendering NextPDF melalui layanan ini.