Contrats / Extraction

En bref

Le domaine de l’extraction regroupe les contrats qui lisent et valident les PDF et transforment leur contenu en données structurées. Il couvre l’inspecteur, les validateurs de conformité, le gestionnaire PDF/A, les contrats d’objets importés, les contrats d’embedding et d’index vectoriel, ainsi que le sous-espace de noms dédié au validateur de facture électronique.

Installation

composer require nextpdf/core:^3

Vue d’ensemble conceptuelle

InspectorInterface lit un PDF brut. Il renvoie un InspectResult structuré. Le résultat liste les objets présents dans le fichier. Utilise-le pour tout outil amené à lire un PDF que le moteur n’a pas écrit.

ExternalComplianceValidatorInterface sert de pont vers un outil de vérification externe, comme veraPDF. Cet outil contrôle PDF/A et PDF/UA. L’implémentation null renvoie un résultat « unavailable » quand aucun outil de vérification n’est configuré. Un site sans veraPDF continue donc de fonctionner. ProfileValidatorInterface vérifie l’environnement d’exécution par rapport à un profil de déploiement. Il examine les extensions requises et recommandées. Il renvoie un verdict typé.

PdfAManagerInterface maintient un fichier PDF/A conforme à la spécification pendant son écriture. Il bloque le JavaScript, les actions de formulaire JavaScript et le chiffrement intégré. PDF/A interdit les trois. Il vérifie aussi que chaque police est intégrée. Il définit des métadonnées conformes à la spécification. Il écrit les objets nécessaires avant le catalogue. L’implémentation concrète est livrée dans l’édition Pro. Le core la trouve avec class_exists() et l’adapte au contrat. Le moteur open-source n’a donc aucune dépendance payante.

Deux contrats couvrent les objets importés : ImportedFormObjectInterface et EmbeddedPdfObjectInterface. Ils donnent un accès typé aux objets lus depuis un PDF existant. Le moteur peut ensuite les réintégrer. Le chemin sans perte conserve les octets bruts du dictionnaire. Un chemin de repli fournit un tableau de dictionnaire analysé pour les objets issus de flux d’objets. Chaque objet réintégré est un objet indirect PDF. Un numéro d’objet et un numéro de génération l’identifient — ISO 32000-2 §7.3.10.

Les contrats d’embedding prennent en charge le travail de recherche. EmbeddingServiceInterface transforme du texte en vecteur dense. Il indique la dimension et le nom du modèle. L’appelant peut ainsi s’adapter à l’exécution. L’édition Pro exécute un modèle CPU. L’édition Enterprise exécute un modèle GPU. VectorIndexInterface construit un index des plus proches voisins et l’interroge. Il s’agit du petit index in-process destiné à l’usage du core. La recherche à plus grande échelle relève d’un contrat réservé à Enterprise.

Le groupe EInvoice contient le vérificateur de facture électronique commun aux différents niveaux. ValidatorInterface exécute des contrôles préalables sur une charge utile CII ou UBL. SchematronRunnerInterface exécute la passe de règles métier. ValidationResult rassemble les constats et les violations de règles. Le vérificateur doit rejeter une entrée mal formée au moyen d’un résultat, et non d’une exception. Il doit aussi se prémunir contre les DOCTYPE et les charges utiles surdimensionnées.

Surface de l’API

Type	Nature	Membres clés	Stabilité	Depuis
InspectorInterface	interface	inspect(string, InspectConfig): InspectResult	expérimental	2.2.0
ExternalComplianceValidatorInterface	interface	validate(string, ComplianceFlavour), isAvailable()	expérimental	2.4.0
ProfileValidatorInterface	interface	validate(DeploymentProfile): DeploymentProfileResult	expérimental	2.4.0
PdfAManagerInterface	interface	validateNoJavaScript(), validateFont(), validateNoEncryption(), applyOutputProfile(), writeRequiredObjects()	stable	1.10.0
ImportedFormObjectInterface	interface	getWidth(), getHeight(), getEmbeddedObjects(), getResourcesDict(), getMediaBox(), getContentStream()	stable	1.8.0
EmbeddedPdfObjectInterface	interface	getRawDictionaryBytes(), getRawStreamData(), getDictionary()	stable	1.8.0
EmbeddingServiceInterface	interface	embed(), batchEmbed(), getDimension(), getModelName()	expérimental	2.1.0
VectorIndexInterface	interface	build(), search(), delete(), count()	expérimental	2.1.0
EInvoice\ValidatorInterface	interface	validate(string, ValidatorContext): ValidationResult	expérimental	5.1.0
EInvoice\ValidationResult	classe final readonly	$isValid, getErrors(), getWarnings(), fail()	expérimental	5.1.0

L’espace de noms EInvoice publie aussi SchematronRunnerInterface, ProfileInterface, ValidationFinding, RuleViolation, ainsi que les énumérations ProfileType, RuleSeverity et ValidationFindingLevel.

Exemple de code — Démarrage rapide

examples/contracts/extraction-quickstart.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\InspectorInterface;
use NextPDF\Inspect\InspectConfig;

/**
 * Inspect a PDF and report its object count.
 *
 * @param InspectorInterface $inspector A configured inspector.
 * @param string             $pdfData   Raw PDF bytes.
 */
function describe(InspectorInterface $inspector, string $pdfData): \NextPDF\Inspect\InspectResult
{
    return $inspector->inspect($pdfData, new InspectConfig());
}

La fonction dépend du contrat. Toute implémentation d’inspecteur peut donc le satisfaire.

Exemple de code — Production

examples/contracts/extraction-production.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\EInvoice\ValidatorInterface;
use NextPDF\Contracts\EInvoice\ValidatorContext;
use NextPDF\Contracts\ExternalComplianceValidatorInterface;
use NextPDF\ValueObjects\ComplianceFlavour;
use Psr\Log\LoggerInterface;

final readonly class InvoiceConformanceService
{
    public function __construct(
        private ValidatorInterface $invoiceValidator,
        private ExternalComplianceValidatorInterface $pdfaValidator,
        private LoggerInterface $logger,
    ) {}

    /**
     * Validate the invoice XML, then the PDF/A-3 carrier.
     *
     * @param string $xml     The CII or UBL invoice payload.
     * @param string $pdfPath Absolute path to the PDF/A-3 carrier.
     */
    public function validate(string $xml, string $pdfPath, ValidatorContext $ctx): bool
    {
        $result = $this->invoiceValidator->validate($xml, $ctx);

        if (!$result->isValid) {
            $this->logger->warning('Invoice XML invalid', [
                'errors' => \count($result->getErrors()),
            ]);

            return false;
        }

        if (!$this->pdfaValidator->isAvailable()) {
            $this->logger->info('PDF/A validator unavailable; skipping carrier check.');

            return true;
        }

        $carrier = $this->pdfaValidator->validate($pdfPath, ComplianceFlavour::PdfA3b);

        return $carrier->isConformant();
    }
}

Le service traite explicitement le cas où le validateur est indisponible, plutôt que de supposer qu’un validateur est présent.

Cas limites et pièges

• EInvoice\ValidatorInterface::validate() renvoie un ValidationResult en échec pour une entrée mal formée. Il ne lève pas d’exception pour les violations de bonne formation. Vérifie $isValid, n’enveloppe pas l’appel dans un try/catch pour ce cas.
• ExternalComplianceValidatorInterface::isAvailable() doit être vérifié avant de te fier à un verdict. L’implémentation null renvoie « unavailable ». Le traiter comme « non conforme » produit des faux négatifs.
• EmbeddedPdfObjectInterface::getRawDictionaryBytes() renvoie null pour les objets issus d’un flux d’objets. Replie-toi sur getDictionary(). Ne suppose pas que les octets bruts existent.
• EmbeddingServiceInterface::getDimension() diffère selon le niveau. Le code qui alloue un vecteur de largeur fixe doit lire la dimension à l’exécution, sans la coder en dur.
• VectorIndexInterface::build() exige que les listes de vecteurs et d’identifiants aient la même longueur et des dimensions cohérentes. Une discordance lève InvalidArgumentException. Valide avant de construire.

Performance

Le coût de l’inspection et de la validation augmente avec la taille du document et le nombre d’objets. Le performance_budget de 1500 ms en temps réel et de 64 Mo de pic couvre un seul document de taille modérée. Un appel veraPDF externe ajoute le temps de traitement propre au validateur. Ce temps de traitement est hors du budget du moteur et devrait s’exécuter en dehors du chemin de la requête. Le coût de l’embedding augmente avec la longueur du texte et devient nettement plus faible en lot qu’en boucle, surtout sur un modèle GPU. Privilégie batchEmbed(). La recherche vectorielle est sous-linéaire par rapport à la taille de l’index pour l’index in-process. Le profil de reproductibilité est structural. Un rapport de validation enregistre un horodatage et une empreinte de l’environnement. Deux exécutions diffèrent sur ces champs, tandis que le verdict de conformité reste identique.

Notes de sécurité

L’extraction lit des documents que le moteur n’a pas créés ; chaque entrée est donc non fiable. L’inspecteur et le validateur de facture électronique analysent tous deux des octets fournis de l’extérieur. Le validateur de facture électronique doit filtrer les charges utiles avec DOCTYPE, surdimensionnées et contenant des caractères de contrôle interdits avant l’analyse, afin d’empêcher les attaques par entité externe XML et par billion laughs. La réintégration d’objets importés copie des octets depuis un PDF étranger. Un objet source malveillant peut transporter un contenu hostile ; la réintégration conserve donc les octets sans les exécuter. L’application de PDF/A supprime le JavaScript et les actions. Le gestionnaire PDF/A rejette le JavaScript et le chiffrement parce que tous deux sont interdits dans le profil et constituent tous deux des vecteurs d’abus dans un document d’archivage à longue durée de vie. Traite le contenu inspecté, les objets importés et le XML de facture comme une entrée hostile de bout en bout.

Conformité

Affirmation	Norme	Article	Preuve
PDF/A-4 interdit le JavaScript et les actions de formulaire JavaScript ; le gestionnaire PDF/A rejette les deux.	ISO 19005-4	§6.7.1	cité par l’article (absent du corpus)
Chaque objet réintégré est un objet indirect PDF identifié par un numéro d’objet et une génération.	ISO 32000-2	§7.3.10

ISO 19005-4 est référencé par article. Il n’est pas dans le corpus de citations vérifiables, donc aucun reference_id n’est enregistré. L’affirmation d’objet indirect ISO 32000-2 est rattachée au glossaire. Les deux affirmations sont paraphrasées. Le moteur ne reproduit aucun texte normatif.

Contexte commercial

Le core définit et fige les contrats d’extraction. Le code de production associé à PdfAManagerInterface, EmbeddingServiceInterface et VectorIndexInterface est livré dans les éditions Pro et Enterprise, y compris les modèles d’embedding CPU et GPU et le chemin complet d’application de PDF/A. Le core les résout à l’exécution avec class_exists(). Le moteur open-source n’embarque donc aucune dépendance commerciale, et l’API ne change pas lors d’une mise à niveau.

Voir aussi

• Contrats : 41 interfaces publiques (SPI) — la vue d’ensemble du SPI et les niveaux de stabilité.
• Contrats / Document — les contrats de document qui produisent le porteur PDF/A.
• Contrats / Signature — l’archivage signé utilisé avec l’application de PDF/A.
• Inspect — l’implémentation de l’inspecteur derrière InspectorInterface.
• Text — l’extraction de texte qui consomme les objets inspectés.
• Metadata — les métadonnées PDF/A configurées par le gestionnaire.