Menyiapkan NextPDF dan merender PDF pertama Anda

NextPDF adalah pustaka PHP yang membuat berkas PDF (Portable Document Format). Dalam tutorial ini Anda memasangnya ke dalam folder kosong lalu merender dokumen satu halaman pertama Anda. Anda memerlukan sebuah terminal dan sekitar sepuluh menit.

Apa yang akan Anda bangun

Anda akan membangun sebuah proyek mungil yang berisi satu skrip, 01-hello.php. Skrip tersebut merender satu halaman dengan satu baris judul tebal dan satu paragraf. Skrip menyimpan hasilnya sebagai out/hello.pdf. Sepanjang prosesnya Anda mempelajari dua perintah yang memastikan instalasi Anda sehat.

Halaman ini mengajarkan satu jalur pemasangan: folder kosong ditambah paket mesin. Jalur lain juga ada, seperti adapter framework, renderer berbasis peramban, dan klien Python. Jalur-jalur tersebut berada di Instalasi dan Pilih jalur Anda. Anda tidak memerlukannya hari ini.

Langkah 1: Buat proyek dan pasang NextPDF

Composer adalah manajer paket untuk PHP. Composer mengunduh pustaka ke dalam proyek Anda dan menghasilkan sebuah autoloader. Autoloader adalah berkas PHP kecil yang menemukan kelas-kelas pustaka untuk Anda, sehingga Anda tidak pernah menulis daftar include yang panjang.

Buka terminal dan jalankan ketiga perintah ini:

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

Composer mencetak progres saat menyelesaikan dan mengunduh paket. Baris persisnya bervariasi tergantung versi Composer dan cache lokal Anda. Instalasi yang berhasil berakhir tanpa teks kesalahan dan tampak kurang lebih seperti ini:

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

Apa yang baru saja terjadi

Composer membuat tiga hal di dalam folder Anda. composer.json mencatat bahwa proyek Anda bergantung pada mesin. composer.lock mengunci versi persis yang dipasang, sehingga instalasi berikutnya menyelesaikan kode yang sama. Folder vendor/ menyimpan paket yang diunduh, termasuk vendor/autoload.php. Skrip Anda memuat satu berkas itu, dan setiap kelas mesin menjadi tersedia.

Composer juga memeriksa penyiapan PHP Anda selama instalasi. Mesin mendeklarasikan ekstensi PHP yang dibutuhkannya. Ekstensi adalah modul opsional yang tertanam di dalam PHP. Jika salah satunya hilang, Composer berhenti dan menyebutkan namanya alih-alih membiarkan Anda berakhir dengan instalasi yang rusak.

Langkah 2: Render PDF pertama Anda

Buat berkas bernama 01-hello.php di sebelah composer.json. Tempelkan program lengkap ini:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

$document->save(__DIR__ . '/out/hello.pdf');

echo "Wrote out/hello.pdf\n";

Jalankan:

php 01-hello.php

Anda akan melihat tepat satu baris:

Wrote out/hello.pdf

Buka out/hello.pdf di penampil PDF mana pun. Anda akan melihat baris judul tebal dengan paragraf di bawahnya, dan sebagian besar penampil menampilkan “Hello from NextPDF” di judul jendelanya.

Apa yang baru saja terjadi

Telusuri skrip dari atas ke bawah:

• require memuat autoloader Composer, sehingga kelas Document dapat ditemukan.
• @mkdir membuat folder out/. Tanda @ di depan membuat skrip tetap senyap ketika folder sudah ada, sehingga Anda dapat menjalankannya lagi.
• Document::createStandalone() mengembalikan dokumen baru. Metode ini dibuat untuk skrip baris perintah singkat persis seperti ini.
• setTitle() menetapkan judul dokumen, yang ditampilkan oleh penampil pada judul jendela.
• addPage() menambahkan satu halaman kosong dan menempatkan kursor di kiri atas.
• setFont() memilih keluarga font, gaya, dan ukuran dalam poin. Poin adalah satuan standar untuk ukuran font dalam cetakan. 'B' berarti tebal, dan '' berarti reguler. Keluarga bernama helvetica sudah bawaan, sehingga Anda tidak memerlukan berkas font.
• cell() menulis satu baris teks pada posisi kursor. Lebar 0 berarti “membentang hingga margin kanan”. newLine: true menggerakkan kursor ke bawah setelahnya, seperti menekan Enter.
• save() membangun PDF yang telah selesai dan menuliskannya ke disk.

Satu dokumen menghasilkan satu berkas. Ketika Anda memerlukan PDF kedua, buat dokumen baru alih-alih menggunakan kembali yang lama.

Langkah 3: Verifikasi penyiapan Anda

Dua pemeriksaan singkat memastikan instalasi ini akan terus berfungsi, bukan hanya untuk satu skrip.

Pertama, tampilkan daftar ekstensi yang dibawa PHP Anda:

php -m

Cari curl, gd, intl, mbstring, openssl, dan zlib dalam daftar tersebut. Mesin bergantung pada keenam ekstensi ini. Composer sudah memeriksanya pada Langkah 1, jadi semuanya seharusnya muncul.

Kedua, jalankan pemeriksaan kesehatan bawaan mesin:

vendor/bin/nextpdf doctor

Di Windows, panggil vendor\bin\nextpdf doctor sebagai gantinya. Perintah tersebut memeriksa versi PHP, ekstensi, folder sementara, dan konfigurasi Anda. Setiap pemeriksaan mencetak [OK], [WARN], atau [FAIL], diikuti satu putusan keseluruhan.

Apa yang baru saja terjadi

Baca blok Extensions terlebih dahulu. Enam baris [OK] bernama curl, gd, intl, mbstring, openssl, dan zlib berarti instalasi Anda siap untuk setiap tutorial yang mengikutinya.

Laporan tersebut juga mencantumkan kapabilitas mesin. Pada instalasi Core gratis, kapabilitas yang termasuk dalam paket komersial mencetak [FAIL] dengan pesan yang menyebutkan paket yang menyediakannya. Hal ini memang wajar di sini, dan dapat mengubah putusan keseluruhan menjadi UNHEALTHY meskipun penyiapan Core Anda baik-baik saja. Untuk tutorial-tutorial ini, blok Extensions adalah sinyal yang penting.

Jika ada yang tidak beres

Cocokkan gejala Anda dengan kasus-kasus umum berikut terlebih dahulu:

• composer: command not found berarti Composer tidak ada atau tidak berada pada PATH Anda. Pasang dari getcomposer.org, lalu ulangi Langkah 1.
• Failed opening required '.../vendor/autoload.php' berarti skrip berjalan di luar folder proyek, atau instalasi tidak selesai. Masuk ke folder dari Langkah 1 dan jalankan composer install.
• Jika Composer berhenti selama Langkah 1 dan menyebutkan ekstensi PHP yang hilang, aktifkan ekstensi tersebut di php.ini Anda. Konfirmasikan dengan php -m, lalu ulangi instalasi.
• Baris [FAIL] di blok Extensions milik doctor menyebutkan ekstensi PHP yang hilang. Aktifkan di php.ini, konfirmasikan dengan php -m, lalu jalankan doctor lagi. Baris [FAIL] kapabilitas yang menyebutkan paket komersial memang wajar pada instalasi Core dan tidak memerlukan tindakan di sini.

Untuk hal lainnya, mulailah dengan basis pengetahuan pemecahan masalah. Jika sebuah skrip memunculkan eksepsi, cari kelasnya di referensi kesalahan; sebagian besar kesalahan pemula muncul di bagian kesalahan umum.

Selanjutnya

Anda memiliki instalasi yang berfungsi dan berkas hasil render pertama Anda. Lanjutkan dengan Teks, font, dan dasar-dasar halaman untuk mengatur ukuran halaman, font bawaan, warna, dan perataan.