Pro エディション

チャート

概要

NextPDF Pro は、棒グラフ、折れ線グラフ、円グラフを、ベクトルコンテンツ演算子として PDF ページに直接描画します。ラスタライズの工程もヘッドレスブラウザへの依存もないため、出力は決定的かつ再現可能です。

インストール

composer require nextpdf/pro:^3

概念の概要

チャートモジュールは、3 種類のネイティブチャートレンダラーを提供します。それぞれが自己完結型の描画プリミティブであり、指定した固定の矩形ボックス内に描画します。リフローも、コンテナの認識も、レイアウトの調整もありません。ボックスを配置するのはあなたであり、レンダラーはそれを塗りつぶします。

棒グラフ — バーの色、軸の色、バー間隔、ラベルのフォントサイズを設定できる縦棒グラフです。
折れ線グラフ — 系列ごとの色、任意のデータポイントマーカー、任意のグリッド、設定可能な線幅を備えた、単一系列または複数系列の折れ線グラフです。
円グラフ — 自動的なパレット割り当て、任意のパーセンテージラベル、任意の凡例を備えた円形チャートです。

すべてのレンダラーは同じ形を踏襲します。fromData(...) ファクトリ、流れるような with*() 設定、そして PDF コンテンツストリーム演算子を返す render(ChartBox $box): string 呼び出しです。出力は決定的であり、同一の入力と設定からは同一の演算子が生成されます。これにより、チャートを含むドキュメントは再現可能なまま保たれ、署名やアーカイブにも安全に対応できます。

レンダラーは画像ではなくベクトル演算子を出力するため、チャートはどのズーム倍率でも鮮明なままで、ドキュメントにラスターのペイロードを追加しません。

この設計の理由

設計の核となる決定は、画像をラスタライズしたりヘッドレスブラウザを駆動したりするのではなく、ネイティブの PDF ベクトル演算子を出力することです。この選択により出力は決定的になります。同一のデータと設定からは、常にバイト単位で同一の演算子が生成されます。決定的な演算子は、チャートを含むドキュメントを再現可能に保ち、そのため署名やアーカイブにも安全です。外部レンダラーを避けることでプロセス依存も排除されるため、スループットはブラウザの起動コストではなくデータポイント数に応じてスケールします。各レンダラーは演算子を q/Q のグラフィックス状態ペアで包み、リフローを行わないため、予測可能かつ低コストに合成できます。

設計背景：大量ドキュメント生成。

API サーフェス

composer require nextpdf/pro:^3

チャートの公開サーフェスは、NextPDF\Pro\Chart 内の 5 つのクラスです。

BarChart — fromData()、withBarColor()、withAxisColor()、withBarGap()、withFontSize()、render()。
LineChart — create()、fromData()、addSeries()、withAxisColor()、withLineWidth()、withFontSize()、withDots()、withGrid()、render()。
PieChart — fromData()、withColors()、withStrokeColor()、withFontSize()、withPercentages()、withLegend()、render()。
ChartBox — 配置用の矩形です。fromUserSpace() は、左上原点のユーザー空間の矩形を PDF の左下原点に変換します。inset() はパディング用です。
ChartColor — rgb()、hex()、palette()、ならびにストローク/フィル演算子のエミッターです。

コードサンプル — クイックスタート

use NextPDF\Pro\Chart\BarChart;
use NextPDF\Pro\Chart\ChartBox;

$box = ChartBox::fromUserSpace(72, 72, 400, 240, pageHeight: 842);
$stream = BarChart::fromData(['Q1', 'Q2', 'Q3', 'Q4'], [100, 200, 150, 300])
    ->render($box);
// $stream is appended to the target page content.

コードサンプル — 本番

use NextPDF\Pro\Chart\ChartBox;
use NextPDF\Pro\Chart\ChartColor;
use NextPDF\Pro\Chart\LineChart;

$box = ChartBox::fromUserSpace(72, 72, 460, 260, pageHeight: 842)
    ->inset(8, 8, 8, 8);

$stream = LineChart::create(['Jan', 'Feb', 'Mar', 'Apr'])
    ->addSeries('Revenue', [120, 180, 150, 220], ChartColor::hex('#336699'))
    ->addSeries('Cost', [80, 90, 110, 130], ChartColor::palette(1))
    ->withGrid(true)
    ->withDots(true, 2.5)
    ->withLineWidth(1.2)
    ->render($box);

エッジケースと落とし穴

空のデータは例外を投げるのではなく空文字列を返すため、データセットが存在しない場合はページを壊すことなく何も描画しません。
合計がゼロまたは負の円グラフは、空文字列を返します。
単一のポイントしか持たない折れ線系列は、線分を描画しません（単一のポイントにはパスがありません）。
寸法がゼロの ChartBox は意味のある描画を行いません。描画前にボックスのサイズを設定してください。
レンダラーはボックスにクリップしません。意図するページ領域に収まるボックスを指定してください。

パフォーマンス

描画はシングルパスで、データポイント数に対して線形です。ラスタライズも、画像バッファも、外部プロセスもありません。出力される演算子文字列のサイズが、メモリコストの上限を決めます。複数系列の折れ線グラフは、系列をまたいだ合計ポイント数に対して線形にスケールします。

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

チャートレンダラーは、数値とラベルのデータのみを取り込みます。入力を評価したり実行したりすることはありません。レンダラーはラベルを PDF テキスト演算子として出力し、それらを解釈することはありません。モジュールはチャートデータをログに記録しません。機密性のあるラベルは、チャート化する前にアプリケーション側でサニタイズする必要があります。

適合性

チャートは外部標準の規制対象ではありません。出力は、ISO 32000-2 のコンテンツストリームセマンティクスに従ってページに描画される PDF コンテンツストリームです。このモジュールには、シンボロジーや暗号に関する適合性サーフェスはありません。

公開の境界

このページは、外部から観測可能な動作とサポートされる公開 API サーフェスのみを記載します。内部の名前空間パス、ヘルパークラス、メカニズムの一覧表、ランブックのファイル名、チケットのプレフィックスは対象外です。