Pro エディション

Optimizer

概要

Optimizer は、PDF を重複オブジェクトと画像の再圧縮の可能性について分析し、推定されるサイズ削減量を報告します。3 つのレベルが、出力の忠実度とファイルサイズのトレードオフを調整します。

提供とライセンス

この機能は NextPDF Pro（nextpdf/pro）に同梱され、Pro ティアのライセンスエンベロープで有効化されます。その権限を持たないデプロイでは、この機能のクラスはロードされません。エディションを比較してライセンスを取得する。

機能ごとの個別のライセンスフラグはありません。最適化レベル（lossless、balanced、aggressive）は、ライセンスのスイッチではなくランタイムのパラメーターです。

インストール

composer require nextpdf/pro:^3

コードは NextPDF\Pro\Optimizer 名前空間の下にあります。

概念の概要

PdfOptimizer は、オブジェクトの重複排除と画像の再圧縮を調整します。生の PDF バイト列を与えると、（レベルが許す場合に）重複オブジェクトのグループを見つけ、画像を分析し、レベルの目標品質で各画像の圧縮を推定します。それらの所見を集約して OptimizationResult にまとめ、元のサイズ、推定された最適化後のサイズ、除去されたオブジェクト、そして前後の画像数を報告します。

OptimizationLevel はトレードオフを定義します。lossless は画像品質を保ち、バイト安定な出力のために重複排除をスキップします。balanced は重複排除を行い、画像品質を 75 パーセントに目標設定します。aggressive は重複排除とダウンサンプリングを行い、品質を 50 パーセントに目標設定します。

なぜこの仕組みなのか

Optimizer は書き換えではなく分析を行います。analyze() は削減の可能性を推定し、入力を変更せずに OptimizationResult を返します。これにより、このパスは非破壊的に保たれ、Writer を通じて適用するかどうかを判断できます。レベルの抽象化は、トレードオフを一箇所に集約します。lossless は deduplicateStreams() から false を返すため出力をバイト同一に保つことができ、balanced と aggressive はより低い品質目標で画像ストリームを再圧縮します。達成可能な削減量は、文書がストリームと画像をすでにどのようにエンコードしているかに依存するため、このモジュールは固定の見出し値ではなく、実際に存在するオブジェクトから推定値を報告します。設計の背景についてはストリームとフィルターを参照してください。

振る舞いの契約

analyze($pdfData) は OptimizationResult を返します。入力を変更しません。
lossless レベルは、出力をバイト安定に保てるようストリームの重複排除をスキップします。balanced と aggressive は重複排除を有効にします。
画像品質の目標は、lossless、balanced、aggressive についてそれぞれ 100、75、50 パーセントです。
推定された最適化後のサイズは、決してゼロを下回らず、元のサイズを超えることもありません。
withLevel($level) は要求したレベルの新しい Optimizer を返します。インスタンスは変更されません。

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

以下は、文書化された公開 API を反映したものです。このモジュールについては、リポジトリに実行可能な例は付属していません。

use NextPDF\Pro\Optimizer\PdfOptimizer;

$result = (new PdfOptimizer())->analyze($pdfBytes);

コードサンプル — 本番

use NextPDF\Pro\Optimizer\PdfOptimizer;
use NextPDF\Pro\Optimizer\OptimizationLevel;

$optimizer = new PdfOptimizer(OptimizationLevel::Aggressive);
$result = $optimizer->analyze($pdfBytes);

$savings = $result->originalSize > 0
    ? (1 - $result->optimizedSize / $result->originalSize) * 100
    : 0.0;

エッジケースと落とし穴

analyze() は可能性を推定します。最適化されたドキュメントを生成するには、Writer モジュールと組み合わせてください。
lossless レベルは、品質を保ち重複排除をスキップするため、意図的にサイズ削減がわずかになります。
最適化後の画像数は、破棄された画像ではなく、重複排除によって除去された画像を反映します。

パフォーマンス

分析は、入力サイズに対して線形であり、これにオブジェクト構造と画像構造のスキャンコストが加わります。レベルが、重複排除と再圧縮の推定をどれほど積極的に行うかを制御します。公表された固定のサイズ削減値はありません。結果はドキュメントに完全に依存します。代表的なドキュメントで測定してください。

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

入力は信頼できないものとして扱ってください。分析は読み取り専用であり、埋め込みコンテンツを実行しません。このモジュールはドキュメントの内容をログに記録しません。

適合性

最適化は、ISO 32000-2 で定義された PDF のオブジェクトおよび画像モデルに対して動作します。ソースは関連する節に注釈を付けています。執筆時点で RAG コーパスが利用できなかったため、このページは外部の節識別子を一切主張せず、適合性に関する記述をモジュールのテストで検証された振る舞いに限定します。

Enterprise の境界に関する注記

Enterprise は Optimizer の振る舞いを変更しません。Enterprise は、別途文書化された上位層のコンプライアンスおよびアーカイブ機能を追加します。それらは最適化の可能性を分析するのには必要ありません。

Core のフォールバック/代替手段

Pro がない場合は、NextPDF Core の基本的な最適化を使用してください。オブジェクトの重複排除と調整可能な画像再圧縮の分析は Pro の追加機能です。を参照してください。

公開の境界

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