CodeIgniter 開発者向けガイド

概要

CodeIgniter パッケージは、サービスファクトリ、ヘルパー関数、1 つのドキュメントをラップする小さな Pdf ライブラリラッパーを公開します。このラッパーはコントローラーから使うと便利です。CodeIgniter のキューペイロードはシリアライズ済みデータであるため、キュー処理では静的なビルダー callable を使用します。

コントローラーのフロー、サービス、キュービルダー、またはテストを nextpdf/codeigniter を中心に設計する際は、このガイドを参照してください。

アーキテクチャの境界

レイヤー	所有元	責務	ここに配置しないもの
コントローラー	アプリケーション	認可、ビルダーまたはサービスの呼び出し、`DownloadResponse` の返却	共有レイアウトロジック
ライブラリラッパー	`nextpdf/codeigniter`	1 つの `Document` のラップと、response/save ヘルパーの提供	長期保持するドキュメントの保存
サービスファクトリ	`nextpdf/codeigniter`	共有レジストリと新規ドキュメントの作成	業務固有のストレージルート
キュービルダー	アプリケーション	静的な callable 入力からのドキュメントビルド	リクエストオブジェクトやシリアライズできない状態
コアエンジン	`nextpdf/nextpdf`	PDF のビルドとシリアライズ	CodeIgniter のレスポンスやキューのポリシー

ランタイムのライフサイクル

ステージ	動作	開発者のアクション
オートロードの登録	`Registrar::Autoload()` によるモジュールのヘルパー読み込み登録	CodeIgniter の設定を通じたモジュール読み込み
サービスの resolve（解決）	`Services::pdf()` のデフォルト動作として、新規ドキュメントをラップするラッパーの返却	リクエストごとに 1 回のみ解決
オーサリング	アプリケーションコードによる、コアのドキュメント呼び出しへの `Pdf::document()` の使用	ドキュメント構築コードのサービスまたはビルダーへの配置
レスポンス	`PdfResponse` による `DownloadResponse` の返却	PDF ヘッダー設定のパッケージへの委譲
キューの実行	`GeneratePdfJob::process()` による、ビルダーと出力パスの検証後の保存	キュービルダーの `App\PdfBuilders` 配下への配置

推奨されるアプリケーション構成

パス	目的
`app/PdfBuilders/*`	`GeneratePdfJob` が受け付ける、静的でキューセーフなビルダー
`app/Libraries/*`	繰り返し発生するドキュメントワークフローをラップする任意のアプリケーションラッパー
`app/Services/*`	ドメインデータの取得とストレージポリシー
`app/Config/NextPdf.php`	パッケージ設定に対するアプリケーション側オーバーライド
`tests/app/PdfBuilders/*`	ビルダーとキューペイロードのテスト

短いフローではパッケージのヘルパーを使用してください。ドキュメント構築が直接テストすべきクラスに属する場合は、明示的なサービス呼び出しを使用してください。

<?php

namespace App\Controllers;

final class InvoiceController extends BaseController
{
    public function download(int $id)
    {
        $pdf = pdf();
        $pdf->document()
            ->setTitle('Invoice ' . $id)
            ->addPage()
            ->writeHtml('<h1>Invoice ' . $id . '</h1>');

        return $pdf->download('invoice-' . $id . '.pdf');
    }
}

キュービルダーのパターン

キュービルダーは静的かつ決定論的で、App\PdfBuilders の下に配置する必要があります。コンテキスト配列は、シリアライズと監査が容易な程度に単純な状態に保ってください。

<?php

namespace App\PdfBuilders;

use NextPDF\Core\Document;

final class InvoiceBuilder
{
    public static function build(Document $document, array $context): Document
    {
        $document->setTitle((string) $context['title'])
            ->addPage()
            ->writeHtml((string) $context['html']);

        return $document;
    }
}

ジョブは、出力先を設定済みのアプリケーション PDF ディレクトリ内に限定します。アプリケーションでテナント固有のストレージが必要な場合は、そのポリシーを 1 つのサービスに集約し、キューのディスパッチ前にテストしてください。

拡張ポイント

拡張ポイント	用途	制約
`Services::pdfDocument()`	ドキュメント作成のカスタマイズ	新規ドキュメントの返却が必須
`Services::fontRegistry()`	フォントのウォームアップとレジストリへのアクセス	安全でないパスの拒否と、ウォームアップ後のレジストリロック維持
`Services::pdfSigner()`	任意のデジタル署名	署名が無効な場合の `null` 返却
`NextPDF\CodeIgniter\Libraries\Pdf`	コントローラー向けラッパー	1 つのラッパーにつき 1 つのドキュメント
`App\PdfBuilders::*`	キューセーフなドキュメントビルダー	静的な callable 文字列が必須
`app/Config/NextPdf.php`	アプリケーションのデフォルトと統合設定	本番環境の値の明示指定を維持

開発ワークフロー

コントローラーから始めて、pdf() または service('pdf') を呼び出します。
繰り返し発生するドキュメント構築は、app/PdfBuilders またはアプリケーションサービスに移動します。
リクエストパスで生成すると遅すぎる場合は、GeneratePdfJob を使用します。
キューのコンテキストは、シリアライズ可能で小さい状態に保ってください。
意図的にポリシーを拡張する場合を除き、出力は承認済みの PDF ストレージルート配下に保存してください。
ヘルパー、サービス、キューペイロード、および安全でないパスに対するテストを追加してください。

障害処理

障害	処理すべき場所	推奨される対応
拡張機能の欠如または安全でないフォントパス	サービスファクトリ	サービス解決時の早期失敗
無効なビルダー callable	キュージョブの検証	ジョブの拒否と、シークレットを含めないビルダー文字列のログ記録
安全でない出力パス	ストレージサービスとキュージョブ	ディスパッチ前の拒否と、ジョブ検証の維持
レスポンスのシリアライズエラー	コントローラーまたはフレームワークのエラー処理	部分的なレスポンスボディを送信しないこと
任意の Premium クラスが利用できない	サービスメソッドの戻り値	任意の e-invoice 機能使用前の `null` の明示的な処理

安全なデフォルト

関心事	デフォルト	オーバーライドするタイミング
キュービルダーの名前空間	`App\PdfBuilders`	セキュリティポリシーも併せて更新しない限り、デフォルトを維持
出力ルート	`WRITEPATH/pdfs`	より強力な許可リストを伴う場合のみオーバーライド
レスポンスのファイル名	`document.pdf`	サニタイズ済み業務用ファイル名の使用
ストリームメソッド	他のフレームワークとの API の同等性	CodeIgniter では、ストリーミングをメモリ境界として頼らないこと
ドキュメントサービス	デフォルトで新規	リクエストコード内で共有ドキュメントを要求しないこと

テストチェックリスト

サービステストでは、Services::pdf() を解決するたびに独立したドキュメントが返ることを検証します。
ヘルパーテストでは、pdf() と pdf_document() が新規オブジェクトを返すことを検証します。
レスポンステストでは、ヘッダーとファイル名の正規化を検証します。
キューテストでは、無効なビルダー文字列と安全でない出力パスを対象にします。
ビルダーテストは、代表的なコンテキストデータを使って実行します。
設定テストでは、フォントパス、キャッシュパス、署名の無効化、および TSA の無効化の各状態を対象にします。