Текст, шрифты и основы работы со страницами

В первом руководстве вы отрисовали страницу с одной строкой текста. На этот раз вы возьмёте под контроль саму страницу и текст на ней. Вы выберете размер страницы, напишете заголовки и абзацы и оформите их с помощью встроенных шрифтов движка.

Что вы создадите

Вы напишете два небольших скрипта. Каждый из них создаёт одностраничный файл формата Portable Document Format (PDF):

• 01-text-basics.php отрисовывает страницу A4 в книжной ориентации с цветным заголовком, абзацами с переносом строк и тремя примерами выравнивания.
• 02-fonts.php отрисовывает страницу-образец, сравнивающую два встроенных семейства шрифтов в нескольких размерах.

Всё работает только с пакетом nextpdf/core. Вам не нужны ни файлы шрифтов, ни дополнительные расширения, ни сеть. Если у вас ещё нет настроенного проекта, сначала пройдите первое руководство и вернитесь сюда.

Шаг 1. Оформление текста на странице A4

У каждой страницы есть размер и ориентация. A4 — это распространённый международный размер бумаги, а Letter — его аналог в США. Ориентация бывает книжной (portrait, вертикальная) или альбомной (landscape, горизонтальная). И размер, и ориентацию вы передаёте в addPage(), когда начинаете страницу.

Затем записью занимаются три метода. setFont() выбирает гарнитуру и размер для последующего текста. cell() пишет одну строку внутри невидимой рамки. multiCell() переносит более длинный текст на столько строк, сколько нужно. В обоих методах ширина 0 означает “использовать всё пространство вплоть до правого поля”.

Ещё два вызова отвечают за внешний вид. setTextColor() принимает значения красного, зелёного и синего от 0 до 255 и действует, пока вы не измените его снова. Перечисление Alignment — фиксированный список именованных вариантов — предлагает Left, Center, Right и Justify.

Создайте 01-text-basics.php в папке проекта:

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Contracts\Orientation;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Text basics');
$document->addPage(PageSize::A4(), Orientation::Portrait);

// A colored heading. The values are red, green, and blue, each 0 to 255.
$document->setFont('helvetica', 'B', 20);
$document->setTextColor(30, 64, 175);
$document->cell(0, 14, 'Project kickoff notes', newLine: true);
$document->ln(4);

// Back to black for the body text.
$document->setTextColor(0, 0, 0);
$document->setFont('helvetica', '', 11);
$document->multiCell(
    0,
    7,
    'Welcome to the second tutorial. This paragraph is written with '
        . 'multiCell(), so the engine wraps the words onto as many lines '
        . 'as the page width requires.',
);
$document->ln(4);

$document->multiCell(
    0,
    7,
    'Justified text stretches the spaces so both edges line up. It is a '
        . 'good fit for report bodies and other long passages.',
    align: Alignment::Justify,
);
$document->ln(6);

// One line each: left, centered, and right.
$document->setFont('helvetica', 'I', 11);
$document->cell(0, 8, 'Left-aligned line', newLine: true, align: Alignment::Left);
$document->cell(0, 8, 'Centered line', newLine: true, align: Alignment::Center);
$document->cell(0, 8, 'Right-aligned line', newLine: true, align: Alignment::Right);

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

echo "Wrote out/text-basics.pdf\n";

Запустите его командой php 01-text-basics.php. Скрипт выводит Wrote out/text-basics.pdf, и файл появляется в новой папке out/.

Что произошло

addPage(PageSize::A4(), Orientation::Portrait) создал страницу до того, как был записан хоть какой-то текст. Передайте вместо этого Orientation::Landscape — и та же страница развернётся горизонтально. Другие именованные размеры, такие как PageSize::A5() или PageSize::Letter(), работают точно так же.

setFont('helvetica', 'B', 20) выбрал полужирный Helvetica размером 20 пунктов. Пункт (pt) — традиционная типографская единица; 72 пункта равны одному дюйму. Заголовок синий, потому что при вызове cell(), который его записал, был активен setTextColor(30, 64, 175). Следующий setTextColor(0, 0, 0) вернул чёрный цвет для всего, что идёт после него.

Два вызова multiCell() автоматически перенесли свои абзацы по строкам. Тот, что с выравниванием по ширине, растягивает межсловные пробелы, чтобы оба края совпадали, — кроме последней строки абзаца. Между блоками ln() смещал позицию записи вниз, добавляя свободное пространство. Наконец, save() собрал файл и записал его в out/.

Полный список параметров, которые принимают эти методы, см. в разделе Составление текста со шрифтами и выравниванием.

Шаг 2. Выбор среди встроенных шрифтов

Движок поставляется с тремя встроенными текстовыми семействами: Helvetica, Times и Courier. Helvetica — рубленая гарнитура (sans-serif), то есть у её букв нет мелких концевых штрихов (засечек). Times — гарнитура с засечками (serif), которая хорошо читается в длинных фрагментах, напоминающих печатный текст. Courier — моноширинный шрифт, поэтому он подходит для листингов кода и чеков. Поскольку эти семейства встроены, вашим скриптам вообще не нужны файлы шрифтов.

Аргумент стиля в setFont() объединяет однобуквенные флаги: 'B' — полужирный, 'I' — курсив и 'U' — подчёркивание. Пустая строка означает обычное начертание, а флаги комбинируются, поэтому 'BI' даёт полужирный курсив.

Встроенные семейства поддерживают текст на основе латиницы. Для других систем письма или собственной фирменной гарнитуры вы регистрируете файл шрифта, как показано в рецепте Встраивание и субсеттинг шрифтов (субсеттинг сохраняет только те символы, которые вы действительно использовали, поэтому файлы остаются небольшими). Матрица поддержки шрифтов перечисляет все форматы шрифтов, которые принимает движок.

Создайте 02-fonts.php рядом с первым скриптом:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Font sampler');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 14, 'Built-in font sampler', newLine: true);
$document->ln(4);

// Helvetica: a sans-serif face, a solid default for labels and headings.
$document->setFont('helvetica', 'B', 14);
$document->cell(0, 10, 'Helvetica', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('helvetica', '', (float) $size);
    $document->cell(0, $size * 0.8, "Helvetica sample at {$size}pt.", newLine: true);
}
$document->setFont('helvetica', 'BI', 12);
$document->cell(0, 9, 'Helvetica bold italic for emphasis.', newLine: true);
$document->ln(6);

// Times: a serif face that suits long, print-like passages.
$document->setFont('times', 'B', 14);
$document->cell(0, 10, 'Times', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('times', '', (float) $size);
    $document->cell(0, $size * 0.8, "Times sample at {$size}pt.", newLine: true);
}
$document->setFont('times', 'I', 12);
$document->cell(0, 9, 'Times italic for quotations.', newLine: true);

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

echo "Wrote out/font-sampler.pdf\n";

Запустите его командой php 02-fonts.php и откройте out/font-sampler.pdf. Вы увидите, как одно и то же тестовое предложение меняет облик при переходе между двумя семействами и увеличивается на трёх размерах.

Что произошло

addPage() без аргументов использовал стандартные настройки страницы в книжной ориентации, поэтому не каждому скрипту нужно указывать размер явно. Каждый вызов setFont() менял активное семейство, начертание или размер прямо посреди страницы, и шрифт остаётся активным до следующего вызова setFont().

Циклы приводят размер к типу с помощью (float), потому что setFont() ожидает десятичное число. Высота строк масштабируется вместе с размером шрифта ($size * 0.8), поэтому более крупный текст получает более высокие строки и ничто не перекрывается. Попробуйте заменить 'times' на 'courier' и снова запустить скрипт, чтобы увидеть третье семейство.

Если что-то пошло не так

• Ошибка “class not found” или ошибка автозагрузки обычно означает, что скрипт не нашёл vendor/autoload.php. Запускайте его внутри папки проекта, содержащей vendor/.
• Опечатка в имени семейства вызывает исключение с именем шрифта, который не удалось найти. Проверьте написание: helvetica, times, courier.
• Центр устранения неполадок собирает типовые решения, а Шрифты и тегирование подробно рассматривает проблемы со шрифтами.
• Каждое исключение движка задокументировано в справочнике ошибок — с контекстом, который оно несёт, и действием по восстановлению.

Дальше

Теперь вы можете формировать страницы, оформлять текст и осознанно выбирать шрифты. В следующем руководстве вы размещаете изображения на странице и упорядочиваете содержимое с помощью таблиц и списков.