Démarrage rapide avec NextPDF Pro

En un coup d’œil

Tu disposes d’une enveloppe de licence NextPDF Pro. Ce tutoriel la transforme en un premier résultat vérifié en quatre étapes courtes. Tu installes nextpdf/pro depuis le dépôt privé, tu actives ta licence, tu confirmes le droit résolu par le runtime, puis tu effectues le rendu d’un PDF gabarité et tu le signes. Chaque étape montre la sortie que tu devrais voir.

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

Prérequis

• PHP 8.4 et Composer 2. Les paquets premium requièrent PHP >=8.4 <9.0.
• Les identifiants du dépôt privé. Ton portail délivre une URL de dépôt, un nom d’utilisateur et un jeton. La configuration est couverte dans Installer et authentifier.
• Ton enveloppe de licence. Connecte-toi à ton compte sur app.getnextpdf.com, signe le contrat de licence, et télécharge l’enveloppe signée pour ton déploiement. Traite-la comme une clé d’API.
• ionCube Loader (builds encodés uniquement). L’essai Pro et le build Pro payant encodé avec ionCube nécessitent le Loader pour PHP 8.4 — voir Configuration ionCube.

1. Installer et activer

Fais pointer Composer vers ton dépôt privé, authentifie-toi et requiers le paquet :

composer config repositories.nextpdf composer https://repo.example.com/nextpdf
composer config --auth http-basic.repo.example.com your-username your-token
composer require nextpdf/pro:^3

Substitue l’URL du dépôt et les identifiants de ton portail. Les trois méthodes d’authentification (fichier auth.json du projet, COMPOSER_AUTH, auth globale) sont décrites dans Installer et authentifier.

Ensuite, place l’enveloppe de licence signée là où ton déploiement la charge, en suivant ta convention de configuration, puis exécute l’étape d’activation de ton intégration — la plupart des frameworks l’exposent sous forme de commande console. En coulisses, l’activation en ligne est un unique appel sur la surface de licence :

public function activate(string $licenseJws, string $deploymentId, ?string $machineFingerprintHash = null, ?string $expectedLicenseId = null, ?string $clientNonce = null): StatusResponse

Lève ou échoue avec : NextPDF\Enterprise\Licensing\LicenseClientException en cas d’échec de transport, d’un statut différent de 200, ou d’un nonce fourni incorrect, et NextPDF\Accelerator\Exception\SpectrumAuthenticationException en cas de tout échec de vérification du statut signé. Sur le canal ionCube, la licence se vérifie aussi périodiquement en ligne ; le canal signed-source se vérifie localement — voir Deux canaux de distribution.

2. Vérifier ton droit

Demande à l’évaluateur de droits — l’unique autorité pour les décisions de licence — ce à quoi ton enveloppe a été résolue. $license est le NextPDF\Enterprise\Licensing\LicenseKey vérifié que le bootstrap de licence de ton intégration expose ; null affiche le résultat sans-licence à fermeture sûre.

use NextPDF\Enterprise\Licensing\EntitlementEvaluator;

$result = (new EntitlementEvaluator())->evaluate($license);

printf("status:   %s\n", $result->status->value);
printf("edition:  %s\n", $result->edition?->value ?? '(none)');
printf("channel:  %s\n", $result->channel->value);
printf("branding: %s\n", $result->brandingMode->value);
printf("runtime:  %s\n", $result->runtimeAllowed ? 'allowed' : 'disabled');

La méthode qui la sous-tend (elle ne lève pas) :

public function evaluate(?LicenseKey $license, ?DateTimeImmutable $now = null): EntitlementResult

Avec une licence Pro payante active, attends-toi à :

status:   active
edition:  pro
channel:  paid
branding: none
runtime:  allowed

Sur un octroi d’essai ou d’évaluation, attends-toi plutôt à channel: evaluation et branding: evaluation. Toutes les capacités Pro s’exécutent quand même, et la sortie rendue porte un filigrane d’évaluation visible, par conception. Une licence payante le retire sans changement de code — voir Marquage d’essai et d’évaluation.

3. Premier résultat

Maintenant la partie amusante : analyse un gabarit JSON, lie tes données avec un formatage sensible au type, effectue le rendu des valeurs liées, et signe le document. Enregistre ceci sous quickstart.php à côté de ton répertoire vendor/ et exécute php quickstart.php. Tu as besoin d’un certificat de signature sous forme de fichier PKCS#12 (signing-cert.p12) ; un certificat auto-signé convient pour ce tutoriel. La signature en production nécessite une clé privée correctement protégée, une véritable chaîne de certificats et une politique de confiance que tes destinataires acceptent — les signatures auto-signées ne conviennent pas aux flux de destinataires de confiance.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;
use NextPDF\Security\Signature\CertificateInfo;
use NextPDF\Security\Signature\SignatureLevel;

// Parse a JSON template: one A4 page, three positioned placeholders.
$template = (new TemplateParser())->parse(<<<'JSON'
{
    "name": "welcome-letter",
    "pageSize": "A4",
    "orientation": "P",
    "placeholders": [
        {"name": "customer", "type": "text",     "x": 25, "y": 60, "width": 160, "height": 10},
        {"name": "issued",   "type": "date",     "x": 25, "y": 72, "width": 80,  "height": 10},
        {"name": "total",    "type": "currency", "x": 25, "y": 84, "width": 80,  "height": 10, "format": "EUR "}
    ]
}
JSON);

// Bind data. Keys match placeholder names case-insensitively.
$binding = (new TemplateDataBinder())->bind($template, [
    'customer' => 'Aurora Paper Co.',
    'issued'   => '2026-07-03',
    'total'    => 1249.5,
]);

printf(
    "Bound %d of %d placeholders (%d missing, %d warnings)\n",
    $binding->count(),
    count($template->placeholders),
    count($binding->missingFields),
    count($binding->warnings),
);

// Render the bound values with the Core document API.
$doc = Document::createStandalone();
$doc->setTitle('Welcome letter');
$doc->addPage();
$doc->setFont('helvetica', '', 12);

foreach ($binding->bindings as $bound) {
    $doc->text($bound->placeholder->x, $bound->placeholder->y, $bound->formattedValue);
}

// Apply a PAdES B-B baseline signature, then save once.
$doc->setSignature(
    CertificateInfo::fromPkcs12(__DIR__ . '/signing-cert.p12', (string) getenv('NEXTPDF_P12_PASSWORD')),
    SignatureLevel::PAdES_B_B,
);

$doc->save(__DIR__ . '/welcome-letter-signed.pdf');

echo "Created: welcome-letter-signed.pdf\n";

Sortie attendue :

Bound 3 of 3 placeholders (0 missing, 0 warnings)
Created: welcome-letter-signed.pdf

Ouvre welcome-letter-signed.pdf dans un lecteur de PDF : les trois valeurs liées apparaissent à leurs positions de gabarit (issued formaté Y-m-d, total en EUR 1,249.50), et le panneau de signature du lecteur affiche une signature. La structure émise suit le profil de base PAdES B-B ; NextPDF documente ceci comme une capacité, non comme une certification — la portée et la posture de conformité figurent sur la page des niveaux PAdES. Si le JSON du gabarit est mal formé, TemplateParser::parse() lève InvalidArgumentException avec un message préfixé par Template validation failed:.

Les signatures clés que tu viens d’utiliser, mot pour mot :

public function parse(string $json): TemplateDefinition
public function bind(TemplateDefinition $template, array $data): BindingResult
public static function fromPkcs12(string $p12Path, #[SensitiveParameter] string $password = ''): self
public function setSignature(CertificateInfo $certInfo, SignatureLevel $level = SignatureLevel::PAdES_B_B, ?TsaClient $tsaClient = null, ?ClientInterface $httpClient = null): static
public function save(string $path): void

Lève ou échoue avec : parse() — InvalidArgumentException lorsque le JSON est invalide ou ne se conforme pas à la structure attendue ; fromPkcs12() — NextPDF\Exception\SignatureException lorsque le fichier ne peut être lu ou analysé ; setSignature() — NextPDF\Exception\InvalidConfigException lorsque la linéarisation est déjà activée (PAdES et Fast Web View sont mutuellement exclusifs) ; save() — NextPDF\Exception\InvalidConfigException, NextPDF\Exception\PageLayoutException, ou NextPDF\Exception\CompressionException lorsque le fichier ne peut être écrit. bind() ne lève pas ; il rapporte missingFields et warnings à la place.

4. Quand quelque chose échoue

Composer ne trouve pas ou ne récupère pas nextpdf/pro

Un 401/403 pendant composer require, ou « could not be found », signifie que le dépôt privé ou ses identifiants ne sont pas configurés pour ce projet. La clé d’hôte dans auth.json doit correspondre exactement à l’hôte de l’URL du dépôt. Parcours Installer et authentifier.

Le runtime rapporte l’absence de licence

L’étape 2 affiche status: no_license, runtime: disabled, et l’avertissement de l’évaluateur — le message brut du runtime premium (partagé par les deux éditions) est : No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Les fonctionnalités premium échouent en fermeture sûre sans enveloppe vérifiée. Un fichier d’enveloppe présent mais corrompu n’est jamais traité comme absent — il lève NextPDF\Enterprise\Licensing\Storage\LicenseStorageException avec des messages tels que License file is present but unreadable: ... ou License file is present but empty: .... Place l’enveloppe au chemin configuré et rends-la lisible par l’utilisateur du processus PHP.

Le certificat de signature ne se charge pas

CertificateInfo::fromPkcs12() lève NextPDF\Exception\SignatureException lorsque le fichier .p12 ne peut être lu ou analysé. Les causes habituelles sont un mauvais chemin, un mauvais mot de passe (vérifie NEXTPDF_P12_PASSWORD), ou un fichier qui n’est pas réellement au format PKCS#12. Vérifie avec openssl pkcs12 -info -in signing-cert.p12 -noout.

Où aller ensuite

• Gabarit — la référence complète de définition de gabarit et de liaison.
• Signer un PDF avec PAdES B-B, puis étendre à PAdES B-T — ajoute un horodatage RFC 3161 à ta signature.
• Capacités de NextPDF Pro — tout ce que ta licence Pro inclut.
• Deux canaux de distribution — bail en ligne ionCube versus source signée entièrement hors ligne.
• Marquage d’essai et d’évaluation — à quoi ressemble le filigrane d’évaluation et comment une licence payante le retire.