Symfony API リファレンス

概要

Symfony パッケージは、バンドル登録、設定ツリー、新しいドキュメントを生成するためにインジェクトできるファクトリー、HTTP レスポンスヘルパー、および非同期生成のための Messenger 型を公開します。大半のアプリケーションコードが直接扱うのは 2 つのシンボルだけです。インジェクトする PdfFactory サービス（Document の構築に使用）と、そのドキュメントを安全な HTTP レスポンスに変換する PdfResponse ヘルパーです。残りのシンボル（バンドル、エクステンション、コンパイラーパス、設定ツリー、Messenger DTO、ハンドラー）は、一度だけ設定する配線か、フレームワーク側で管理される配線です。

ここから始めましょう: 初めて使う場合は、NextPDF\Symfony\Service\PdfFactory をインジェクトし、create() を呼び出して新しい Document を取得し、NextPDF\Symfony\Http\PdfResponse::download() でそれを返します。以下の最初のサンプルがその流れを示しています。

よくあるタスク

よく行う作業向けに、そのまま実行できる 3 つのスニペットを示します。いずれも、以降の表に記載された検証済みのシンボルのみを使用します。

コントローラーから PDF ダウンロードを返す：ファクトリーをインジェクトし、ドキュメントを構築して、レスポンスヘルパーに渡します:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class InvoiceController
{
    #[Route('/invoice/{number}', name: 'invoice_pdf')]
    public function download(PdfFactory $pdf, string $number): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, "Invoice #{$number}");

        return PdfResponse::download($doc, "invoice-{$number}.pdf");
    }
}

動作：PdfFactory::create() は、設定済みの新しい Document を返します。PdfResponse::download() は、Content-Type: application/pdf、添付ファイルのディスポジション、およびバンドルで固定されたセキュリティヘッダーを付けてそれを送信します。

大きな PDF をストリーミングしてピークメモリーを低く抑える：ヘルパーを差し替えて StreamedResponse を返します:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\StreamedResponse;
use Symfony\Component\Routing\Attribute\Route;

final class ReportController
{
    #[Route('/report', name: 'report_pdf')]
    public function report(PdfFactory $pdf): StreamedResponse
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, 'Annual report');

        return PdfResponse::streamDownload($doc, 'annual-report.pdf');
    }
}

動作：PdfResponse::streamDownload() は、実体化された PDF をチャンク単位で送出し、Content-Length を省略します。インライン版には streamInline() を使用します。

非同期生成用に PDF をディスパッチする：レンダリングがワーカー上で実行されるように、GeneratePdfMessage を Messenger トランスポートに送信します:

<?php

declare(strict_types=1);

namespace App\Controller;

use App\Pdf\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Routing\Attribute\Route;

final class QueueController
{
    #[Route('/invoice/{id}/queue', name: 'invoice_queue')]
    public function queue(MessageBusInterface $bus, int $id): Response
    {
        $bus->dispatch(new GeneratePdfMessage(
            builderClass: InvoicePdfBuilder::class,
            outputPath: '/var/storage/invoices/' . $id . '.pdf',
            builderContext: ['invoice_id' => $id],
        ));

        return new Response('PDF generation queued.', 202);
    }
}

動作：この DTO は、ビルダーの class-string と検証済みの出力パスを保持します。ハンドラーはビルダーを resolve（解決）してドキュメントを構築し、それをワーカー上で保存します。ビルダークラスは PdfBuilderInterface を実装し、サービスロケーターに登録されます（ロケーターとワーカーの配線については Symfony クイックスタートを参照してください）。

ファクトリー

新しいドキュメントを生成する、インジェクト可能なサービスの正確なコンストラクターと create() の契約を確認する場合は、この表を参照してください。

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗の条件	備考
new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)	factory: コアファクトリー。defaults: 作成者、著者、言語、マージン。pdfa: 任意の PDF/A プロファイル。artisanConfig: 任意の Chrome レンダラー設定。	設定されている場合にのみデフォルト値を適用。	PdfFactory	コンテナー配線のエラー。	create() が新しいドキュメントを返すため、このサービスはシングルトン化可能。
PdfFactory::create()	なし。	作成者と言語を適用。著者は空でない場合にのみ適用。PDF/A と Artisan の設定は利用可能な場合にのみ適用。	NextPDF\Core\Document	コア設定のエラー。	リクエスト、コマンド、またはメッセージごとに 1 回使用。
PdfFactory::setArtisanAvailable(bool $available)	available: コンパイル時の可用性フラグ。	コンパイラーパスで有効化されるまで無効。	void	想定なし。	任意のエクステンションのコンパイラーパスから呼び出される内部フック。
PdfFactory::setProAvailable(bool $available)	available: コンパイル時の可用性フラグ。	コンパイラーパスで有効化されるまで無効。	void	想定なし。	Premium の可用性を設定する内部フック。

バンドル、エクステンション、設定

この表は配線レイヤーをまとめたものです。バンドルを登録するとき、nextpdf 設定ツリーを解決するとき、または任意エクステンションの検出を追跡するときに参照してください。2 番目の表は設定キーそのものを一覧表示します。

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗の条件	備考
NextPdfBundle::build(ContainerBuilder $container)	Symfony コンテナービルダー。	親の build メソッドを呼び出し、OptionalExtensionPass を登録。	void	コンパイラーパス登録のエラー。	任意の Artisan および Premium 機能の検出を有効化。
NextPdfBundle::getPath()	なし。	パッケージのルートパスを返却。	string	想定なし。	Symfony のバンドル検出とリソース読み込みで使用。
NextPdfExtension::load(array $configs, ContainerBuilder $container)	ユーザー設定の配列とコンテナービルダー。	指定された nextpdf 設定を処理し、解決済みのパラメーターを保存し、サービス定義を読み込んだうえで、必須の拡張モジュールを確認。	void	設定検証、サービス読み込み、または拡張モジュール不足のエラー。	必須の拡張モジュールは mbstring と zlib。
NextPdfExtension::getAlias()	なし。	ルート設定キーとして nextpdf を使用。	string	想定なし。	バンドルは nextpdf: の下で設定。
Configuration::getConfigTreeBuilder()	なし。	検証済みの nextpdf 設定ツリーを定義。	TreeBuilder	Symfony の設定定義エラー。	実用的な範囲で Laravel の設定形状を踏襲。
OptionalExtensionPass::process(ContainerBuilder $container)	Symfony コンテナービルダー。	任意の Artisan および Premium サービスを検出し、ファクトリーの可用性フラグを切り替え。	void	コンパイラーパス配線のエラー。	コンテナーのコンパイル時に実行。

設定キー	型	デフォルトの動作	備考
page_format	enum	A4。指定可能な値に A3、A5、Letter、Legal、Tabloid を含む。	デフォルトのドキュメント生成に適用。
orientation	enum	P。指定可能な値は P と L。	ページごとに異なる向きが必要な場合は、明示的なドキュメント呼び出しを使用。
unit	enum	mm。指定可能な値は pt、mm、cm、in。	フレームワークのデフォルトをコアの単位と一致。
pdfa	`string	null`	null。指定可能な値は 4、4e、4f。
fonts_path / cache_path	string	プロジェクトのフォントパスとカーネルのキャッシュパス。	実行時の役割に応じて、両方のパスを読み取り可能または書き込み可能に設定。
signature.*	array	デフォルトでは無効、署名レベルは B-B。	証明書、鍵、パスワード、追加証明書、およびレベルを指定。
tsa.*	array	URL が null の場合は無効。タイムアウトのデフォルトは 30 秒。	認証情報、mTLS ファイル、公開鍵ピン、および HTTP ポリシーをサポート。
ocsp_cache.*	array	有効、TTL は 86400 秒。	利用可能な場合、検証および長期署名のフローで使用。
messenger.*	array	トランスポートは async、タイムアウト 120、リトライ 3 回。	非同期生成のワークフローで使用。
artisan.*	array	設定済みかつインストール済みでない限り、Chrome レンダラーは無効。	任意のレンダラーが利用可能な場合、ChromeRendererConfig にマッピング。
defaults.*	array	作成者 NextPDF、著者は空、言語 en、デフォルトのマージンとフォント。	メソッド PdfFactory::create() によって適用。

HTTP レスポンス

適切なレスポンスヘルパー（インライン表示かダウンロード、バッファリングかストリーミング）を選ぶときや、各ヘルパーのファイル名とヘッダーの動作を確認するときは、この表を参照してください。

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗の条件	備考
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: 構築済みのドキュメント。filename: レスポンスのファイル名。	存在しない場合は .pdf を付加。	Symfony\Component\HttpFoundation\Response	コアのシリアライズエラー。	PDF のコンテンツタイプと防御的なヘッダーを設定。
PdfResponse::download(Document $document, string $filename = 'document.pdf')	引数は inline と同じ、ディスポジションは添付ファイル。	ブラウザー向けのダウンロードレスポンス。	Response	動作は inline と同一。	明示的なダウンロードに使用。
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	引数は inline と同じ。	実体化された PDF のバイト列をチャンク単位で送出。	StreamedResponse	動作は inline と同一。	ドキュメントの実体化は回避しない。
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	引数は streamInline と同じ、ディスポジションは添付ファイル。	ダウンロードストリームのレスポンス。	StreamedResponse	動作は streamInline と同一。	レンダリング前に出力サイズのポリシーを適用。

Messenger による連携

非同期パスを構築するとき（ディスパッチするメッセージ DTO、実装するビルダーインターフェイス、ワーカー上で実行されるハンドラー）は、この表を参照してください。

シンボル	パラメーター	デフォルトの動作	戻り値	スローまたは失敗の条件	備考
new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])	builderClass: PdfBuilderInterface を実装する class-string。outputPath: 出力先の .pdf。builderContext: シリアライズ可能なデータ。	空のコンテキスト配列。	メッセージ DTO。	InvalidArgumentException: 無効な FQCN、ストリームラッパー、null バイト、トラバーサル、空のパス、または .pdf 以外の出力先の場合にスロー。	Messenger トランスポートはクロージャーではなくデータを運搬。
PdfBuilderInterface::build(Document $document, array $context): Document	document: 設定済みの新しいドキュメント。context: シリアライズ可能なメッセージデータ。	メッセージの値以外にデフォルトのコンテキストなし。	設定済みの Document。	ビルダー固有の例外。	ビルダーは決定的かつ冪等に保つ。
new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)	PDF ファクトリーと、タグ付けされたビルダーのサービスロケーター。	構築時にドキュメントは作成しない。	GeneratePdfHandler	コンテナー配線のエラー。	ロケーターは PdfBuilderInterface の実装のみを公開すべき。
GeneratePdfHandler::__invoke(GeneratePdfMessage $message)	message: 検証済みのメッセージ DTO。	コンテナーからビルダーを解決し、ドキュメントを構築して保存。	void	ビルダーサービスの不足、無効なビルダー結果、コアの書き込みエラー。	静的コールバックよりもサービスビルダーを優先。

開発上の注意

• サービスとして Document を保持しないでください。PdfFactory を保持し、作業単位ごとに create() を呼び出します。
• キューに入れるのは、シリアライズ可能なコンテキストのみにしてください。開いたストリーム、クロージャー、またはリクエストオブジェクトを builderContext に入れないでください。
• デプロイにテナント固有のストレージルートがある場合は、出力パスのポリシーを DTO より厳格に保ってください。