NextPDF をセットアップして最初の PDF をレンダリングする

NextPDF は、PDF（Portable Document Format）ファイルを作成する PHP ライブラリです。 このチュートリアルでは、空のフォルダーに NextPDF をインストールし、最初の 1 ページのドキュメントをレンダリングします。ターミナルと約 10 分の時間が必要です。

作成するもの

ここでは、01-hello.php という 1 つのスクリプトだけを含む小さなプロジェクトを作成します。 このスクリプトは、太字のタイトル行と 1 つの段落を持つ 1 ページをレンダリングし、 その結果を out/hello.pdf として保存します。その過程で、インストールが正常であることを確認する 2 つのコマンドを学びます。

このページでは、1 つのインストール方法（空のフォルダーとエンジンパッケージ）を説明します。 フレームワークアダプター、ブラウザーベースのレンダラー、Python クライアントなど、 ほかの方法も存在します。それらは インストール とパスを選ぶにあります。今日はそれらは必要ありません。

ステップ 1: プロジェクトを作成して NextPDF をインストールする

Composer は PHP のパッケージマネージャーです。ライブラリをプロジェクトにダウンロードし、 オートローダーを生成します。オートローダーは、ライブラリのクラスを自動的に見つける小さな PHP ファイルであり、これにより長い include のリストを書く必要がなくなります。

ターミナルを開き、次の 3 つのコマンドを実行します。

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

Composer は、パッケージを解決してダウンロードする間、進捗を表示します。実際に表示される行は、Composer のバージョンやローカルキャッシュによって異なります。インストールが成功すると、エラーテキストなしで終了し、おおよそ次のようになります。

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

何が起きたか

Composer は、フォルダー内に 3 つのものを作成しました。composer.json は、プロジェクトがエンジンに依存していることを記録します。composer.lock は、インストールされた正確なバージョンを固定するため、後でインストールしても同じコードが解決されます。vendor/ フォルダーには、vendor/autoload.php を含む、ダウンロードされたパッケージが格納されます。 スクリプトはこの 1 つのファイルを読み込むだけで、すべてのエンジンクラスが利用可能になります。

Composer は、インストール中に PHP のセットアップも確認しました。エンジンは、必要な PHP 拡張機能を宣言します。拡張機能は、PHP に組み込まれるオプションのモジュールです。いずれかが不足している場合、Composer は壊れたインストールを残す代わりに、処理を停止してその拡張機能の名前を示します。

ステップ 2: 最初の PDF をレンダリングする

composer.json と同じ場所に 01-hello.php という名前のファイルを作成します。この完全なプログラムを貼り付けてください。

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

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

echo "Wrote out/hello.pdf\n";

実行します。

php 01-hello.php

次の 1 行だけが表示されるはずです。

Wrote out/hello.pdf

任意の PDF ビューアーで out/hello.pdf を開いてください。太字のタイトル行とその下に段落が表示され、ほとんどのビューアーではウィンドウのタイトルに “Hello from NextPDF” と表示されます。

何が起きたか

スクリプトを上から下まで順に見ていきましょう。

• require は Composer のオートローダーを読み込むため、Document クラスが解決されます。
• @mkdir は out/ フォルダーを作成します。先頭の @ は、フォルダーがすでに存在する場合にスクリプトを静かに保つため、再度実行できます。
• Document::createStandalone() は新しいドキュメントを返します。これは、まさにこのような短いコマンドライン用スクリプトのために作られています。
• setTitle() はドキュメントのタイトルを設定します。これはビューアーがウィンドウのタイトルに表示します。
• addPage() は空のページを 1 つ追加し、カーソルを左上に配置します。
• setFont() は、フォントファミリー、スタイル、およびポイント単位のサイズを選択します。 ポイントは、印刷におけるフォントサイズの標準的な単位です。'B' は太字を、'' は標準を意味します。helvetica という名前のファミリーは組み込みであるため、フォントファイルは不要です。
• cell() はカーソル位置に 1 行のテキストを書き込みます。幅 0 は「右マージンまで伸ばす」ことを意味します。newLine: true はその後カーソルを下に移動させます。これは Enter キーを押すのと同じです。
• save() は完成した PDF を構築し、ディスクに書き込みます。

1 つのドキュメントは 1 つのファイルを生成します。2 つ目の PDF が必要な場合は、古いドキュメントを再利用するのではなく、新しいドキュメントを作成してください。

ステップ 3: セットアップを検証する

2 つの簡単なチェックで、このインストールが 1 つのスクリプトにとどまらず機能し続けることを確認できます。

まず、PHP に含まれる拡張機能を一覧表示します。

php -m

リストの中から curl、gd、intl、mbstring、openssl、zlib を探してください。 エンジンはこれら 6 つに依存しています。Composer はステップ 1 ですでにこれらを確認しているため、すべて表示されるはずです。

次に、エンジン自身のヘルスチェックを実行します。

vendor/bin/nextpdf doctor

Windows では、代わりに vendor\bin\nextpdf doctor を呼び出します。このコマンドは、PHP のバージョン、拡張機能、一時フォルダー、および設定を検査します。各チェックは [OK]、 [WARN]、または [FAIL] を表示し、その後に総合的な判定を 1 つ表示します。

何が起きたか

最初に Extensions ブロックを読んでください。curl、gd、intl、mbstring、 openssl、zlib という名前の 6 つの [OK] 行があれば、インストールは後続のすべてのチュートリアルに対応できる状態です。

このレポートには、エンジンのケイパビリティも一覧表示されます。無料の Core インストールでは、商用パッケージに属するケイパビリティは、それらを提供するパッケージ名を示すメッセージとともに [FAIL] を表示します。これはここでは想定どおりであり、Core のセットアップに問題がなくても、総合的な判定が UNHEALTHY になることがあります。これらのチュートリアルでは、 Extensions ブロックこそが重要なシグナルです。

うまくいかなかった場合

まず、症状を次のよくあるケースと照らし合わせてください。

• composer: command not found は、Composer が存在しないか、PATH に含まれていないことを意味します。getcomposer.orgからインストールし、ステップ 1 を繰り返してください。
• Failed opening required '.../vendor/autoload.php' は、スクリプトがプロジェクトフォルダーの外で実行されたか、インストールが完了しなかったことを意味します。ステップ 1 のフォルダーに移動し、composer install を実行してください。
• ステップ 1 の途中で Composer が停止し、不足している PHP 拡張機能の名前を示した場合は、 その拡張機能を php.ini で有効にしてください。php -m で確認してから、インストールを繰り返してください。
• doctor の Extensions ブロックにある [FAIL] 行は、不足している PHP 拡張機能の名前を示します。php.ini で有効にし、php -m で確認してから、doctor を再度実行してください。 商用パッケージ名を示すケイパビリティの [FAIL] 行は、Core インストールでは想定どおりであり、ここでは対処は不要です。

それ以外の場合は、トラブルシューティングのナレッジベースから始めてください。スクリプトが例外をスローする場合は、エラーリファレンス でそのクラスを調べてください。初心者が遭遇するエラーのほとんどは、一般的なエラー に記載されています。

次のステップ

これで、動作するインストール環境と、最初にレンダリングされたファイルが手に入りました。 ページサイズ、組み込みフォント、色、および配置を制御するには、テキスト、フォント、ページの基本 に進んでください。