Compose text with fonts and alignment

At a glance

Use this recipe to place text and control its font family, style, size, and alignment. You use three methods: setFont(), cell(), and multiCell(). The code follows examples/04-text-and-fonts.php.

Install

composer require nextpdf/core:^3

This constraint installs the nextpdf/core package. The example requires PHP 8.4.

Conceptual overview

setFont($family, $style, $size) selects the active face for the next text call. The $style argument combines three flags: B (bold), I (italic), and U (underline). The U flag applies text decoration; the other flags select the font variant. The Helvetica, Times, and Courier families resolve to the 14 standard Type 1 fonts named in ISO 32000-2. A conformance profile can override this and require an embedded substitute font.

cell() writes one line inside a box. multiCell() wraps words into a column with the width and line height you provide. Text starts in text space, and the text matrix maps text space to user space (ISO 32000-2). You work in user units, and the engine emits the matrix for you.

Set alignment with the Alignment enum: Left, Center, Right, Justify. For multiCell(), justification spreads word spacing across the line.

API surface

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 — same trait.
Alignment — NextPDF\Contracts\Alignment (Left, Center, Right, Justify).

The complete PHPDoc table comes from the source code.

Code sample — Quick start

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

Code sample — Production

This example is self-contained, so the test harness can run it. It mirrors examples/04-text-and-fonts.php and shows style variants, multiple sizes, word-wrapped justified text, and the three alignments.

<?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";

Expected STDOUT:

Wrote compose-text-and-fonts.pdf

Edge cases & gotchas

Width 0 means remaining width. When you pass 0, cell(0, ...) and multiCell(0, ...) use the space up to the right margin. For a fixed-width box, pass an explicit width.
Style string order. 'BI' and 'IB' select the same bold-italic variant because the parser ignores flag order. The 'U' flag is a decoration flag, not a font variant.
Standard-font glyph coverage. The 14 standard fonts render the full WinAnsiEncoding (Windows-1252) repertoire. This covers Western European accented Latin, the Euro sign, and common typographic punctuation — en and em dashes, curly quotes, the bullet, the ellipsis, and the trademark sign. For scripts outside that set, such as Chinese, Japanese, Korean, Arabic, Hebrew, Greek, Cyrillic, or Thai, register and select a TrueType face. See Embed and subset fonts.
Line height compared with font size. The per-line height of multiCell() is the font size times the default line-height ratio of the metric profile. If the height is too small, lines can overlap.
Justify on the last line. Justified multiCell() does not stretch the final line of a paragraph. This matches conventional typesetting.

Performance

Text emission is linear in the glyph count, O(n). The budget is wall_ms: 1000, peak_mb: 64. It is lower than the HyperText Markup Language (HTML) recipes because there is no cascade or layout tree. Standard fonts are not embedded, which keeps the output small.

Security notes

Text content is rendered, not interpreted. Validate the length of user-supplied strings to keep output size bounded. This path runs no script and fetches no remote resource.

Conformance

Statement	Spec	Clause	reference_id
The Helvetica, Times, and Courier families are among the 14 standard Type 1 fonts.	ISO 32000-2	iso32000_2_sec9#x1.x29
The standard-14 families support the full Latin character set (WinAnsiEncoding, Windows code page 1252).	ISO 32000-2	Annex D.2 (iso32000_2_annexes#x1.x17.p4)	eb9220f88dfadad27a0be2206b64e68d8ea301d6d46e08142d43859c05fac6e4
Text coordinates are in text space, mapped to user space by the text matrix.	ISO 32000-2	iso32000_2_sec8#x1.x10.p2

This recipe shows how NextPDF composes text with the standard fonts. Their glyph coverage is the full WinAnsiEncoding (Windows-1252) repertoire — Western European Latin plus common typographic punctuation. Text in other scripts requires an embedded face.

Commercial context

Not applicable.