Pro edition

Accelerator

At a glance

Accelerator offloads batch image re-compression, PDF parsing, and text embedding to a co-located CPU sidecar. When the sidecar is unreachable, every operation falls back to the in-process PHP path, so callers observe the same results either way.

Availability & licensing

This capability ships in NextPDF Pro (nextpdf/pro) and activates with a Pro-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

Accelerator has no separate per-feature flag. The accelerated path is selected at runtime by a sidecar reachability check (ProAcceleratorProvider::isAvailable()); when the sidecar is unreachable, the in-process PHP path runs instead.

Install

composer require nextpdf/pro:^3

The Premium package installs the nextpdf/pro code under the NextPDF\Pro\Accelerator namespace. The nextpdf/premium metapackage also installs Enterprise capabilities; Accelerator itself is a Pro-tier feature.

Conceptual overview

ProAcceleratorProvider is the entry point. It lazily constructs four services:

An accelerated optimizer that wraps the Pro PdfOptimizer and offloads batch image work to the sidecar.
An accelerated differ that wraps the Pro PdfDiffer; the sidecar parallelizes structure parsing while the diff algorithm itself runs in PHP.
A CPU embedding service that returns 384-dimension vectors using an all-MiniLM-L6-v2 ONNX model hosted by the sidecar.
A CPU vector index that builds and searches an in-memory HNSW index keyed by a collection identifier.

The design keeps domain logic in PHP. The sidecar performs parallelizable, CPU-bound work (image transcoding, multi-document parsing, ONNX inference, vector search). Each accelerated path has a deterministic PHP fallback that produces equivalent results.

Why it works this way

The load-bearing decision is that correctness never depends on the sidecar. Domain logic stays in PHP; the sidecar only performs parallelizable, CPU-bound work. The optimizer and differ (AcceleratedOptimizer, AcceleratedDiffer) keep a deterministic PHP fallback, so a missing sidecar changes timing, not results. Only the two operations with no PHP equivalent — CpuEmbeddingService and CpuVectorIndex — fail closed instead of degrading. A silent wrong answer there would be worse than an explicit error. That split lets throughput scale with sidecar cores while callers keep one code path and one trust boundary.

Design background: High-volume document generation.

Behavior contract

ProAcceleratorProvider::isAvailable() returns whether the sidecar responds. Callers can branch on this, but do not have to: the optimizer and differ fall back automatically.
embedding()->embed() returns a single 384-element vector; batchEmbed() returns one vector per input and rejects an empty input list with InvalidArgumentException.
vectorIndex($collectionId)->build() requires vectors and ids to be the same length and treats an empty input as a no-op.
vectorIndex()->search($queryVector, $topK) returns ranked results; delete() is not supported for the HNSW index and rejects the call — callers rebuild the index instead.
The embedding service and vector index require the sidecar; they raise a “not available” error rather than silently degrading, because there is no PHP equivalent for ONNX inference or HNSW search.
The optimizer and differ never raise on sidecar failure; they degrade to the PHP path transparently.

Code sample — Quick start

The following reflects the documented public API (ProAcceleratorProvider). The repository does not ship a runnable example for this module.

use NextPDF\Pro\Accelerator\ProAcceleratorProvider;

$provider = new ProAcceleratorProvider($spectrumClient);

$result = $provider->optimizer()->optimizeBatch([
    'invoice-1' => $pdfBytesA,
    'invoice-2' => $pdfBytesB,
]);

foreach ($result->getItems() as $item) {
    // Per-document optimization outcome.
}

Code sample — Production

use NextPDF\Pro\Accelerator\ProAcceleratorProvider;

$provider = new ProAcceleratorProvider($spectrumClient);

if ($provider->isAvailable()) {
    $index = $provider->vectorIndex('contracts');
    $index->build($vectors, $ids);
    $hits = $index->search($queryVector, topK: 10);
} else {
    // No PHP equivalent for HNSW search: route to your own retrieval path
    // or surface a degraded-capability message.
}

Wire ProAcceleratorProvider through your container as a singleton so the optimizer and differ instances are reused. Treat the embedding and vector-index calls as requiring the sidecar.

Edge cases & gotchas

The vector index lives in the sidecar process memory and is keyed by collection identifier. A sidecar restart clears all indexes; rebuild after a restart.
count() on the vector index returns 0 when the sidecar is unreachable rather than raising.
Optimizer and differ acceleration are best-effort; a sidecar error mid-batch causes a silent fallback for that call, so timing — not correctness — varies.

Performance

Acceleration targets CPU-bound batch work: parallel image transcoding, multi-document parsing, and vector search. NextPDF does not publish a fixed throughput multiplier here; gains depend on document mix, image density, sidecar core count, and batch size. Measure in your environment before relying on a specific number. The PHP fallback is single-threaded by design.

Security notes

This module sends documents and vectors to the co-located sidecar over its configured transport. Treat the sidecar as part of your trust boundary and deploy it on the same host or a private network segment. The module validates input size and shape before dispatch. It logs no document content.

Conformance

This module performs no format conformance work itself; it delegates optimization and diffing to the Pro Optimizer and Diff modules. See those modules for ISO 32000-2 references.

Enterprise boundary note

Enterprise does not change Accelerator behavior. Enterprise adds higher-tier compliance, archival, and signature lifecycle features documented elsewhere; those are out of scope for this module and are not required to use Accelerator.

Core fallback / alternative

Without Pro, use NextPDF Core’s in-process optimization and diffing. The accelerated paths in this module reduce to that same PHP behavior when the sidecar is absent.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.