Module optionnel · pdftoolkit/pdf-codecs 0.1.0
English | Français
Le point d’entrée public est Decoder::decode(DecodeRequest): DecodedImage.
PhpDecoder l’implémente en créant le codec demandé avec une politique immuable
DecodeLimits. Analyseurs, contextes entropiques, tampons intermédiaires et
compteurs de travail appartiennent à cet appel. Réutiliser un décodeur après un
échec ne réutilise ni les tables, ni les données globales, ni le budget de
l’image qui a échoué.
Entrée encodée
DecodeRequest porte le codec et les octets encodés. colorTransform ne
s’applique qu’au JPEG et accepte 0, 1 ou l’absence. globals ne s’applique qu’au
JBIG2 et contient les octets du flux global déjà résolu. Résolution des
références PDF, déchiffrement, filtres précédents et dictionnaire d’image PDF
relèvent de Reader. La bibliothèque ne déduit pas le format d’un nom de fichier
et n’exécute pas le contenu fourni par une image.
use PDFToolkit\Codecs\Codec;
use PDFToolkit\Codecs\DecodeLimits;
use PDFToolkit\Codecs\DecodeRequest;
use PDFToolkit\Codecs\PhpDecoder;
$decoder = new PhpDecoder(new DecodeLimits(
maxInputBytes: 8 * 1024 * 1024,
maxOutputBytes: 32 * 1024 * 1024,
maxPixels: 4_000_000,
));
$image = $decoder->decode(new DecodeRequest(Codec::Jpeg, $encodedBytes));
$firstSample = $image->components[0]->sample(0, 0);
L’appelant fournit $encodedBytes. Cet exemple n’ouvre aucun fichier et ne
télécharge rien. L’exemple exécutable examples/decode.php gère explicitement
des fichiers locaux en tant qu’application extérieure à la bibliothèque.
Résultats décodés
DecodedImage contient les dimensions et l’origine de la grille de référence,
des objets ComponentPlane ordonnés, ColorInformation et les définitions de
canaux. Chaque composante précise ses dimensions, son espacement, son origine,
sa précision, son signe et son association alpha. Ses dimensions peuvent
différer de celles d’une autre composante. Le consommateur doit examiner ces
champs avant d’entrelacer ou d’afficher les échantillons.
Les octets des plans contiennent les échantillons bit de poids fort en premier,
avec bourrage en fin de ligne. Les valeurs signées utilisent le complément à
deux à la précision déclarée. ComponentPlane::sample(x, y) expose cette valeur
sans la réduire à un octet. Par exemple, la valeur signée -1 sur douze bits
est représentée par douze bits à un, et non par un entier sérialisé propre à PHP.
Les bits inutilisés en fin de ligne ne sont pas des pixels supplémentaires.
Métadonnées de couleur et valeurs des échantillons sont séparées. Les profils
ICC intégrés restent des octets, sans instruction d’accès au système de
fichiers. Les transformations de couleur définies pour JPEG et les
transformations de codestream JPEG 2000 sont des opérations de décodage ; la
conversion ICC, le rendu, les tableaux PDF Decode et la composition de la
transparence restent à la charge du consommateur. Les guides des codecs
précisent l’interprétation exacte de leurs sorties.
Budgets et échecs
DecodeBudget vérifie l’entrée, la sortie, les dimensions, le travail et les
allocations comptabilisées avant l’opération correspondante. DecodeLimits,
immuable, définit aussi les limites de composantes, métadonnées, segments,
tuiles et profondeur. Les limites applicables dépendent des structures du
codec. La limite d’entrée comprend les données globales JBIG2. Les allocations
sont comptabilisées cumulativement pendant un appel ; ce décompte est distinct
de la mémoire courante du processus PHP et ne remplace pas sa limite mémoire.
L’appelant distingue trois situations :
| Exception | Sens | Réponse appropriée |
|---|---|---|
MalformedImage |
Structure ou données encodées invalides. | Rejeter ou signaler l’entrée fournie. |
UnsupportedFeature |
Le décodeur ne traite pas un mécanisme déclaré. | Choisir une autre implémentation explicitement capable, ou signaler la limite. |
ResourceLimit |
Le budget configuré pour cet appel est épuisé. | Signaler la limite ; modifier la politique seulement par une décision explicite de l’application. |
Aucune tentative automatique avec des limites relâchées ni troncature silencieuse n’a lieu. Métadonnées et fixtures documentent les profils implémentés. La réussite du corpus prouve ces cas, sans déclarer que chaque flux possible a été exercé.
Relation avec PDFToolkit
Ce paquet ne dépend ni du cœur ni de Reader. Il ne découvre pas d’exécutables natifs, ne lance pas de processus et n’installe pas de paquets Composer. Reader porte l’adaptateur qui sélectionne d’abord un moteur natif disponible et compatible, puis ce décodeur PHP optionnel. La même bibliothèque peut être utilisée directement par une application qui ne lit pas de documents PDF.