Filter — référence approfondie

En un coup d’œil

Cette page est la référence au niveau du contrat du module Filter de NextPDF Pro, espace de noms NextPDF\Pro\Filter. La surface se compose de deux classes. DecodeParms analyse un fragment de dictionnaire PDF /DecodeParms pour en faire un objet-valeur immuable et à bornes vérifiées. PngPredictor inverse la famille de prédicteurs PNG (balises 10-15) sur des octets de flux décompressés par FlateDecode. Le module dessert les extracteurs Pro Diff et Classifier. Ce n’est pas un cadre général de filtres de flux. Cette page énonce l’API publique, le contrat de comportement observable et les modes de défaillance typés. Les conseils d’utilisation et les exemples de code se trouvent sur la page de capacité Filter.

Disponibilité et licence

Cette capacité 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 capacité. Compare les éditions et obtiens une licence.

Aucun indicateur de capacité au runtime ne verrouille ce module. Les classes Filter sont disponibles dès que nextpdf/pro est installé.

Surface de l’API publique

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
DecodeParms	constructeur : int $predictor = 1, int $columns = 1, int $colors = 1, int $bitsPerComponent = 8	Les valeurs par défaut encodent « aucun prédicteur »	—	—	final readonly ; les quatre propriétés sont publiques et immuables
DecodeParms::fromDictionary()	string $raw — texte brut du dictionnaire, corps d’objet environnant toléré	Les clés absentes conservent leurs valeurs par défaut ; la correspondance tolère les espaces	self	InvalidArgumentException	Point de contrôle à l’analyse ; bornes listées dans le contrat de comportement
DecodeParms::isPngPredictor()	aucun	Prédicat pur ; aucune E/S	bool — true pour les prédicteurs 10-15	—	Teste-le avant d’appeler le filtre inverse
PngPredictor	—	Sans état	—	—	final ; le seul point d’entrée est la méthode statique inverse()
PngPredictor::inverse()	string $raw, int $columns, int $colors, int $bitsPerComponent, int $predictor	Applique le filtre inverse ligne par ligne selon la balise par ligne ; une entrée vide renvoie une chaîne vide	string — charge utile reconstruite, balises de filtre retirées	InvalidArgumentException	Accepte uniquement les prédicteurs 10-15 ; le prédicteur TIFF est hors périmètre

Signatures des points d’entrée

public function __construct(
    public int $predictor = 1,
    public int $columns = 1,
    public int $colors = 1,
    public int $bitsPerComponent = 8,
) {}

public static function fromDictionary(string $raw): self

public function isPngPredictor(): bool

public static function inverse(
    string $raw,
    int $columns,
    int $colors,
    int $bitsPerComponent,
    int $predictor,
): string

Contrat de comportement

Analyse de /DecodeParms

DecodeParms::fromDictionary() reconnaît quatre clés comme entiers dans le texte brut du dictionnaire : /Predictor, /Columns, /Colors et /BitsPerComponent. Ce sont les paramètres de prédicteur qu’ISO 32000-2:2020 §7.4.4.4 définit pour les filtres LZWDecode et FlateDecode. La correspondance tolère les espaces et survit aux jetons PDF environnants. Les clés absentes conservent leurs valeurs par défaut : prédicteur 1, columns 1, colors 1, bits-per-component 8. Les valeurs présentes sont validées en mode fail-closed à l’analyse, avant qu’une géométrie ne puisse atteindre l’allocation de ligne du filtre inverse :

• Une valeur négative présente pour toute clé reconnue est rejetée.
• /Columns au-dessus de 1,000,000 est rejeté.
• /Colors au-dessus de 32 est rejeté.
• /BitsPerComponent en dehors de {1, 2, 4, 8, 16} est rejeté.
• Un pas de ligne dérivé au-dessus de 64,000,000 octets est rejeté.

isPngPredictor() renvoie true lorsque le prédicteur analysé est compris entre 10 et 15. Le prédicteur 1 (aucune prédiction) et le prédicteur 2 (le groupe TIFF) renvoient false.

Géométrie de ligne

PngPredictor::inverse() consomme un flux d’octets décompressé par FlateDecode dans lequel chaque ligne est précédée d’une balise de filtre d’un octet. Il émet la charge utile reconstruite, balises retirées. La largeur de la charge utile d’une ligne est de ceil(columns * colors * bitsPerComponent / 8) octets ; le pas de ligne ajoute un octet de balise. Le décalage du voisin de gauche (octets par pixel) est max(1, floor(colors * bitsPerComponent / 8)), de sorte que les empaquetages inférieurs à l’octet sont ramenés à un octet. Le filtrage opère sur des octets entiers quelle que soit la profondeur de bits, conformément à la sémantique des filtres PNG.

Reconstruction par ligne

Balise	Filtre	Reconstruction
0	None	passthrough
1	Sub	recon[x] = filt[x] + recon[x-bpp]
2	Up	recon[x] = filt[x] + prior[x]
3	Average	recon[x] = filt[x] + floor((recon[x-bpp] + prior[x]) / 2)
4	Paeth	recon[x] = filt[x] + Paeth(left, up, up-left)

Toutes les sommes sont prises modulo 256. Pour la première ligne, et pour les octets situés à gauche du premier pixel, le voisin manquant est lu comme zéro, conformément à W3C PNG §9.2. L’opération inverse est pilotée entièrement par la balise par ligne. C’est le comportement conforme à la fois pour les prédicteurs fixes (10-14) et pour Optimum (15) selon ISO 32000-2:2020 §7.4.4.4, de sorte que la variance de balise selon le générateur est tolérée.

Superposition de la validation

La validation des paramètres s’effectue en deux couches, par conception. DecodeParms est le point de contrôle à l’analyse et rejette d’abord les magnitudes hostiles. PngPredictor::inverse() conserve ses propres contrôles comme deuxième couche : contrôles de plage sur les quatre paramètres, garde-fous de dépassement qui comparent chaque facteur à PHP_INT_MAX avant de former le produit du pas, le même plafond de 64,000,000 octets par ligne, et une borne proportionnelle à l’entrée qui rejette un pas déclaré plus grand que l’entrée entière avant qu’aucun tampon de ligne ne soit alloué.

Déterminisme

Les deux points d’entrée sont des fonctions statiques pures de leurs entrées. Il n’y a aucune E/S, aucune journalisation et aucun état global. Le temps d’exécution est linéaire par rapport à la longueur de l’entrée, avec une petite constante par octet. L’analyse de /DecodeParms se réduit à quelques correspondances d’expressions régulières bornées. Les budgets sont indiqués dans le performance_budget du frontmatter.

Cas limites et modes de défaillance

Toute défaillance dans ce module lève InvalidArgumentException en nommant la valeur fautive dans le message.

• fromDictionary() rejette une valeur négative présente pour toute clé reconnue.
• fromDictionary() rejette /Columns au-dessus de 1,000,000 et /Colors au-dessus de 32.
• fromDictionary() rejette /BitsPerComponent en dehors de {1, 2, 4, 8, 16} et un pas de ligne dérivé au-dessus de 64,000,000 octets.
• inverse() rejette un prédicteur en dehors de 10-15. Le prédicteur TIFF (2) n’est jamais filtré en inverse ici ; teste isPngPredictor() d’abord.
• inverse() rejette columns ou colors inférieur à 1 et bitsPerComponent en dehors de l’ensemble autorisé.
• inverse() rejette une géométrie dont le produit du pas dépasserait l’entier de la plateforme, avant toute allocation.
• inverse() rejette un pas de ligne au-dessus du plafond de 64,000,000 octets par ligne, indépendamment de la longueur réelle de l’entrée.
• inverse() renvoie une chaîne vide pour une entrée vide ; ce n’est pas une erreur.
• inverse() traite un pas de ligne déclaré plus grand que l’entrée entière comme une ligne tronquée au décalage 0.
• inverse() traite une ligne partielle finale comme une ligne tronquée, en nommant le décalage et les nombres d’octets.
• inverse() traite une balise de filtre par ligne inconnue (hors 0-4) en indiquant la valeur de la balise et le décalage de la ligne.
• Une incohérence entre la géométrie /DecodeParms déclarée et la disposition réelle du flux se manifeste comme une erreur de paramètre ou de troncature, jamais comme une sortie silencieusement corrompue.
• Le filtre Average utilise la division entière, conformément à la sémantique floor de la spécification PNG.
• Aucune opération cryptographique n’a lieu dans ce module. Le comportement est identique dans les déploiements sous contrainte FIPS.

Conformité

Affirmation	Norme	Clause
Le paramètre de filtre /Predictor sélectionne l’algorithme de prédicteur ; les valeurs autorisées proviennent de la table des valeurs de prédicteur.	ISO 32000-2:2020	§7.4.4.4
PDF définit deux groupes de prédicteurs : le groupe TIFF est l’unique fonction Predictor 2 ; le groupe PNG correspond aux balises 10-15.	ISO 32000-2:2020	§7.4.4.4
Les valeurs valides de /BitsPerComponent sont 1, 2, 4, 8 et 16 avec 8 par défaut ; /Colors vaut 1 ou plus avec 1 par défaut ; /Columns vaut 1 par défaut.	ISO 32000-2:2020	§7.4.4.4
Les fonctions de reconstruction des types de filtre 0-4 opèrent octet par octet modulo 256 ; les octets absents à gauche et de la ligne précédente sont lus comme zéro.	W3C PNG (Third Edition)	§9.2
Le type de filtre Paeth calcule le PaethPredictor des voisins de gauche, du dessus et du dessus-gauche et choisit le plus proche.	W3C PNG (Third Edition)	§9.4

Toutes les clauses sont paraphrasées ; NextPDF ne reproduit aucun texte normatif. Ce sont des déclarations de capacité, non des certifications ; NextPDF ne détient aucune certification et n’en accorde aucune. La conformité du calcul de reconstruction et des valeurs par défaut des paramètres est vérifiée par la suite de tests unitaires. Un cadre complet de filtres de flux PDF, ainsi que l’inversion du prédicteur TIFF, sont hors périmètre pour ce module.

Notes de développement

• Les deux classes sont fournies depuis nextpdf/pro 3.0.0 et sont à jour en 3.1.0.
• Le module est consommé par les extracteurs Pro Diff et Classifier lorsque leurs entrées portent un prédicteur.
• Teste isPngPredictor() avant d’appeler inverse() ; le prédicteur 1 et le prédicteur TIFF ne nécessitent aucune inversion PNG.
• Le module borne sa propre allocation par ligne. Les appelants qui inversent des prédicteurs sur des flux non fiables devraient tout de même borner en amont la taille de l’entrée décompressée, comme le font les extracteurs Pro.
• Les prédicteurs fixes (10-14) et Optimum (15) partagent un même chemin de code ; la balise par ligne pilote la reconstruction dans les deux cas.
• Le détail des mécanismes internes reste dans la documentation interne du dépôt source et est hors périmètre pour ce manuel.

Limite de publication

Cette page documente uniquement 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 utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.

Voir aussi

• Filter (capacité) — installation, prise en main et exemples d’utilisation en production.
• Diff — référence approfondie — un consommateur du filtre inverse.
• Classifier — référence approfondie — un consommateur du filtre inverse.