Размещение текста: шрифты и выравнивание

Коротко о главном

Этот рецепт показывает, как размещать текст и управлять семейством шрифта, начертанием, размером и выравниванием. Используются три метода: setFont(), cell() и multiCell(). Код основан на примере examples/04-text-and-fonts.php.

Установка

composer require nextpdf/core:^3

Эта команда устанавливает пакет nextpdf/core. Для примера требуется PHP 8.4.

Концептуальный обзор

setFont($family, $style, $size) выбирает активное начертание для следующего вызова вывода текста. Аргумент $style принимает комбинацию из трёх флагов: B (полужирный), I (курсив) и U (подчёркивание). Флаг U применяет оформление текста, а остальные флаги выбирают вариант шрифта. Семейства Helvetica, Times и Courier сопоставляются с 14 стандартными шрифтами Type 1, перечисленными в ISO 32000-2. Профиль соответствия может переопределить это поведение и потребовать встроенный замещающий шрифт.

cell() выводит одну строку внутри блока. multiCell() переносит слова в столбце с заданными шириной и высотой строки. Текст задаётся в текстовом пространстве, а текстовая матрица отображает текстовое пространство в пользовательское (ISO 32000-2). Вы работаете в пользовательских единицах, а движок формирует матрицу автоматически.

Задайте выравнивание с помощью перечисления Alignment: Left, Center, Right, Justify. Для multiCell() выравнивание по ширине распределяет пробелы между словами по всей строке.

Поверхность 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 — тот же трейт.
Alignment — NextPDF\Contracts\Alignment (Left, Center, Right, Justify).

Полная таблица PHPDoc составляется по исходному коду.

Пример кода — быстрый старт

<?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');

Пример кода — рабочий вариант

Этот пример самодостаточен, поэтому его можно запускать в тестовой среде. Он повторяет examples/04-text-and-fonts.php и демонстрирует варианты начертания, несколько размеров шрифта, текст с переносом и выравниванием по ширине, а также три способа выравнивания.

<?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:

Wrote compose-text-and-fonts.pdf

Граничные случаи и подводные камни

Ширина 0 означает оставшуюся ширину. Когда вы передаёте 0, cell(0, ...) и multiCell(0, ...) используют пространство до правого поля. Для блока фиксированной ширины передайте явную ширину.
Порядок символов в строке начертания. 'BI' и 'IB' выбирают одно и то же полужирное курсивное начертание, поскольку анализатор не учитывает порядок флагов. Флаг 'U' — это флаг оформления, а не вариант шрифта.
Покрытие глифов стандартными шрифтами. 14 стандартных шрифтов отрисовывают полный репертуар WinAnsiEncoding (Windows-1252). Он покрывает западноевропейскую латиницу с диакритикой, знак евро и распространённую типографскую пунктуацию — короткое и длинное тире, типографские кавычки, маркер списка, многоточие и знак товарного знака. Для письменностей за пределами этого набора, таких как китайская, японская, корейская, арабская, иврит, греческая, кириллица или тайская, зарегистрируйте и выберите начертание TrueType. См. Встраивание и субсетинг шрифтов.
Высота строки относительно размера шрифта. Высота строки в multiCell() равна размеру шрифта, умноженному на коэффициент межстрочного интервала по умолчанию, заданный в профиле метрик. Если высота слишком мала, строки могут перекрываться.
Выравнивание по ширине в последней строке. При выравнивании по ширине multiCell() не растягивает последнюю строку абзаца. Это соответствует общепринятым правилам вёрстки.

Производительность

Вывод текста линеен по числу глифов, O(n). Бюджет составляет wall_ms: 1000, peak_mb: 64. Этот бюджет ниже, чем у рецептов на языке HyperText Markup Language (HTML), потому что здесь нет ни каскада, ни дерева макета. Стандартные шрифты не встраиваются, поэтому размер выходного PDF остаётся небольшим.

Замечания по безопасности

Текстовое содержимое отрисовывается, а не интерпретируется. Проверяйте длину пользовательских строк, чтобы ограничить размер вывода. Этот путь обработки не выполняет скрипты и не загружает удалённые ресурсы.

Соответствие

Утверждение	Спецификация	Пункт	reference_id (идентификатор ссылки)
Семейства Helvetica, Times и Courier входят в число 14 стандартных шрифтов Type 1.	ISO 32000-2	iso32000_2_sec9#x1.x29 (§9 шрифты)
Семейства стандартных 14 шрифтов поддерживают полный латинский набор символов (WinAnsiEncoding, Windows code page 1252).	ISO 32000-2	Annex D.2 (iso32000_2_annexes#x1.x17.p4)	eb9220f88dfadad27a0be2206b64e68d8ea301d6d46e08142d43859c05fac6e4
Координаты текста заданы в текстовом пространстве и отображаются в пользовательское пространство текстовой матрицей.	ISO 32000-2	iso32000_2_sec8#x1.x10.p2 (§8 позиционирование текста)

Этот рецепт показывает, как NextPDF размещает текст со стандартными шрифтами. Их покрытие глифов — это полный репертуар WinAnsiEncoding (Windows-1252): западноевропейская латиница плюс распространённая типографская пунктуация. Для текста на других письменностях требуется встроенное начертание.

Коммерческий контекст

Не применимо.