Optimizer — Referencia detallada

De un vistazo

Esta página es la referencia detallada de la superficie pública de NextPDF\Pro\Optimizer. Cubre el orquestador de análisis, los niveles de optimización, los dos escáneres y los objetos de valor de resultado. Expone parámetros, valores predeterminados, la aritmética de estimación y los modos de fallo. El análisis es de solo lectura: estima el ahorro y no produce ningún documento de salida. Leer primero la página de capacidad de Optimizer para orientarse sobre el flujo de trabajo.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa habilitación no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Optimizer no tiene ningún indicador de licencia por función. Esta es una capacidad de la edición Pro. El nivel de optimización es un parámetro en tiempo de ejecución, no un conmutador de licencia.

Superficie de la API pública

composer require nextpdf/pro:^3

El metapaquete nextpdf/premium instala el código de nextpdf/pro; este módulo reside en el espacio de nombres NextPDF\Pro\Optimizer.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
PdfOptimizer::__construct	OptimizationLevel $level = OptimizationLevel::Balanced	Construye un optimizador en el nivel dado	PdfOptimizer	Nada declarado	Construye sus propias instancias de escáner
PdfOptimizer::analyze	string $pdfData	Análisis de solo lectura en el nivel configurado	OptimizationResult	OverflowException con entrada superior a 100,000,000 bytes; InvalidArgumentException de los escáneres con datos PDF no válidos	Solo estima; no produce ningún documento de salida
PdfOptimizer::withLevel	OptimizationLevel $level	Devuelve un nuevo optimizador en el nivel solicitado	self	Nada declarado	La instancia receptora no se modifica
OptimizationLevel	casos Lossless, Balanced, Aggressive	Enumeración respaldada por cadenas de niveles de agresividad	—	—	Valores de respaldo lossless, balanced, aggressive
OptimizationLevel::label	ninguno	Etiqueta de nivel legible para humanos	string	Nada declarado	Para uso en pantalla
OptimizationLevel::imageQuality	ninguno	Calidad de imagen objetivo para el nivel	int	Nada declarado	100, 75 o 50
OptimizationLevel::deduplicateStreams	ninguno	Si el nivel habilita la deduplicación	bool	Nada declarado	false solo para Lossless
OptimizationResult::__construct	int $originalSize, int $optimizedSize, int $objectsRemoved, int $imagesBefore, int $imagesAfter, float $processingTimeMs	Resultado de análisis inmutable	OptimizationResult	Nada declarado	Todas las propiedades son públicas y de solo lectura
OptimizationResult::savedBytes	ninguno	Tamaño original menos el tamaño optimizado estimado	int	Nada declarado	Bytes
OptimizationResult::savedPercent	ninguno	Porcentaje de reducción de tamaño	float	Nada declarado	0.0 cuando el tamaño original es cero
OptimizationResult::summary	ninguno	Informe multilínea legible para humanos	string	Nada declarado	Tamaños formateados como B, KB o MB
ObjectDeduplicator::findDuplicates	string $pdfData	Agrupa cuerpos de objeto idénticos por hash SHA-256	list<DuplicateGroup>	InvalidArgumentException cuando falta la cabecera %PDF, con entrada superior a 268,435,456 bytes, o con más de 500,000 marcadores de objeto	Devuelve solo grupos con dos o más miembros
ObjectDeduplicator::estimateSavings	list<DuplicateGroup> $groups	Suma el recuento de duplicados por el tamaño del objeto en cada grupo	int	Nada declarado	Bytes
ImageRecompressor::analyzeImages	string $pdfData	Extrae metadatos de cada XObject de imagen	list<ImageAnalysis>	InvalidArgumentException cuando falta la cabecera %PDF	Omite objetos sin ancho y alto explícitos
ImageRecompressor::suggestCompression	ImageAnalysis $image, OptimizationLevel $level	Recomienda un filtro y estima el ahorro	ImageCompressionSuggestion	Nada declarado	Heurísticas dependientes del nivel; véase el contrato de comportamiento
DuplicateGroup::__construct	string $contentHash, list<int> $objectNumbers, int $objectSize	Registro de grupo de duplicados inmutable	DuplicateGroup	Nada declarado	El primer número de objeto es el objeto canónico conservado
DuplicateGroup::duplicateCount	ninguno	Tamaño del grupo menos el objeto canónico	int	Nada declarado	Objetos eliminables al fusionar
ImageAnalysis::__construct	int $objectNumber, int $width, int $height, string $colorSpace, int $bitsPerComponent, string $filter, int $streamSize	Registro de metadatos por imagen inmutable	ImageAnalysis	Nada declarado	Los campos reflejan las entradas del diccionario de imagen
ImageAnalysis::estimatedDpi	float $displayWidthPt	DPI efectivo al ancho de visualización dado	float	Nada declarado	0.0 cuando el ancho de visualización es cero o negativo
ImageAnalysis::isOverResolution	float $displayWidthPt, int $targetDpi = 300	Marca candidatos a submuestreo por encima del DPI objetivo	bool	Nada declarado	Comparación estrictamente mayor que
ImageCompressionSuggestion::__construct	int $objectNumber, string $currentFilter, string $suggestedFilter, int $estimatedSavings, string $reason	Registro de recomendación inmutable	ImageCompressionSuggestion	Nada declarado	reason es texto explicativo legible para humanos

Firmas de los puntos de entrada

final class PdfOptimizer
{
    public function __construct(
        private OptimizationLevel $level = OptimizationLevel::Balanced,
    )

    public function analyze(string $pdfData): OptimizationResult

    public function withLevel(OptimizationLevel $level): self
}

enum OptimizationLevel: string
{
    case Lossless = 'lossless';
    case Balanced = 'balanced';
    case Aggressive = 'aggressive';

    public function label(): string

    public function imageQuality(): int

    public function deduplicateStreams(): bool
}

final readonly class OptimizationResult
{
    public function __construct(
        public int $originalSize,
        public int $optimizedSize,
        public int $objectsRemoved,
        public int $imagesBefore,
        public int $imagesAfter,
        public float $processingTimeMs,
    )

    public function savedBytes(): int

    public function savedPercent(): float

    public function summary(): string
}

final class ObjectDeduplicator
{
    public function findDuplicates(string $pdfData): array

    public function estimateSavings(array $groups): int
}

final class ImageRecompressor
{
    public function analyzeImages(string $pdfData): array

    public function suggestCompression(
        ImageAnalysis $image,
        OptimizationLevel $level,
    ): ImageCompressionSuggestion
}

Contrato de comportamiento

Orquestación

PdfOptimizer::analyze acepta bytes PDF sin procesar y es de solo lectura. Primero acota la entrada no confiable en 100,000,000 bytes; una entrada de tamaño excesivo lanza OverflowException antes de que se ejecute cualquier escaneo. Después ejecuta el análisis de deduplicación cuando el nivel lo permite, ejecuta siempre el análisis de imágenes y agrega ambos en un único OptimizationResult. withLevel devuelve un nuevo optimizador; las instancias nunca se modifican.

Semántica de niveles

Nivel	Calidad de imagen objetivo	Deduplicación	Intención
Lossless	100%	Desactivada	Sin pérdida de calidad; salida con intención de estabilidad de bytes
Balanced	75%	Activada	Compromiso de calidad moderado; el predeterminado
Aggressive	50%	Activada	Reducción máxima; submuestreo; pérdida de calidad visible

Lossless omite la deduplicación para que la salida pueda mantener la estabilidad de bytes. La calidad objetivo alimenta la aritmética de sugerencia de imágenes que se describe a continuación.

Análisis de deduplicación

El deduplicador escanea las definiciones de objeto indirecto de generación cero (N 0 obj hasta endobj). Cada cuerpo se recorta de los espacios en blanco circundantes, se calcula su hash con SHA-256 y se agrupa por hash. Las definiciones que difieren únicamente en el relleno, por lo tanto, siguen coincidiendo. Solo se devuelven los grupos con dos o más miembros. El ahorro estimado por grupo es igual al recuento de duplicados por el tamaño de un solo cuerpo, ya que todos los objetos salvo el canónico pueden eliminarse.

Análisis de imágenes

Un objeto se trata como imagen cuando su cuerpo contiene /Subtype /Image (con o sin un espacio interno). El ancho y el alto son obligatorios; un objeto al que le falte cualquiera de ellos se omite. El espacio de color toma como valor predeterminado DeviceRGB, los bits por componente 8 y el filtro una cadena vacía cuando está ausente. El tamaño del flujo se mide entre los marcadores stream y endstream; cuando no se encuentra ningún flujo en línea, se usa en su lugar el valor de /Length.

Heurísticas de sugerencia

• En el nivel Lossless, se conserva el filtro actual y el ahorro estimado es cero.
• Para fuentes DCTDecode, la sugerencia vuelve a codificar con la calidad del nivel. La estimación es el tamaño del flujo por (1 − calidad/100) por 0,5.
• Para fuentes FlateDecode, la sugerencia convierte a DCTDecode. La estimación es el 40% del tamaño del flujo en Balanced y el 60% en Aggressive.
• Para cualquier otro filtro, o sin filtro, la sugerencia convierte a FlateDecode. La estimación es el 20% del tamaño del flujo.

Aritmética de resultados

• Los objetos eliminados equivalen a la suma, sobre todos los grupos de duplicados, de los miembros más allá del primero canónico.
• El ahorro total equivale al ahorro por deduplicación más las estimaciones de sugerencia por imagen.
• El tamaño optimizado estimado es el tamaño original menos el ahorro total, con un mínimo de cero. El ahorro es no negativo, por lo que la estimación nunca supera el tamaño original.
• El recuento de imágenes posterior resta, por cada grupo de duplicados que contenga una imagen analizada, el recuento de miembros duplicados de ese grupo. El recuento tiene un mínimo de cero.
• El tiempo de procesamiento se mide con un reloj monótono y se informa en milisegundos.

El estimador de DPI divide el ancho en píxeles por el ancho de visualización en pulgadas (72 puntos por pulgada). Un ancho de visualización cero o negativo produce 0.0. El predicado de exceso de resolución compara la estimación con un objetivo, 300 DPI por defecto.

Casos límite y modos de fallo

• analyze solo informa del potencial. Producir la salida optimizada con el módulo Writer.
• Una entrada vacía, o una entrada que no comienza con la cabecera %PDF, falla con InvalidArgumentException.
• Una entrada superior a 100,000,000 bytes falla con OverflowException en la puerta de entrada del orquestador, antes de cualquier escaneo.
• El deduplicador rechaza de forma independiente las entradas superiores a 268,435,456 bytes y con más de 500,000 marcadores de objeto. Ambos rechazos son a prueba de fallos con InvalidArgumentException; nada se trunca ni se escanea parcialmente.
• Solo participan las definiciones de objeto de generación cero. Los objetos con números de generación distintos de cero no se escanean.
• Una definición sin un marcador endobj de cierre se omite.
• Los objetos de imagen sin un ancho y un alto explícitos se excluyen del informe de imágenes.
• Todas las cifras de ahorro son heurísticas derivadas de los metadatos del objeto, no resultados de recompresión medidos.
• El nivel sin pérdidas informa intencionadamente de reducciones pequeñas; preserva la calidad y omite la deduplicación.
• El análisis nunca decodifica, ejecuta ni renderiza contenido incrustado. Lee únicamente la estructura y los metadatos del objeto.
• La única primitiva criptográfica utilizada es SHA-256, para la agrupación de contenido duplicado. El módulo no define ningún comportamiento específico de FIPS.

Conformidad

Ambos escáneres operan sobre el modelo de objeto e imagen PDF de ISO 32000-2:2020. La deduplicación se dirige a las definiciones de objeto indirecto; la estructura de su identificador se define en ISO 32000-2:2020, 7.3.10, citada en el registro de citas de esta página. El análisis de imágenes lee los parámetros que un diccionario de imagen declara explícitamente —ancho, alto y bits por componente— conforme a ISO 32000-2:2020, 8.9.4, también citada.

Estas afirmaciones describen la capacidad frente a las cláusulas citadas. NextPDF no posee ninguna certificación de conformidad, y el soporte de una cláusula no es una afirmación de certificación.

Notas de desarrollo

• El código fuente del módulo lleva @since 1.9.0; esta referencia documenta la superficie tal como se distribuye en nextpdf/pro 3.1.0.
• Todas las clases son final; los registros de resultado y de análisis son objetos de valor de solo lectura. Construir nuevas instancias en lugar de modificarlas.
• El nivel predeterminado es Balanced. Seleccionar otro nivel mediante el constructor o el método de estilo with.
• El límite de entrada de la puerta de entrada lo impone una salvaguarda de tamaño de entrada de Core compartida entre las superficies de entrada de NextPDF.
• El análisis se basa en cadenas sobre bytes ya en memoria. El módulo no realiza ningún acceso al sistema de archivos ni a la red.
• El detalle del mecanismo interno permanece en la documentación interna del repositorio de código fuente y queda fuera del alcance de este manual.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de la API pública admitida. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de tickets quedan fuera del alcance.

Véase también

• Optimizer — la página de capacidad para orientación sobre el flujo de trabajo y ejemplos de código.
• Writer — Referencia detallada — produce el documento de salida optimizado.
• Accelerator — Referencia detallada — optimización por lotes con descarga sidecar en la semántica de este módulo.