フォントと配置を指定してテキストを組版する

概要

このレシピでは、テキストを配置し、フォントファミリー、スタイル、サイズ、配置を設定します。この処理には、setFont()、cell()、multiCell() の 3 つのメソッドを使います。コードは examples/04-text-and-fonts.php に準拠しています。

インストール

composer require nextpdf/core:^3

この制約により nextpdf/core パッケージがインストールされます。このサンプルは PHP 8.4 で動作します。

概念的な概要

setFont($family, $style, $size) はアクティブなフェイスを選択します。選択されたフェイスは、次のテキスト呼び出しで使用されるフォントです。$style 引数は、3 つのフラグ B（太字）、I（斜体）、U（下線）を組み合わせます。U フラグはテキスト装飾フラグであり、残りはフォントバリアントを選択します。Helvetica、Times、Courier の各ファミリーは、ISO 32000-2 で指定されている 14 種類の標準 Type 1 フォントに解決されます。適合性プロファイルによっては、これをオーバーライドして代替フォントの埋め込みを強制できます。

cell() はボックス内に 1 行のテキストを書き込みます。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 を反映しており、スタイルのバリアント、さまざまなサイズ、折り返し付きの両端揃えテキスト、3 種類の配置を示します。

<?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）のレパートリー全体をレンダリングします。これは西ヨーロッパのアクセント付きラテン文字、ユーロ記号、および一般的な約物（en ダッシュと em ダッシュ、丸引用符、中黒、省略記号、商標記号）をカバーします。中国語、日本語、韓国語、アラビア語、ヘブライ語、ギリシャ語、キリル文字、タイ語など、その範囲外のスクリプトを使う場合は、TrueType フェイスを登録して選択します。フォントの埋め込みとサブセット化を参照してください。
フォントサイズに対する行の高さ。 multiCell() の 1 行あたりの高さは、フォントサイズにメトリックプロファイルのデフォルトの行間比率を掛けた値です。高さが小さすぎると、行が重なることがあります。
最終行の両端揃え。 両端揃えの multiCell() は、段落の最終行を引き伸ばしません。これは従来の組版と一致します。

パフォーマンス

テキスト出力は、グリフ数に対して線形（O(n)）です。バジェットは wall_ms: 1000, peak_mb: 64 です。カスケードやレイアウトツリーがないため、HTML レシピよりも低いバジェットになっています。標準フォントは埋め込まれないため、出力は小さく保たれます。

セキュリティに関する注意

テキストコンテンツはレンダリングされるだけで、解釈されることはありません。出力サイズを一定範囲に収めるために、ユーザー指定の文字列の長さを検証してください。このパスはスクリプトを実行せず、リモートリソースを取得しません。

適合性

記述	仕様	箇条	reference_id
14 種類の標準 Type 1 フォントに含まれる Helvetica、Times、Courier の各ファミリー	ISO 32000-2	iso32000_2_sec9#x1.x29
標準 14 フォントファミリーはラテン文字セット全体（WinAnsiEncoding、Windows コードページ 1252）をサポートします。	ISO 32000-2	Annex D.2 (iso32000_2_annexes#x1.x17.p4)	eb9220f88dfadad27a0be2206b64e68d8ea301d6d46e08142d43859c05fac6e4
テキスト空間にあり、テキストマトリックスによってユーザー空間にマッピングされるテキスト座標	ISO 32000-2	iso32000_2_sec8#x1.x10.p2

このレシピでは、NextPDF が標準フォントを使ってテキストを組版する方法を示します。これらのフォントのグリフカバレッジは WinAnsiEncoding（Windows-1252）のレパートリー全体、すなわち西ヨーロッパのラテン文字に一般的な約物を加えたものです。その他のスクリプトのテキストには、埋め込みフェイスが必要です。

商用コンテキスト

該当なし。