NextPDF Artisan のインストール

概要

Composer で nextpdf/artisan をインストールします。これにより、ランタイム依存関係である chrome-php/chrome も取り込まれます。続いて、Chrome または Chromium のバイナリを PHP プロセスから利用できるようにします。

インストール

composer require nextpdf/artisan

このパッケージは composer.json で次の制約を宣言します。

要件	制約	備考
`php`	`>=8.4 <9.0`	PHP 8.4 のみ
`nextpdf/core`	`^3.0 \|\| ^5.2`	オープンソースの NextPDF エンジン
`chrome-php/chrome`	`^1.15`	CDP クライアントライブラリ。推移的に取り込まれます
`psr/log`	`^3.0`	任意のロガー注入ポイント

Composer は chrome-php/chrome を自動的に resolve（解決）します。Chrome の バイナリ はシステム依存関係であり、Composer によってインストールされることはありません。

Chrome バイナリのプロビジョニング

ブリッジには、実行可能な Chrome または Chromium が必要です。デフォルトでは、chrome-php/chrome が一般的なパス上にあるバイナリを自動検出します。明示的なパスを固定する場合は、設定を通じて渡します。/integrations/artisan/configuration/ および専用の /integrations/artisan/chrome-renderer-setup/ ページを参照してください。

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

アプリケーションに組み込む前に、バイナリがヘッドレスで動作することを確認してください。

chromium --headless --dump-dom about:blank

正常に実行されると、空の DOM ドキュメントが出力され、終了コード 0 で終了します。ゼロ以外の終了は、バイナリまたはその共有ライブラリが不足していることを意味します。ブリッジはレンダリング時に同じ失敗を ChromeRenderException として報告するため、続行する前に修正してください。

パッケージが正しく組み込まれていることの確認

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\ChromeHtmlRenderer;

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

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig());

echo $renderer->getHtmlSecurityPolicy()->getName(), PHP_EOL;
// Prints: default

これはレンダラーを構築し、Chrome を起動せずにデフォルトの HTML セキュリティポリシーを読み戻します。これにより、オートローディングと nextpdf/core のコントラクトバインディングが解決されることを確認できます。（この動作は tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected によって表明されています。）

コンテナへのインストール

Docker では、Chrome サンドボックスは通常、追加のカーネルケーパビリティなしに PID 1 / root として起動できません。このケースに備えて、このパッケージは noSandbox スイッチを公開しています。Chrome サンドボックスを無効化すると、実際のセキュリティ上のコストが発生します。/integrations/artisan/security-and-operations/ ページと /integrations/artisan/chrome-renderer-setup/ では、そのコストを文書化し、制限を明示しています。そのセクションを読まずにこのスイッチを設定しないでください。

エッジケースと注意点

chrome-php/chrome は存在するがバイナリがない場合。 Composer は成功しますが、最初のレンダリングで、起動失敗をラップした ChromeRenderException がスローされます。ライブラリのチェックは、バイナリのチェックとは別です。
chrome-php/chrome が存在しない場合。 ライブラリがオートローダーから削除されると、BrowserPool::getBrowser() は、正確な修復コマンドを伴う ChromeNotAvailableException をスローします。（tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable によって表明されています。）
バージョン制約。 nextpdf/core: ^3.0 || ^5.2 — Artisan は両方の core メジャーラインをサポートします。アプリケーションが対象とする core バージョンを固定してください。

セキュリティに関する注意

ブリッジをインストールすると、外部プロセス（Chrome）が信頼境界内に入ります。いずれかのレンダリングパスをユーザー提供の HTML に公開する前に、/integrations/artisan/security-and-operations/ を確認してください。