Pular para o conteúdo
NextPDF
getnextpdf.com

Pro edição

Início rápido do NextPDF Pro

Visão geral

Seção intitulada “Visão geral”

Você tem um envelope de licença do NextPDF Pro. Este tutorial o transforma em um primeiro resultado verificado em quatro passos curtos. Você instala nextpdf/pro do repositório privado, ativa sua licença, confirma o direito de uso que o runtime resolveu, depois renderiza um PDF baseado em template e o assina. Cada passo mostra a saída que você deve ver.

Este recurso é entregue no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem esse direito de uso não carrega as classes do recurso. Compare edições e obtenha uma licença.

Pré-requisitos

Seção intitulada “Pré-requisitos”
  • PHP 8.4 e Composer 2. Os pacotes premium exigem PHP >=8.4 <9.0.
  • Credenciais do repositório privado. Seu portal emite uma URL de repositório, um nome de usuário e um token. A configuração é abordada em Instalar e autenticar.
  • Seu envelope de licença. Entre na sua conta em app.getnextpdf.com, assine o contrato de licença e baixe o envelope assinado para sua implantação. Trate-o como uma chave de API.
  • ionCube Loader (apenas builds codificados). O trial Pro e o build Pro pago, codificado com ionCube, precisam do Loader para PHP 8.4 — consulte Configuração do ionCube.

1. Instalar e ativar

Seção intitulada “1. Instalar e ativar”

Aponte o Composer para seu repositório privado, autentique-se e exija o pacote:

Terminal window
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

Substitua a URL do repositório e as credenciais do seu portal. Todos os três métodos de autenticação (auth.json do projeto, COMPOSER_AUTH, auth global) são descritos em Instalar e autenticar.

Em seguida, coloque o envelope de licença assinado onde sua implantação o carrega, seguindo sua convenção de configuração, e execute o passo de ativação da sua integração — a maioria dos frameworks o expõe como um comando de console. Nos bastidores, a ativação online é uma única chamada na superfície de licenciamento:

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

Lança ou falha com: NextPDF\Enterprise\Licensing\LicenseClientException em uma falha de transporte, um status diferente de 200 ou um nonce fornecido inválido, e NextPDF\Accelerator\Exception\SpectrumAuthenticationException em qualquer falha de verificação de status assinado. No canal ionCube a licença também verifica periodicamente online; o canal de código-fonte assinado verifica localmente — consulte Dois canais de entrega.

2. Verifique seu direito de uso

Seção intitulada “2. Verifique seu direito de uso”

Pergunte ao avaliador de direito de uso — a única autoridade para decisões de licença — a que seu envelope foi resolvido. $license é a NextPDF\Enterprise\Licensing\LicenseKey verificada que o bootstrap de licenciamento da sua integração expõe; null mostra o resultado fail-closed de ausência de licença.

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

O método por trás disso (ele não lança exceção):

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

Com uma licença Pro paga e ativa, espere:

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

Em uma concessão de trial ou avaliação, espere channel: evaluation e branding: evaluation em vez disso. Todo recurso Pro ainda funciona, e a saída renderizada carrega uma marca-d’água de avaliação visível por design. Uma licença paga a remove sem nenhuma alteração de código — consulte Marca de trial e avaliação.

3. Primeiro resultado

Seção intitulada “3. Primeiro resultado”

Agora a parte divertida: fazer o parse de um template JSON, vincular seus dados com formatação sensível a tipo, renderizar os valores vinculados e assinar o documento. Salve isto como quickstart.php ao lado do seu diretório vendor/ e execute php quickstart.php. Você precisa de um certificado de assinatura como um arquivo PKCS#12 (signing-cert.p12); um autoassinado serve para este tutorial. A assinatura em produção precisa de uma chave privada devidamente protegida, uma cadeia de certificados real e uma política de confiança que seus destinatários aceitem — assinaturas autoassinadas não são adequadas para fluxos de trabalho com destinatários confiáveis.

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

Saída esperada:

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

Abra welcome-letter-signed.pdf em um leitor de PDF: os três valores vinculados aparecem em suas posições de template (issued formatado como Y-m-d, total como EUR 1,249.50), e o painel de assinatura do leitor mostra uma assinatura. A estrutura emitida segue o perfil de linha de base PAdES B-B; a NextPDF documenta isto como um recurso, não uma certificação — o escopo e a postura de conformidade estão na página de níveis PAdES. Se o template JSON estiver malformado, TemplateParser::parse() lança InvalidArgumentException com uma mensagem prefixada por Template validation failed:.

As assinaturas de método principais que você acabou de usar, na íntegra:

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

Lança ou falha com: parse() — InvalidArgumentException quando o JSON é inválido ou não está em conformidade com a estrutura esperada; fromPkcs12() — NextPDF\Exception\SignatureException quando o arquivo não pode ser lido ou parseado; setSignature() — NextPDF\Exception\InvalidConfigException quando a linearização já está habilitada (PAdES e Fast Web View são mutuamente exclusivos); save() — NextPDF\Exception\InvalidConfigException, NextPDF\Exception\PageLayoutException ou NextPDF\Exception\CompressionException quando o arquivo não pode ser gravado. bind() não lança exceção; em vez disso, reporta missingFields e warnings.

4. Quando algo falha

Seção intitulada “4. Quando algo falha”

O Composer não consegue encontrar ou buscar nextpdf/pro

Seção intitulada “O Composer não consegue encontrar ou buscar nextpdf/pro”

Um 401/403 durante composer require, ou “could not be found”, significa que o repositório privado ou suas credenciais não estão configurados para este projeto. A chave de host em auth.json deve corresponder exatamente ao host da URL do repositório. Trabalhe com Instalar e autenticar.

O runtime reporta ausência de licença

Seção intitulada “O runtime reporta ausência de licença”

O passo 2 imprime status: no_license, runtime: disabled e o aviso do avaliador — a mensagem bruta do runtime premium (compartilhada por ambas as edições) é: No license configured. Enterprise runtime is disabled. Install a license or purchase one at https://nextpdf.dev/pricing. Os recursos premium falham de forma fechada sem um envelope verificado. Um arquivo de envelope presente-mas-corrompido nunca é tratado como ausente — ele levanta NextPDF\Enterprise\Licensing\Storage\LicenseStorageException com mensagens como License file is present but unreadable: ... ou License file is present but empty: .... Coloque o envelope no caminho configurado e torne-o legível pelo usuário do processo PHP.

O certificado de assinatura não carrega

Seção intitulada “O certificado de assinatura não carrega”

CertificateInfo::fromPkcs12() lança NextPDF\Exception\SignatureException quando o arquivo .p12 não pode ser lido ou parseado. As causas usuais são um caminho errado, uma senha errada (verifique NEXTPDF_P12_PASSWORD) ou um arquivo que não é realmente PKCS#12. Verifique com openssl pkcs12 -info -in signing-cert.p12 -noout.

Para onde ir a seguir

Seção intitulada “Para onde ir a seguir”