最初の PDF

概要

このチュートリアルでは、2 つの PDF ファイルを生成します。1 つ目では、流れるように記述できるコアの Application Programming Interface（API）を使い、テキストを直接書き込みます。2 つ目では、HyperText Markup Language（HTML）と Cascading Style Sheets（CSS）のフラグメントをページにレンダリングします。最後には、実際のドキュメントに合わせて応用できる、動作するスクリプトが手に入ります。また、フレームワーク版とサーバー版の参照先も確認できます。

どちらの方法も、同じエンジン上で動作します。そのため、ここで学ぶ内容は、すべてのディストリビューションにそのまま引き継がれます。

次の図は、2 つのオーサリング方法と、それらを再利用する 3 つのデプロイ先を示しています。

From your code to a PDF file

始める前に

必要なものは 2 つです。インストール済みのコアエンジンと、PHP スクリプトを実行できる環境です。

1. ランタイムで PHP 8.4 を利用できることを確認します。

   php --version

2. コアエンジンがまだプロジェクトに含まれていない場合は、インストールします。

   composer require nextpdf/core

3. プロジェクトのルートに first-pdf.php という名前の作業用ファイルを作成します。

標準 14 フォントは設定なしで使えます

デフォルトの本文フォントは、ISO 32000-2 で規定された標準 14 種類の Type 1 フォントのいずれかに resolve（解決）されます。そのため、最初のドキュメントではフォントファイルは必要ありません。カスタムフォントは、デザイン上必要になった時点で、後から登録して埋め込みます。

PHP から PDF を生成する

まずは、流れるように記述できる API から始めます。Document::createStandalone() は、すぐに使えるドキュメントを返します。ページを追加し、フォントを設定し、セルを書き込んでから保存します。各オーサリングメソッドはドキュメントを返すため、呼び出しを上から下へ自然に読み進められます。

1. 次のコードを first-pdf.php に記述します。このスクリプトは strict types を宣言し、オートローダーを読み込んで、1 ページのドキュメントを構築します。

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('My first NextPDF document');
   $document->addPage();
   
   $document->setFont('helvetica', 'B', 24);
   $document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
   
   $document->setFont('helvetica', '', 12);
   $document->cell(0, 10, 'This is the first PDF I generated with PHP.', newLine: true);
   
   $document->save(__DIR__ . '/first-pdf.pdf');
   
   echo "Wrote first-pdf.pdf\n";

2. スクリプトを実行します。

   php first-pdf.php

3. 出力を確認します。標準出力に次の行が表示され、スクリプトと同じ場所に first-pdf.pdf という新しいファイルが作成されます。

   Wrote first-pdf.pdf

これで、有効な PDF 2.0 ファイルが生成されました。任意のビューアーで開くと、見出しとその下の行が表示されます。

save と output の違い

save() は、ドキュメントを指定したファイルパスに書き込みます。バイト列をブラウザーへストリーミングする場合は、代わりに output() を呼び出します。バイト列をメモリ内に取得するには、getPdfData() を呼び出します。ドキュメントは 1 回限りの使用です。一度書き込んだ後は再利用せず、次のドキュメント用に新しいインスタンスを作成してください。

HTML を PDF にレンダリングする

セルを書き込む方法なら細かく制御できます。ただし、ほとんどのドキュメントは、HTML と CSS で表現したほうが速く記述できます。コアエンジンには、純粋な PHP による HTML パイプラインが含まれています。その中の writeHtml() メソッドは、フラグメントを現在のページにレンダリングします。ブラウザーも外部サービスも使用しません。

1. HTML フラグメントをレンダリングする 2 つ目のファイルとして、html-pdf.php を作成します。

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('HTML to PDF');
   $document->addPage();
   
   $html = <<<'HTML'
   <h1 style="color: #1E3A8A;">HTML rendering in NextPDF</h1>
   <p>NextPDF renders <strong>HTML content</strong> directly into PDF pages.</p>
   <ul>
       <li>Headings, paragraphs, and lists</li>
       <li>Inline <strong>bold</strong> and <em>italic</em></li>
       <li>Inline styles such as color and font-size</li>
   </ul>
   HTML;
   
   $document->writeHtml($html);
   
   $document->save(__DIR__ . '/html-pdf.pdf');
   
   echo "Wrote html-pdf.pdf\n";

2. 実行します。

   php html-pdf.php

3. 出力された行と新しいファイルを確認します。

   Wrote html-pdf.pdf

HTML 入力は信頼できないものとして扱う

HTML がユーザー、フォーム、その他の外部ソースから渡される場合は、writeHtml() に渡す前に、検証してサニタイズしてください。HTML を PDF ページにレンダリングする レシピでは、セキュリティ対策の全体像とストリーミングモデルについて説明しています。

エンジンは、サポートされている HTML と CSS のサブセットをレンダリングします。特定のプロパティに依存する前に、CSS サポートマトリックス で確認してください。レイアウトにブラウザーと同等の完全な再現性が必要な場合（たとえば flexbox、grid、Web フォントなど）は、Artisan レンダラー をインストールし、代わりに writeHtmlChrome() を呼び出します。このメソッドでは、テキストは選択可能な状態に保たれます。

フレームワークのコントローラーから

アプリケーションがすでにフレームワーク上で、またはサーバーとして動作している場合もあります。先ほどと同じ 2 つの呼び出しは、その環境にそのまま移せます。エンジンはまったく同じで、変わるのは接続部分だけです。

Laravel

Pdf ファサードは、呼び出しごとに新しいドキュメントを解決します。PdfResponse は、ドキュメントをダウンロードレスポンスに変換します。

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

詳しくは Laravel クイックスタート を参照してください。

Symfony

このバンドルは、PdfFactory サービスを公開します。コントローラーで NextPDF\Symfony\Service\PdfFactory を型ヒントとして指定し、同じ方法でドキュメントを構築してから、HTTP レスポンスとして返します。Symfony クイックスタート を参照してください。

Server (REST)

NextPDF Server を実行した状態で、順序付けされた操作の配列を POST すると、サーバーが PDF のバイト列を返します。

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

ステータスコードが 200 のレスポンスの場合、ボディが PDF になります。Connect クイックスタート を参照してください。

次のステップ

これで、3 通りの方法で PDF を生成しました。ここでは、それぞれの方法から次に進む先を紹介します。

HTML を PDF ページにレンダリングする HTML の完全なレシピ。サポートされる要素、ストリーミングモデル、セキュリティ対策を取り上げます。

進む道を選ぶ コア、フレームワーク、サーバーのいずれを使うか、またどの HTML レンダラーを使うかを決めます。

コアエンジンリファレンス Document のすべてのメソッド、パラメーター、戻り値を取り上げます。

クックブック スタイル設定、テーブル、ページネーションなど、タスクに焦点を当てたレシピです。