Gambar, tabel, dan daftar

Teks saja jarang menghasilkan dokumen yang utuh. Dalam tutorial ini Anda menambahkan tiga elemen dasar sehari-hari: gambar, tabel, dan daftar berbutir. Anda menulis dua skrip kecil, dan masing-masing menghasilkan berkas PDF (Portable Document Format) sungguhan yang bisa langsung Anda buka.

Apa yang akan Anda bangun

01-image.php — PDF satu halaman dengan judul dan gambar persegi berwarna amber, ditempatkan pada titik yang tepat di halaman.
02-table-and-lists.php — PDF satu halaman dengan tabel kecil berisi buku dan daftar berbutir di bawahnya.

Kedua skrip merupakan program yang lengkap. Tetap gunakan folder proyek dari tutorial pertama dan simpan setiap skrip di samping composer.json.

Langkah 1: Tempatkan gambar pada halaman

Skrip ini membawa gambarnya sendiri. Sebuah gambar PNG (Portable Network Graphics) mungil berukuran 8 x 8 piksel disematkan di dalam skrip sebagai string Base64. Base64 adalah cara menuliskan data biner dalam bentuk teks biasa, sehingga bisa diletakkan di dalam kode sumber. Dalam proyek nyata Anda akan melewati bagian itu, karena berkas gambar Anda sudah ada di disk.

Simpan ini sebagai 01-image.php dan jalankan dengan php 01-image.php:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// A tiny 8 x 8 pixel amber PNG, stored as text inside this script.
// In a real project the image file already exists on disk, so you
// would skip this block and point image() at your own file.
$pngBase64 = 'iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAAEUlEQVR42mP4Oo8bK2IYWhIAq6BngWh/dt4AAAAASUVORK5CYII=';

@mkdir(__DIR__ . '/out');

$pngPath = __DIR__ . '/out/amber-square.png';
$pngBytes = base64_decode($pngBase64, true);
if ($pngBytes === false) {
    fwrite(STDERR, "The embedded image data is damaged.\n");
    exit(1);
}
file_put_contents($pngPath, $pngBytes);

$document = Document::createStandalone();
$document->setTitle('Tutorial: images');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 26, 'A picture inside a PDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 18, 'The amber square below comes from a tiny PNG file.', newLine: true);

// Place the image 72 points (one inch) from the left edge and
// 160 points down from the top, printed as a 96 x 96 point square.
$document->image($pngPath, x: 72, y: 160, width: 96, height: 96);

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

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

Anda akan melihat Wrote out/image.pdf di layar. Buka out/image.pdf dan Anda akan menemukan judul, satu baris teks, dan persegi berwarna amber.

Apa yang baru saja terjadi

Skrip pertama-tama mendekode string Base64 kembali menjadi byte gambar dan menuliskannya ke out/amber-square.png. Itu hanyalah trik agar tutorial ini mandiri. Pelajaran sesungguhnya dimulai pada pemanggilan image(), yang membaca berkas PNG atau JPEG (Joint Photographic Experts Group) mana pun yang sudah ada dengan cara yang sama.
@mkdir(__DIR__ . '/out') membuat folder keluaran. Tanda @ menyembunyikan peringatan tak berbahaya yang akan Anda dapatkan ketika folder sudah ada, sehingga skrip bisa dijalankan dua kali berturut-turut.
image() menerima path berkas beserta posisi dan ukuran cetak. Posisi dan ukuran diukur dalam titik (point), dan 72 titik setara dengan satu inci. Titik asal halaman adalah sudut kiri-atas, sehingga y: 160 berarti 160 titik ke bawah dari atas.
Piksel dan titik adalah dua hal yang berbeda. Gambar tersebut hanya berukuran 8 x 8 piksel, tetapi width: 96, height: 96 mencetaknya sebagai persegi selebar satu dan sepertiga inci. Andalah yang menentukan ukuran cetak; jumlah piksel tidak.
image() menempatkan gambar tepat pada titik yang Anda sebutkan. Ini tidak menggeser posisi penulisan yang digunakan cell(). Dengan menulis teks lebih dahulu, lalu menempatkan gambar, keduanya tidak akan bertabrakan.
NextPDF membaca gambar hanya dari berkas lokal, tidak pernah dari alamat web. NextPDF memeriksa bahwa berkas tersebut benar-benar gambar yang didukung sebelum menyematkannya. Perlindungan itu menjaga Anda ketika nama berkas berasal dari pengguna.

Langkah 2: Tambahkan tabel dan daftar berbutir

Tabel dan daftar adalah konten yang terstruktur. Cara tercepat untuk menjelaskan struktur adalah HTML (Hypertext Markup Language), markup yang sama dengan yang digunakan halaman web. NextPDF merender sekumpulan HTML yang didukung langsung ke halaman PDF. Tidak ada peramban yang terlibat.

Simpan ini sebagai 02-table-and-lists.php dan jalankan dengan php 02-table-and-lists.php:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Tutorial: tables and lists');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 26, 'A reading list, two ways', newLine: true);
$document->ln(8);

$html = <<<'HTML'
<h2>The books as a table</h2>
<table border="1" cellpadding="6" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 50%;">Title</th>
            <th style="width: 20%; text-align: center;">Year</th>
            <th style="width: 30%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Office</td>
            <td style="text-align: center;">2019</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Pixels</td>
            <td style="text-align: center;">2023</td>
            <td style="text-align: right;">208</td>
        </tr>
    </tbody>
</table>

<h2>Why these two books</h2>
<ul>
    <li>Short chapters that fit into a lunch break</li>
    <li>Worked examples on every page</li>
    <li>No jargon without an explanation</li>
</ul>
HTML;

$document->writeHtml($html);

$document->save(__DIR__ . '/out/table-and-lists.pdf');

echo "Wrote out/table-and-lists.pdf\n";

Anda akan melihat Wrote out/table-and-lists.pdf. PDF tersebut memuat judul, tabel tiga kolom dengan baris header gelap, dan daftar berbutir.

Apa yang baru saja terjadi

Skrip ini memadukan kedua gaya penulisan dalam satu halaman. cell() mencetak judul besar pada posisi penulisan saat ini. writeHtml() kemudian mengalirkan tabel dan daftar ke bawah halaman, di bawah judul itu.
ln(8) menambahkan jarak vertikal kecil setinggi delapan titik antara judul dan konten HTML. Tanpanya, keduanya akan tampak berdempetan.
Tabel menggunakan markup tabel biasa: <thead> untuk baris header, <tbody> untuk baris data, <th> untuk sel header, dan <td> untuk sel data. border="1" menggambar garis kisi, dan cellpadding="6" memberi ruang lega di dalam setiap sel.
Lebar kolom berupa persentase, seperti width: 50%. Nilai-nilai ini membagi lebar penuh tabel, sehingga tata letaknya tetap bertahan saat ukuran halaman berubah. Resep Menata tabel HTML membahas header, footer, dan penentuan lebar kolom secara mendalam.
Atribut style menggunakan deklarasi CSS (Cascading Style Sheets), bahasa penataan gaya untuk web. Warna, perataan, dan lebar bekerja seperti yang ditunjukkan di sini. Sebelum Anda mengandalkan properti lain, periksa matriks dukungan CSS.
Daftar berbutir hanyalah <ul> dengan satu <li> per butir. NextPDF menggambar tanda butir dan indentasinya untuk Anda.

Jika terjadi masalah

Kesalahan yang menyebut ImageProcessingException berarti berkas gambar tidak dapat dibaca atau didekode. Periksa path-nya, dan pastikan berkas berformat yang didukung seperti PNG atau JPEG.
Kesalahan yang menyebut PageLayoutException berarti ada posisi atau ukuran yang ditolak. Lebar dan tinggi harus lebih besar dari nol, dan path harus menunjuk ke berkas lokal, bukan alamat web.
Kedua kesalahan tersebut dijelaskan dalam rujukan kesalahan mesin.
Jika tabel tampil aneh, periksa markup-nya terlebih dahulu. Setiap baris <tr> dan sel <td> memerlukan tag penutupnya.
Untuk hal lainnya, mulailah dari panduan pemecahan masalah.

Berikutnya

Halaman Anda kini dapat memuat gambar, tabel, dan daftar. Dalam tutorial berikutnya Anda membiarkan dokumen tumbuh melampaui satu halaman dan menjaganya tetap rapi dengan header, footer, dan nomor halaman. Untuk pembahasan yang lebih mendalam tentang topik hari ini, resep Menyematkan gambar dalam dokumen membahas format gambar dan aturan penentuan ukuran.