CodeIgniter API リファレンス

概要

CodeIgniter パッケージは、小さなコントローラー向けのインターフェイスを公開します。含まれるのは、1 つのドキュメントをラップする Pdf ライブラリラッパー（Services::pdf() とグローバルな pdf() ヘルパー）、ビルド済みドキュメントを DownloadResponse に変換するレスポンスヘルパー（PdfResponse）、その背後にある Services ファクトリ（フォント/画像レジストリ、ドキュメントファクトリ、任意の署名者と TSA クライアント）、NextPdf 設定クラス、そして静的ビルダー callable による非同期生成のための GeneratePdfJob です。

まずはここからです。コントローラーで Services::pdf()（または pdf() ヘルパー）を呼び出し、$pdf->document() にコンテンツを追加し、$pdf->download('file.pdf') を返します。この 1 つのパスだけで、最も一般的なタスクをカバーできます。下記のリファレンス表は機能面ごとに整理されています。「よくあるタスク」セクションでは、実行可能な形を最初に示します。

よくあるタスク

これらは、最も頻繁に発生する実際のフローです。各サンプルは nextpdf/codeigniter に対してソース検証済みです。

コントローラーからダウンロード可能な PDF を返す：標準のレンダリングパス。

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, "Invoice #{$id}");

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

動作：新しい Document をラップした新しい Pdf が resolve（解決）され、1 つのセルを書き込み、ディスポジション attachment とパッケージのセキュリティヘッダーを備えた DownloadResponse を返します。

ブラウザー内で PDF をインラインプレビューする：同じラッパーで、download() の代わりに inline() を使います。

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;

final class ReportController extends BaseController
{
    public function preview(): DownloadResponse
    {
        $pdf = pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly Report');

        return $pdf->inline('report.pdf');
    }
}

動作：グローバルな pdf() ヘルパー（Services::pdf() と同等）を使い、DownloadResponse をディスポジション inline で返すため、ブラウザーは PDF をダウンロードせずに表示します。

キューで PDF を非同期生成する：静的ビルダーを使って GeneratePdfJob を push します。

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

service('queue')->push('pdf', GeneratePdfJob::class, [
    'builder'    => 'App\PdfBuilders\InvoiceBuilder::build',
    'outputPath' => WRITEPATH . 'pdfs/invoice-42.pdf',
    'context'    => ['invoice_id' => 42],
]);

動作：生成をキューに登録します。ワーカーは、ビルダー（App\PdfBuilders\...::method の静的 callable である必要があります）と出力パス（WRITEPATH/pdfs/ 配下に解決され、.pdf で終わる必要があります）を検証し、新しいドキュメントをビルドしてから保存します。

ライブラリラッパー

この表は、Pdf ラッパーを保持していて、そのレスポンスまたは保存メソッドが必要な場合に参照します。

シンボル	パラメーター	デフォルト動作	戻り値	スローされる例外・失敗条件	備考
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`：新しいコアドキュメント。	渡されたドキュメントを、1 回のレスポンスまたは保存操作のためにラップします。	`Pdf`	想定されるものはありません。	出力後はラッパーを再利用しないでください。
`Pdf::document()`	なし。	ラップされたドキュメントを返します。	`NextPDF\Core\Document`	想定されるものはありません。	コアのオーサリング API を呼び出すときに使います。
`Pdf::inline(string $filename = 'document.pdf')`	`filename`：レスポンスのファイル名。	ブラウザーのインラインディスポジション。	`CodeIgniter\HTTP\DownloadResponse`	コアのシリアライゼーションエラー。	委譲先は `PdfResponse::inline()`。
`Pdf::download(string $filename = 'document.pdf')`	`filename`：レスポンスのファイル名。	ブラウザーの attachment ディスポジション。	`DownloadResponse`	コアのシリアライゼーションエラー。	委譲先は `PdfResponse::download()`。
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`：レスポンスのファイル名。	他のフレームワークパッケージとの API パリティ。	`DownloadResponse`	コアのシリアライゼーションエラー。	CodeIgniter はバイナリ出力をネイティブに処理します。
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`：レスポンスのファイル名。	他のフレームワークパッケージとの API パリティ。	`DownloadResponse`	コアのシリアライゼーションエラー。	非ストリームレスポンスと同じサイズ制御を使用します。
`Pdf::save(string $path)`	`path`：ファイルシステム上の出力先。	ラップされたドキュメントを書き込みます。	`void`	ファイルシステムまたはコアの書き込みエラー。	保存前にストレージのルートを検証します。

サービスとヘルパー

特定のサービスファクトリやグローバルヘルパー関数が必要で、共有動作と戻り値の型を確認したい場合に参照します。

シンボル	パラメーター	デフォルト動作	戻り値	スローされる例外・失敗条件	備考
`Services::fontRegistry(bool $getShared = true)`	`getShared`：CodeIgniter の共有サービスフラグ。	設定済みのフォントでウォームアップされ、その後ロックされる共有レジストリ。	`FontRegistryInterface`	`RuntimeException`（拡張機能の不足、または安全でないフォントパス）。	`fontsPath` 内のストリームラッパーと null バイトを拒否します。
`Services::imageRegistry(bool $getShared = true)`	`getShared`：共有サービスフラグ。	上限付きの共有 LRU 画像レジストリ。	`ImageRegistry`	想定されるものはありません。	キャッシュサイズは `imageCacheMb` で制御されます。
`Services::documentFactory(bool $getShared = true)`	`getShared`：共有サービスフラグ。	共有レジストリを使用する共有ファクトリ。	`DocumentFactoryInterface`	レジストリのセットアップエラー。	ファクトリは再利用可能ですが、ドキュメントは再利用できません。
`Services::tsaClient(bool $getShared = true)`	`getShared`：共有サービスフラグ。	戻り値は `null`（`tsa.url` が空のとき）。	`TsaClient	null`	HTTP クライアントまたは TSA 設定のエラー。
`Services::pdfSigner(bool $getShared = false)`	`getShared`：共有サービスフラグ。	署名が無効のときは `null` を返します。	`SignerInterface	null`	証明書または署名レベルのエラー。
`Services::pdfDocument(bool $getShared = false)`	`getShared`：共有サービスフラグ。	新しいドキュメントを作成し、デフォルトを適用し、必要に応じて PDF/A または Artisan を設定します。	`Document`	任意の拡張機能またはドキュメント設定のエラー。	リクエストの安全性のため、デフォルトの `false` のままにします。
`Services::pdf(bool $getShared = false)`	`getShared`：共有サービスフラグ。	新しいドキュメントをラップする新しい `Pdf` ラッパーを作成します。	`NextPDF\CodeIgniter\Libraries\Pdf`	ドキュメントのセットアップエラー。	メインとなるコントローラー向けサービス。
`Services::eInvoiceEmbedder()`	なし。	Premium Pro の電子インボイス埋め込みクラスが存在しない限り、`null` を返します。	`EmbedderInterface	null`	任意のパッケージの構築エラー。
`Services::eInvoiceValidator()`	なし。	Premium Enterprise のバリデータクラスが存在しない限り、`null` を返します。	`ValidatorInterface	null`	任意のパッケージの構築エラー。
`Services::eInvoiceProfile()`	なし。	Premium Pro がインストールされているときは EN16931 プロファイルを返します。	`ProfileInterface	null`	任意のパッケージエラー。
`Services::schematronRunner()`	なし。	Premium Enterprise の Schematron バリデータが存在しない限り、`null` を返します。	`SchematronRunnerInterface	null`	任意のパッケージの構築エラー。
`Registrar::Autoload()`	なし。	パッケージヘルパーを CodeIgniter のオートロード設定に追加します。	`array`	想定されるものはありません。	モジュールが読み込まれたときに `pdf()` と `pdf_document()` を有効にします。
`pdf()`	なし。	呼び出し先は `Services::pdf(false)`。	`Pdf`	ドキュメントのセットアップエラー。	コントローラー向けの便利ヘルパー。
`pdf_document()`	なし。	呼び出し先は `Services::pdfDocument(false)`。	`Document`	ドキュメントのセットアップエラー。	コアのドキュメント API を使いたいときの便利ヘルパー。

HTTP レスポンス

ビルド済みの Document をすでに保持していて、Pdf ラッパーを介さずに DownloadResponse を自分で構築したい場合に参照します。

シンボル	パラメーター	デフォルト動作	戻り値	スローされる例外・失敗条件	備考
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`：ビルド済みドキュメント。`filename`：レスポンスのファイル名。	保証されるのは `.pdf` 拡張子とインラインディスポジション。	`DownloadResponse`	コアのシリアライゼーションエラー。	PDF コンテンツタイプと防御的ヘッダーを追加します。
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	動作は `inline` と同じ。ディスポジションは attachment。	保証されるのは `.pdf` 拡張子。	`DownloadResponse`	動作は `inline` と同じ。	ブラウザーでのダウンロードに使用します。
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	動作は `inline` と同じ。	CI4 では `inline` と同じ動作。	`DownloadResponse`	動作は `inline` と同じ。	フレームワーク間の API パリティのために存在します。
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	動作は `download` と同じ。	CI4 では `download` と同じ動作。	`DownloadResponse`	動作は `download` と同じ。	フレームワーク間の API パリティのために存在します。

キュージョブ

非同期生成を配線し、正確なジョブデータキーとビルダー callable の契約を確認したい場合に参照します。

シンボル	パラメーター	デフォルト動作	戻り値	スローされる例外・失敗条件	備考
`GeneratePdfJob::process()`	ジョブデータのキー：`builder`、`outputPath`、任意の `context`。	省略時は空の context 配列を使用します。	`void`	`InvalidArgumentException`（安全でないビルダーまたは出力パス）、およびコアの書き込みエラー。	ビルダーは `App\PdfBuilders\...\*::method` である必要があります。
ビルダー callable	`Document $doc`、`array $context`。	ジョブデータ以外のデフォルトの context はありません。	`Document`	ビルダー固有の例外。	CI4 のキューペイロードはシリアライズされたデータであるため、静的 callable が必要です。

設定

デフォルト（ページ形式、パス、署名、TSA、ドキュメントメタデータ）を NextPdf 設定クラスで変更する場合に参照します。

プロパティ	型	デフォルト動作	備考
`pageFormat`	`string`	`A4`。	デフォルトのページ形式。
`orientation`	`string`	`P`。	デフォルトの向き。
`unit`	`string`	`mm`。	デフォルトの単位。
`pdfa`	`string	null`	`null`。
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` と `WRITEPATH . 'cache/nextpdf'`。	パスはアプリケーションが管理するストレージ内に保持します。
`signature`	`array`	レベル `B-B` で無効。	証明書、鍵、パスワード、追加証明書、およびレベル。
`tsa`	`array`	URL が `null` のときは無効。タイムアウトは 30 秒。	資格情報、mTLS ファイル、公開鍵ピン、および HTTP ポリシー。
`ocspCache`	`array`	86400 秒の TTL で有効。	利用可能な場合は署名検証フローで使用されます。
`preloadFonts`	`list<string>`	空。	レジストリがロックされる前にウォームアップされます。
`imageCacheMb`	`int`	`50`。	プロセス存続期間中の画像キャッシュを制御します。
`fontCacheLocking`	`bool`	`true`。	リクエスト処理中のフォントレジストリ変更を除外します。
`artisan`	`array`	設定済みかつインストール済みでない限り、Chrome レンダラーは無効です。	マッピング先は `ChromeRendererConfig::fromArray()`。
`defaults`	`array`	作成者は `NextPDF`、作者は空、言語は `en`、デフォルトの余白とフォント。	`Services::pdfDocument()` は `creator`、`language`、および（空でない場合）`author` のみを適用します。`margin_top`/`right`/`bottom`/`left`、`font_family`、`font_size`、`trim_box`、および `bleed_box` キーは定義済みのデフォルトですが、現在は適用されません。

開発上のメモ

GeneratePdfJob は出力を WRITEPATH . 'pdfs' に限定し、.pdf を要求します。
改ざんされたキューペイロードによる任意コード実行を避けるため、App\PdfBuilders 外のビルダー callable は拒否されます。
コントローラーフローには service('pdf') またはパッケージヘルパーを使用し、長時間の生成にはキュージョブを使用します。