テキスト、フォント、ページの基本

最初のチュートリアルでは、1 行のテキストだけのページをレンダリングしました。今回は、ページそのものと、その上に載るテキストを自分で制御します。ページサイズを選び、見出しと段落を記述し、エンジンの組み込みフォントでそれらをスタイル設定します。

作成するもの

小さなスクリプトを 2 つ記述します。それぞれが 1 ページの Portable Document Format（PDF）ファイルを生成します。

• 01-text-basics.php は、色付きの見出し、折り返された段落、3 種類の整列サンプルを含む A4 縦向きのページをレンダリングします。
• 02-fonts.php は、2 つの組み込みフォントファミリーを複数のサイズで比較するサンプラーページをレンダリングします。

すべては nextpdf/core パッケージだけで動作します。フォントファイルも、追加の拡張機能も、ネットワークも必要ありません。まだプロジェクトを準備していない場合は、先に 最初のチュートリアル に従ってから、ここに戻ってきてください。

ステップ 1：A4 ページでテキストをスタイル設定する

すべてのページには、サイズと向きがあります。A4 は国際的に一般的な用紙サイズで、Letter はその米国版に相当します。向きは、縦向き（portrait、直立）か横向き（landscape、横倒し）のいずれかです。ページを開始するときに、この 2 つの選択を addPage() に渡します。

次に、3 つのメソッドが書き込みを担います。setFont() は、これ以降のテキストに使う書体とサイズを選びます。cell() は、見えないボックスの中に 1 行を書き込みます。multiCell() は、長めのテキストを必要なだけの行数に折り返します。どちらのメソッドでも、幅 0 は「右マージンまでの領域をすべて使う」という意味です。

見た目は、さらに 2 つの呼び出しで整えます。setTextColor() は、赤・緑・青の値を 0 から 255 で受け取り、再び変更するまで適用され続けます。Alignment enum は、名前付きの選択肢を集めた固定リストで、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) は、20 ポイントの太字 Helvetica を選択しました。ポイント（pt）は伝統的な印刷の単位で、72 ポイントが 1 インチに相当します。見出しが青いのは、cell() の呼び出しが書き込んだときに setTextColor(30, 64, 175) が有効だったためです。次の setTextColor(0, 0, 0) は、それ以降のすべてを黒に戻しました。

2 つの multiCell() の呼び出しは、段落を自動的に折り返しました。両端揃えのほうは、段落の最終行を除いて、両端がそろうように単語間隔を広げます。ブロックとブロックの間では、ln() が書き込み位置を下に動かして余白を加えました。最後に、save() がファイルを構築して out/ に書き出しました。

これらのメソッドが受け取るすべてのパラメーターについては、フォントと整列を使ってテキストを構成する を参照してください。

ステップ 2：組み込みフォントから選ぶ

エンジンには、3 つのテキストファミリーが組み込まれています。Helvetica、Times、Courier です。Helvetica はサンセリフ体で、文字の末端に小さな飾り（セリフ）がありません。Times はセリフ体で、印刷物のような長い文章で読みやすい書体です。Courier は等幅なので、コードのリストや領収書に適しています。これらのファミリーは組み込まれているため、スクリプトにフォントファイルはまったく必要ありません。

setFont() の style 引数は、1 文字のフラグを組み合わせます。'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 を開きます。同じサンプル文が、2 つのファミリーの間で表情を変え、3 つのサイズで大きくなっていくのがわかります。

いま何が起きたか

引数なしの addPage() は、縦向きのデフォルトのページ設定を使いました。そのため、すべてのスクリプトでサイズを明示する必要はありません。それぞれの setFont() の呼び出しは、ページの途中でアクティブなファミリー・スタイル・サイズを切り替え、フォントは次の setFont() の呼び出しまで有効なままです。

ループでは、setFont() が小数を期待するため、サイズを (float) でキャストしています。行の高さはフォントサイズに合わせて拡大縮小するので（$size * 0.8）、大きいテキストほど行が高くなり、重なりが生じません。'times' を 'courier' に置き換えてスクリプトをもう一度実行すると、3 つ目のファミリーを確認できます。

うまくいかないとき

• 「class not found」やオートロードのエラーは、たいていスクリプトが vendor/autoload.php を見つけられなかったことを意味します。vendor/ を含むプロジェクトフォルダーの中で実行してください。
• ファミリー名を打ち間違えると、見つけられなかったフォント名を示す例外がスローされます。つづりを確認してください。helvetica、times、courier です。
• トラブルシューティングハブ には、よくある対処法がまとめられており、フォントとタグ付け はフォントの問題を掘り下げて扱っています。
• エンジンのすべての例外は、それぞれが持つコンテキストと回復のためのアクションとともに、エラーリファレンス に記載されています。

次のステップ

これで、意図を持ってページを形づくり、テキストをスタイル設定し、フォントを選べるようになりました。次のチュートリアル では、ページに画像を配置し、テーブルとリストでコンテンツを整理します。