Filtre

En bref

NextPDF\Pro\Filter fournit deux assistants ciblés : un analyseur du dictionnaire PDF /DecodeParms et un filtre inverse pour le prédicteur PNG appliqué aux flux FlateDecodés. C’est la prise en charge du prédicteur utilisée par les extracteurs Diff et Classifier de Pro ; ce n’est pas un cadriciel de filtres généraliste.

Disponibilité et licence

Cette fonctionnalité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement sans ce droit ne charge pas les classes de la fonctionnalité. Compare les éditions et obtiens une licence.

Les classes Filter sont disponibles dès que nextpdf/pro est installé ; aucun indicateur de capacité à l’exécution ne restreint ce module.

Installation

composer require nextpdf/pro:^3

Aperçu conceptuel

Les flux PDF peuvent être compressés par FlateDecode et, en plus, pré-traités avec un prédicteur pour améliorer la compression. ISO 32000-2:2020 §7.4.4.4 définit les paramètres du prédicteur (/Predictor, /Columns, /Colors, /BitsPerComponent) et la famille de prédicteurs PNG (tags 10–15).

• DecodeParms analyse un fragment de dictionnaire /DecodeParms en un objet-valeur immuable avec des valeurs par défaut raisonnables (predictor 1, columns 1, colors 1, bits-per-component 8). isPngPredictor() est vrai pour les tags 10–15.
• PngPredictor applique l’inverse des cinq types de filtre PNG — None, Sub, Up, Average, Paeth — plus Optimum (predictor 15, tag par ligne). Il valide les paramètres et lève une InvalidArgumentException sur des valeurs hors plage ou une ligne tronquée.

Ce module inverse un prédicteur existant lors de la lecture d’un flux. Il n’implémente pas l’ensemble complet des filtres de flux PDF et ne fournit aucun point d’ancrage de réglage de filtre.

Pourquoi ça fonctionne ainsi

Le module inverse un prédicteur existant plutôt que d’offrir un cadriciel de filtres généraliste. Les extracteurs Diff et Classifier de Pro ne lisent que ce qu’un producteur a déjà écrit, donc un périmètre étroit suffit. Ce périmètre permet de borner chaque entrée avant qu’un seul octet ne soit traité. DecodeParms::fromDictionary() est le point d’étranglement au moment de l’analyse : il rejette une géométrie négative ou surdimensionnée et applique les valeurs par défaut de DecodeParms::__construct() lorsqu’une clé est absente. PngPredictor revérifie ces bornes au moment de l’application, de sorte qu’un /DecodeParms hostile lève une erreur typée plutôt qu’une allocation volumineuse. Les appelants branchent sur DecodeParms::isPngPredictor(), gardant le prédicteur TIFF hors d’un filtre inverse qui ne gère que les tags 10–15.

Contexte de conception : Flux et filtres.

Contrat de comportement

• DecodeParms::fromDictionary(string $raw): self — appariement d’entiers tolérant aux espaces ; les clés absentes conservent leurs valeurs par défaut.
• PngPredictor::inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string — le predictor doit être entre 10 et 15 ; columns et colors doivent être ≥ 1 ; bits-per-component doit valoir 1, 2, 4, 8 ou 16 ; une ligne plus courte que la foulée (stride) calculée lève une InvalidArgumentException.
• Déterminisme. La sortie est une fonction pure des entrées.

Surface d’API publique

Type	Genre	Membres clés
NextPDF\Pro\Filter\DecodeParms	final readonly class	__construct(int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8), static fromDictionary(string $raw): self, isPngPredictor(): bool
NextPDF\Pro\Filter\PngPredictor	final class	static inverse(string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor): string

Exemple de code — Démarrage rapide

<?php

declare(strict_types=1);

use NextPDF\Pro\Filter\DecodeParms;
use NextPDF\Pro\Filter\PngPredictor;

$parms = DecodeParms::fromDictionary('<< /Predictor 15 /Columns 640 /Colors 3 >>');

if ($parms->isPngPredictor()) {
    $raw = PngPredictor::inverse(
        $flateDecodedBytes,
        $parms->columns,
        $parms->colors,
        $parms->bitsPerComponent,
        $parms->predictor,
    );
}

Exemple de code — Production

<?php

declare(strict_types=1);

use InvalidArgumentException;
use NextPDF\Pro\Filter\DecodeParms;
use NextPDF\Pro\Filter\PngPredictor;

function undoPredictor(string $decoded, string $dictFragment): string
{
    $parms = DecodeParms::fromDictionary($dictFragment);

    if (! $parms->isPngPredictor()) {
        return $decoded; // no predictor, or TIFF predictor — return as-is
    }

    try {
        return PngPredictor::inverse(
            $decoded,
            $parms->columns,
            $parms->colors,
            $parms->bitsPerComponent,
            $parms->predictor,
        );
    } catch (InvalidArgumentException) {
        return $decoded; // malformed predictor metadata — fail safe
    }
}

Cas limites et pièges

• Le prédicteur TIFF (tag 2) est reconnu par DecodeParms mais n’est pas filtré en inverse par PngPredictor (qui n’accepte que 10–15). Les appelants devraient brancher sur isPngPredictor().
• Une ligne de prédicteur plus courte que la foulée calculée est rejetée ; elle n’est pas tronquée silencieusement.
• La foulée de ligne est calculée à partir de columns * colors * bitsPerComponent ; une incohérence entre /DecodeParms et la disposition réelle du flux produit une erreur de paramètre ou de troncature plutôt qu’une sortie corrompue.

Performance

PngPredictor::inverse() est linéaire par rapport à la longueur du flux, avec une petite constante par octet. L’analyse de DecodeParms consiste en quelques appariements bornés par expression régulière. Voir performance_budget.

Notes de sécurité

Les plages de paramètres sont validées avant tout traitement d’octets, et une ligne tronquée lève une exception plutôt que de lire hors des bornes. Les appelants qui inversent des prédicteurs sur des flux non fiables devraient aussi borner la taille décompressée en amont, comme le font les extracteurs Diff et Classifier de Pro.

Conformité

Affirmation	Clause de spécification	Statut
Paramètres et valeurs par défaut de /DecodeParms	ISO 32000-2:2020 §7.4.4.4	Vérifié (suite unitaire)
Filtre inverse du prédicteur PNG, tags 10–15	ISO 32000-2:2020 §7.4.4.4	Vérifié (suite unitaire)
Cadriciel complet de filtres de flux PDF	—	Non pris en charge (hors périmètre)

Repli / alternative Core

Aucun équivalent Core n’est exposé pour l’inversion du prédicteur PNG. La gestion des flux propre à Core est interne au moteur et ne fait pas partie de cette surface publique.

Note de frontière Enterprise

C’est un assistant de prédicteur étroit. Ce n’est pas un filtre cryptographique, un assainisseur de contenu, ni un composant de reconstruction/désarmement de données ; ces préoccupations sont hors périmètre.

Frontière de publication

Cette page ne documente que le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes assistantes, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.

Voir aussi

• Référence Filter
• Diff
• Classifier
• Spécifications PDF 2.0