Enterprise 版本

Document E-Filing — 深入參考

一覽

EFilingOptimizer 以一趟固定順序的處理準備供電子法院申報的 PDF：淨化、線性化、依大小分割。
EFilingProfile 將司法管轄區限制編碼。內建工廠涵蓋 US PACER、EU e-Justice 與 Taiwan Judicial Yuan。
SizeAwareSplitter 以「先驗證再修正」的重新分割強制執行每個區段的位元組上限。
輸出是一個交付成品。它絕不可重新進入簽署或封存管線。
本模組不執行任何密碼學運算，也不進行任何對外網路呼叫。

供應與授權

此功能隨 NextPDF Enterprise（nextpdf/enterprise）出貨，並以 Enterprise 層級的授權信封啟用。未具備該授權的部署不會載入此功能的類別。比較版本並取得授權。

nextpdf/enterprise 套件邊界閘控此介面；沒有獨立的逐功能能力碼。沒有任何 Core 或 Pro 版本提供電子申報最佳化器。

公開 API 介面

composer require nextpdf/enterprise:^3

符號	參數	預設行為	回傳	拋出或失敗於	備註
`EFilingOptimizer::optimize()`	`string $pdfData`、`?EFilingProfile $profile = null`	設定檔預設為 `EFilingProfile::pacer()`；以固定順序執行淨化、線性化、依大小分割	`EFilingResult`	當超出上限的輸入不是有效的 PDF 時，分割步驟會拋出 `InvalidArgumentException`；淨化與線性化失敗會降級為警告	輸出是一個交付成品
`EFilingProfile::__construct()`	`$name`、`$maxFileSizeBytes = 26_214_400`、`$flattenForms = true`、`$removeJavaScript = true`、`$imageQuality = 75`、`$linearize = true`、`$compressObjectStreams = true`	不可變的司法管轄區設定檔	`EFilingProfile`	不會拋出	為沒有內建工廠的入口提供自訂上限
`EFilingProfile::pacer()`	無	25 MiB 上限，影像品質 75	`EFilingProfile`	不會拋出	US PACER
`EFilingProfile::euJustice()`	無	10 MiB 上限，影像品質 70	`EFilingProfile`	不會拋出	EU e-Justice Portal
`EFilingProfile::taiwan()`	無	10 MiB 上限，影像品質 70	`EFilingProfile`	不會拋出	Taiwan Judicial Yuan
`SizeAwareSplitter::splitByMaxSize()`	`string $pdfData`、`int $maxBytes`	輸入符合時為單一區段；否則進行估算、驗證、重新分割	`list<EFilingSegment>`	當超出上限的輸入缺少 `%PDF` 標頭時拋出 `InvalidArgumentException`	低於上限的輸入不經驗證即以單一區段回傳
`EFilingResult::isSplit()`	無	存在多於一個區段時為 `true`	`bool`	不會拋出	—
`EFilingResult::segmentCount()`	無	區段總數	`int`	不會拋出	—
`EFilingResult::compressionRatio()`	無	`optimizedTotalSize / originalSize`	`float`	不會拋出；原始輸入為空時為 `0.0`	越低越好
`EFilingSegment`	`$pdfData`、`$pageRange`、`$sizeBytes`、`$segmentIndex`	不可變的輸出區段	值物件	不會拋出	頁面範圍字串，例如 `1-25` 或 `all`

public function optimize(string $pdfData, ?EFilingProfile $profile = null): EFilingResult

public function __construct(
    public string $name,
    public int $maxFileSizeBytes = 26_214_400,
    public bool $flattenForms = true,
    public bool $removeJavaScript = true,
    public int $imageQuality = 75,
    public bool $linearize = true,
    public bool $compressObjectStreams = true,
) {}

public static function pacer(): self
public static function euJustice(): self
public static function taiwan(): self

public function splitByMaxSize(string $pdfData, int $maxBytes): array

public function __construct(
    public array $segments,
    public int $originalSize,
    public int $optimizedTotalSize,
    public array $optimizations = [],
    public array $warnings = [],
) {}

public function isSplit(): bool
public function segmentCount(): int
public function compressionRatio(): float

行為合約

EFilingOptimizer::optimize() 會針對輸入位元組執行一條固定順序的管線。當設定 removeJavaScript 時，第一步會移除主動式內容。它以申報專屬的政策委派給內容淨化與重建（content-disarm-and-reconstruction）引擎：JavaScript、具名 JavaScript、啟動動作、表單提交與資料匯入動作會被移除；URI 動作會保留（allowUriActions），因為申報可能帶有正當連結；增量更新會被扁平化為單一修訂（flattenIncrementalUpdates）。當設定 linearize 時，第二步會透過 Core 的 NextPDF\Writer\Linearizer 將淨化後的位元組線性化。第三步會透過 SizeAwareSplitter 強制執行設定檔的 maxFileSizeBytes。

分割器會依平均頁面大小估算每個區段的頁數，進行分割，然後對照上限驗證每個產生的區段。任何仍跨越多於一頁的超出上限區段，都會被遞迴地重新分割，每一趟將自身的頁面跨距減半，直到每個子區段都符合或成為單一頁面。有界的重新分割深度可防範病態的不收斂。輸出索引會被重新正規化，以維持連續且從零開始。

optimize() 會使用三個設定檔欄位：maxFileSizeBytes、removeJavaScript 與 linearize。flattenForms、imageQuality 與 compressObjectStreams 欄位是已宣告的設定檔限制，在 3.1.0 中 optimize() 不會據以動作。

電子申報輸出是一個交付成品，不是文件生命週期狀態。一份經最佳化或分割的 PDF 已是傳輸用的最終版本，絕不可重新進入簽署或封存管線；重新處理會破壞雜湊鏈與舉證完整性。

本模組會依設定準備供電子法院/政府申報的格式。它不保證任何法院、登記機構、法庭或申報入口會接受。內建設定檔上限將常見已發布的限制編碼進來作為便利機制，而非來自各入口的即時資料來源；入口規則因司法管轄區而異且會變動。對照目的地登記機構的現行規則加以查證，是申報者的責任。

處理在行程內於本機進行。傳輸到法院、登記機構或申報入口，屬於本模組之外。

邊界案例與失敗模式

輸入等於或低於上限：一個頁面範圍為 all 的區段；分割步驟不會變更位元組。
淨化遭拒（例如無法解析的輸入）：會記錄警告 CDR sanitization rejected: <reason>，管線並以原始位元組繼續。
淨化通過但未發現威脅：位元組仍會被重建後的 PDF 取代，並由一筆最佳化項目記錄此次乾淨通過。
線性化失敗：會記錄警告 Linearization skipped: <message>，管線並以未線性化的位元組繼續。
單一頁面超出上限：確實無法再分割，會以一個超出上限的區段原樣回傳。此情況不會記錄警告；請在申報前對照設定檔上限檢查每個區段的 sizeBytes。
達到重新分割深度上限：超出上限的區段會原樣通過，而非陷入迴圈。
當原始輸入為空時，compressionRatio() 回傳 0.0。
本模組不執行任何密碼學運算；FIPS 模式不適用。

一致性

行為	參考	狀態
線性化輸出組織（首頁資料位於檔案開頭）	ISO 32000-2:2020 Annex F / Annex G	依此建置
關聯檔案關係語意	ISO 19005-3:2012 §6.7.8	在載體適用之處遵循
嵌入檔案載體要求	ISO 19005-4:2020 Annex A	在載體適用之處遵循

線性化以 Linearized PDF 組織為目標，該組織將顯示首頁所需的所有資料放在檔案開頭，以達成有效率的增量存取。

這些列描述依所引條款建置的功能。支援不等於一致性，一致性也不等於認證；NextPDF 未持有任何認證。本頁的任何陳述都不保證任何申報入口會接受。

本頁帶有 export_control_class: legal-review-required。NextPDF 不提供法律建議。申報規則因司法管轄區而異且會變動；達成它們是申報者的責任。請諮詢法律顧問與目的地登記機構的現行指引。

開發備註

use NextPDF\Enterprise\Document\EFiling\EFilingOptimizer;
use NextPDF\Enterprise\Document\EFiling\EFilingProfile;

$optimizer = new EFilingOptimizer();
$result = $optimizer->optimize($pdfBytes, EFilingProfile::euJustice());

foreach ($result->segments as $segment) {
    // Persist $segment->pdfData; confirm $segment->sizeBytes fits the cap.
}

在申報前檢查 $result->warnings。遭拒的淨化或被略過的線性化會顯示於此，而非以例外呈現。
先簽署並封存原始文件；再為交付最佳化一份副本。絕不可重新簽署、重新蓋章或封存已最佳化的區段。
對照設定檔上限驗證每個區段的 sizeBytes。無法分割的超出上限頁面會無聲地抵達輸出。
對於沒有內建工廠的入口，請以該入口已發布的上限建構自訂的 EFilingProfile。

發布邊界

本頁僅記載外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名與工單前綴皆不在範圍內。