Menyusun teks dengan fon dan perataan

Sekilas pandang

Gunakan resep ini untuk menempatkan teks serta mengatur keluarga fon, gaya, ukuran, dan perataannya. Anda akan menggunakan tiga metode: setFont(), cell(), dan multiCell(). Kode ini mengacu pada examples/04-text-and-fonts.php.

Pemasangan

composer require nextpdf/core:^3

Perintah ini memasang paket nextpdf/core. Contoh ini membutuhkan PHP 8.4.

Gambaran konseptual

setFont($family, $style, $size) memilih fon aktif untuk pemanggilan teks berikutnya. Argumen $style dapat menggabungkan tiga tanda: B (tebal), I (miring), dan U (garis bawah). Tanda U menerapkan dekorasi teks; tanda lainnya memilih varian fon. Keluarga Helvetica, Times, dan Courier merujuk pada 14 fon Type 1 standar yang disebutkan dalam ISO 32000-2. Profil kesesuaian dapat menimpa pilihan ini dan mensyaratkan fon pengganti yang disematkan.

cell() menulis satu baris di dalam sebuah kotak. multiCell() membungkus kata-kata ke dalam kolom dengan lebar dan tinggi baris yang Anda tentukan. Teks berawal di ruang teks, dan matriks teks memetakan ruang teks ke ruang pengguna (ISO 32000-2). Anda bekerja dalam satuan pengguna, dan mesin menghasilkan matriksnya untuk Anda.

Atur perataan dengan enum Alignment: Left, Center, Right, Justify. Untuk multiCell(), rata kiri-kanan menyebarkan spasi antarkata di sepanjang baris.

Permukaan API

setFont(string $family, string $style = '', float $size = 12.0): static — NextPDF\Core\Concerns\HasTypography.
cell(float $width, float $height, string $text = '', bool|string $border = false, bool $newLine = false, Alignment $align = Alignment::Left, bool $fill = false): static — NextPDF\Core\Concerns\HasTextOutput.
multiCell(float $width, float $height, string $text, bool|string $border = false, Alignment $align = Alignment::Left): static — trait yang sama.
Alignment — NextPDF\Contracts\Alignment (Left, Center, Right, Justify).

Tabel PHPDoc lengkap berasal dari kode sumber.

Contoh kode — Mulai cepat

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Heading', newLine: true);

$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Word-wrapped justified body text.', align: Alignment::Justify);

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

Contoh kode — Produksi

Contoh ini bersifat mandiri, sehingga dapat dijalankan oleh kerangka pengujian. Contoh ini mengikuti examples/04-text-and-fonts.php dan memperlihatkan varian gaya, beberapa ukuran, teks yang membungkus kata dengan rata kiri-kanan, serta ketiga jenis perataan.

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Text and Fonts');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Text and Font Styles', newLine: true);
$doc->ln(5);

$doc->setFont('helvetica', '', 12);
$doc->cell(0, 8, 'Normal text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, 'Bold text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'I', 12);
$doc->cell(0, 8, 'Italic text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'BI', 12);
$doc->cell(0, 8, 'Bold-Italic text in Helvetica 12pt.', newLine: true);
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Font Sizes', newLine: true);
foreach ([8, 10, 12, 14, 18] as $size) {
    $doc->setFont('helvetica', '', (float) $size);
    $doc->cell(0, $size * 0.8, "This is {$size}pt text.", newLine: true);
}
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Multi-Line Text (Word Wrap)', newLine: true);
$doc->setFont('helvetica', '', 11);
$paragraph = 'NextPDF is a modern PDF 2.0 library for PHP. It provides a '
    . 'fluent API for document creation. This paragraph demonstrates '
    . 'automatic word wrapping and justified alignment with multiCell().';
$doc->multiCell(0, 7, $paragraph, align: Alignment::Justify);
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Text Alignment', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->cell(0, 8, 'Left-aligned text', newLine: true, align: Alignment::Left);
$doc->cell(0, 8, 'Center-aligned text', newLine: true, align: Alignment::Center);
$doc->cell(0, 8, 'Right-aligned text', newLine: true, align: Alignment::Right);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/compose-text-and-fonts.pdf');

echo "Wrote compose-text-and-fonts.pdf\n";

STDOUT yang diharapkan:

Wrote compose-text-and-fonts.pdf

Kasus tepi & jebakan

Lebar 0 berarti lebar yang tersisa. Saat Anda meneruskan 0, cell(0, ...) dan multiCell(0, ...) menggunakan ruang hingga margin kanan. Untuk kotak dengan lebar tetap, teruskan lebar secara eksplisit.
Urutan string gaya. 'BI' dan 'IB' memilih varian tebal-miring yang sama karena pengurai mengabaikan urutan tanda. Tanda 'U' merupakan tanda dekorasi, bukan varian fon.
Cakupan glif fon standar. Ke-14 fon standar merender seluruh repertoar WinAnsiEncoding (Windows-1252). Ini mencakup Latin beraksen Eropa Barat, tanda Euro, serta tanda baca tipografis umum — tanda hubung en dan em, tanda kutip lengkung, bulet, elipsis, dan tanda merek dagang. Untuk aksara di luar himpunan tersebut, seperti Tionghoa, Jepang, Korea, Arab, Ibrani, Yunani, Sirilik, atau Thai, daftarkan dan pilih fon TrueType. Lihat Menyematkan dan membuat subset fon.
Tinggi baris dibandingkan dengan ukuran fon. Tinggi tiap baris dari multiCell() adalah ukuran fon dikalikan rasio tinggi baris baku dari profil metrik. Jika tingginya terlalu kecil, baris dapat saling tumpang tindih.
Rata kiri-kanan pada baris terakhir. multiCell() yang diratakan kiri-kanan tidak meregangkan baris terakhir dari sebuah paragraf. Ini sesuai dengan penataan huruf konvensional.

Performa

Output teks bersifat linear terhadap jumlah glif, O(n). Anggarannya adalah wall_ms: 1000, peak_mb: 64. Anggaran ini lebih rendah daripada resep HyperText Markup Language (HTML) karena tidak ada kaskade atau pohon tata letak. Fon standar tidak disematkan, sehingga keluarannya tetap kecil.

Catatan keamanan

Konten teks dirender, bukan ditafsirkan. Validasi panjang string yang diberikan pengguna untuk menjaga ukuran keluaran tetap terbatas. Alur ini tidak menjalankan skrip apa pun dan tidak mengambil sumber daya jarak jauh apa pun.

Kesesuaian

Pernyataan	Spesifikasi	Klausul	reference_id
Keluarga Helvetica, Times, dan Courier termasuk di antara 14 fon Type 1 standar.	ISO 32000-2	iso32000_2_sec9#x1.x29
Keluarga standard-14 mendukung set karakter Latin lengkap (WinAnsiEncoding, Windows code page 1252).	ISO 32000-2	Annex D.2 (iso32000_2_annexes#x1.x17.p4)	eb9220f88dfadad27a0be2206b64e68d8ea301d6d46e08142d43859c05fac6e4
Koordinat teks berada dalam ruang teks, dipetakan ke ruang pengguna oleh matriks teks.	ISO 32000-2	iso32000_2_sec8#x1.x10.p2

Resep ini menunjukkan bagaimana NextPDF menyusun teks dengan fon standar. Cakupan glifnya adalah seluruh repertoar WinAnsiEncoding (Windows-1252) — Latin Eropa Barat ditambah tanda baca tipografis umum. Teks dalam aksara lain memerlukan fon yang disematkan.

Konteks komersial

Tidak berlaku.