Inicio rápido de NextPDF Pro

De un vistazo

Tienes un sobre de licencia de NextPDF Pro. Este tutorial lo convierte en un primer resultado verificado en cuatro pasos breves. Instalas nextpdf/pro desde el repositorio privado, activas tu licencia, confirmas el derecho que el runtime resolvió y, a continuación, renderizas un PDF con plantilla y lo firmas. Cada paso muestra el resultado que deberías ver.

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Compara ediciones y obtén una licencia.

Requisitos previos

• PHP 8.4 y Composer 2. Los paquetes premium requieren PHP >=8.4 <9.0.
• Credenciales del repositorio privado. Tu portal emite una URL de repositorio, un nombre de usuario y un token. La configuración se explica en Instalar y autenticar.
• Tu sobre de licencia. Inicia sesión en tu cuenta en app.getnextpdf.com, firma el acuerdo de licencia y descarga el sobre firmado para tu despliegue. Trátalo como una clave de API.
• ionCube Loader (solo compilaciones codificadas). La prueba de Pro y la compilación de pago de Pro codificada con ionCube necesitan el Loader para PHP 8.4 — consulta Configuración de ionCube.

1. Instalar y activar

Apunta Composer a tu repositorio privado, autentícate y requiere el paquete:

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

Sustituye la URL del repositorio y las credenciales por las de tu portal. Los tres métodos de autenticación (auth.json del proyecto, COMPOSER_AUTH, autenticación global) se describen en Instalar y autenticar.

A continuación, coloca el sobre de licencia firmado donde tu despliegue lo carga, siguiendo tu convención de configuración, y ejecuta el paso de activación de tu integración — la mayoría de los frameworks lo exponen como un comando de consola. En segundo plano, la activación en línea es una sola llamada sobre la superficie de licencias:

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

Lanza o falla con: NextPDF\Enterprise\Licensing\LicenseClientException ante un fallo de transporte, un estado distinto de 200 o un nonce suministrado incorrecto, y NextPDF\Accelerator\Exception\SpectrumAuthenticationException ante cualquier fallo de verificación de estado firmado. En el canal de ionCube la licencia también se verifica periódicamente en línea; el canal de código fuente firmado verifica localmente — consulta Dos canales de entrega.

2. Verificar tu derecho

Pregunta al evaluador de derechos —la única autoridad para las decisiones de licencia— a qué resolvió tu sobre. $license es el NextPDF\Enterprise\Licensing\LicenseKey verificado que expone el bootstrap de licencias de tu integración; null muestra el resultado de cierre seguro sin licencia.

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');

El método que hay detrás (no lanza excepciones):

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

Con una licencia de pago de Pro activa, espera:

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

Con una concesión de prueba o evaluación, espera en su lugar channel: evaluation y branding: evaluation. Todas las capacidades de Pro siguen ejecutándose, y la salida renderizada lleva una marca de agua de evaluación visible por diseño. Una licencia de pago la elimina sin ningún cambio de código — consulta Marca de prueba y evaluación.

3. Primer resultado

Ahora la parte divertida: analizar una plantilla JSON, vincular tus datos con formato según el tipo, renderizar los valores vinculados y firmar el documento. Guarda esto como quickstart.php junto a tu directorio vendor/ y ejecuta php quickstart.php. Necesitas un certificado de firma como archivo PKCS#12 (signing-cert.p12); uno autofirmado sirve para este tutorial. La firma en producción necesita una clave privada debidamente protegida, una cadena de certificados real y una política de confianza que tus destinatarios acepten — las firmas autofirmadas no son adecuadas para flujos de trabajo con destinatarios de confianza.

<?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";

Salida esperada:

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

Abre welcome-letter-signed.pdf en un lector de PDF: los tres valores vinculados aparecen en las posiciones de su plantilla (issued formateado como Y-m-d, total como EUR 1,249.50), y el panel de firma del lector muestra una firma. La estructura emitida sigue el perfil de línea base PAdES B-B; NextPDF documenta esto como una capacidad, no como una certificación — el alcance y la postura de conformidad están en la página de niveles PAdES. Si la plantilla JSON está mal formada, TemplateParser::parse() lanza InvalidArgumentException con un mensaje con el prefijo Template validation failed:.

Las firmas clave que acabas de usar, textualmente:

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

Lanza o falla con: parse() — InvalidArgumentException cuando el JSON es inválido o no se ajusta a la estructura esperada; fromPkcs12() — NextPDF\Exception\SignatureException cuando el archivo no puede leerse o analizarse; setSignature() — NextPDF\Exception\InvalidConfigException cuando la linealización ya está habilitada (PAdES y Fast Web View son mutuamente excluyentes); save() — NextPDF\Exception\InvalidConfigException, NextPDF\Exception\PageLayoutException o NextPDF\Exception\CompressionException cuando el archivo no puede escribirse. bind() no lanza excepciones; en su lugar informa de missingFields y warnings.

4. Cuando algo falla

Composer no puede encontrar ni obtener nextpdf/pro

Un 401/403 durante composer require, o “could not be found”, significa que el repositorio privado o sus credenciales no están configurados para este proyecto. La clave del host en auth.json debe coincidir exactamente con el host de la URL del repositorio. Repasa Instalar y autenticar.

El runtime informa de que no hay licencia

El paso 2 imprime status: no_license, runtime: disabled y la advertencia del evaluador — el mensaje sin procesar del runtime premium (compartido por ambas ediciones) es: No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Las funciones premium fallan de forma segura sin un sobre verificado. Un archivo de sobre presente pero dañado nunca se trata como ausente — genera NextPDF\Enterprise\Licensing\Storage\LicenseStorageException con mensajes como License file is present but unreadable: ... o License file is present but empty: .... Coloca el sobre en la ruta configurada y hazlo legible para el usuario del proceso de PHP.

El certificado de firma no se carga

CertificateInfo::fromPkcs12() lanza NextPDF\Exception\SignatureException cuando el archivo .p12 no puede leerse o analizarse. Las causas habituales son una ruta incorrecta, una contraseña incorrecta (comprueba NEXTPDF_P12_PASSWORD) o un archivo que no es realmente PKCS#12. Verifica con openssl pkcs12 -info -in signing-cert.p12 -noout.

Adónde ir a continuación

• Plantilla — la referencia completa de definición y vinculación de plantillas.
• Firma un PDF con PAdES B-B y luego amplía a PAdES B-T — añade una marca de tiempo RFC 3161 a tu firma.
• Capacidades de NextPDF Pro — todo lo que incluye tu licencia de Pro.
• Dos canales de entrega — arrendamiento en línea de ionCube frente a código fuente firmado totalmente sin conexión.
• Marca de prueba y evaluación — cómo se ve la marca de agua de evaluación y cómo la elimina una licencia de pago.