Configurar o ionCube Loader para as edições premium do NextPDF

Visão geral

Algumas distribuições premium do NextPDF são entregues como PHP codificado com ionCube, então o ionCube Loader correspondente precisa estar instalado no runtime do PHP antes que o código seja executado. Isso se aplica a:

As builds de avaliação do NextPDF Pro e Enterprise, e
A build oficial (paga) do NextPDF Pro.

Para a entrega oficial do NextPDF Enterprise, o mecanismo de empacotamento depende do seu contrato. Siga as instruções de entrega presentes nos termos da sua licença em vez de presumir um runtime específico; consulte Licenciamento e ativação.

Esta página é um guia prático de configuração: o que é o ionCube, como instalar e verificar o Loader, onde fica o arquivo de licença para a build paga do Pro codificada com ionCube, como executá-la em contêineres e como corrigir as falhas mais comuns. A versão de PHP suportada é a 8.4, e o Loader que você instalar precisa corresponder exatamente a esse runtime.

O que é o ionCube e por que o NextPDF o utiliza

O ionCube é um codificador de PHP comercial combinado com um componente de runtime gratuito chamado ionCube Loader. O Loader é uma extensão de PHP (Zend). Quando o PHP inicia, o Loader permite que os arquivos codificados sejam decodificados e executados; sem ele, um arquivo codificado não pode ser executado e o PHP relata um erro de loader.

O NextPDF usa a codificação ionCube para proteger o código-fonte premium proprietário e, ao mesmo tempo, continuar entregando PHP instalável que você implanta e executa como qualquer outro pacote do Composer. A codificação não muda a forma como você chama a biblioteca — sua aplicação tem como alvo os mesmos contratos públicos — ela apenas acrescenta a exigência de que o Loader esteja presente no runtime.

Para os downloads do Loader e as instruções específicas de cada versão, oficiais e definitivas, use a documentação do fornecedor em ioncube.com (a documentação e o guia de instalação do ionCube Loader). Esta página aborda a configuração específica do NextPDF; o fornecedor é a fonte de verdade quanto ao próprio Loader.

Requisitos

Instale o ionCube Loader que corresponda ao seu runtime do PHP em todos os eixos. Uma divergência em qualquer um deles é a causa mais comum de falha:

Eixo	Deve corresponder a
Versão do PHP	8.4 (o NextPDF premium requer `>=8.4 <9.0`).
Sistema operacional	O SO que o pacote do Loader tem como alvo (Linux, Windows, macOS).
Arquitetura	A arquitetura de CPU do host, normalmente 64 bits (`x86-64` ou `aarch64`).
Thread safety	Non-thread-safe (NTS) ou thread-safe (ZTS), correspondendo à sua build de PHP.

Além do Loader, você também precisa de:

O pacote premium do NextPDF instalado via Composer — nextpdf/pro, nextpdf/enterprise ou o metapacote nextpdf/premium.
Para builds pagas, o seu arquivo de licença. Para a build paga do Pro codificada com ionCube, consulte Posicionamento da licença abaixo.

Para ler os valores atuais da sua build, execute php -i (ou chame phpinfo()) e verifique as linhas PHP Version, Architecture e Thread Safety. Na maioria das implantações de CLI e PHP-FPM, o thread safety está desativado (NTS); o mod_php clássico do Apache em algumas plataformas é ZTS. Baixe o pacote do Loader para esses valores exatos.

Instalar o Loader

As etapas a seguir descrevem o fluxo geral. Para os nomes exatos dos arquivos e o layout de diretórios do pacote atual, siga a documentação do ionCube Loader em ioncube.com.

Baixe o pacote do Loader que corresponda ao seu ambiente (PHP 8.4, seu SO, arquitetura e NTS/ZTS). O pacote contém um arquivo de loader por versão de PHP e variante de thread safety.
Coloque o arquivo de loader no diretório de extensões do PHP. Use o extension_dir informado por php -i. No Linux/macOS, o arquivo é ioncube_loader_<os>_8.4.so (use ..._8.4_ts.so para uma build ZTS); no Windows, é ioncube_loader_win_8.4.dll (ou a variante ZTS ..._ts.dll).
Registre-o no php.ini como um zend_extension. O ionCube Loader precisa ser carregado como um zend_extension, e não como uma extension comum, e deve ser carregado antes das outras extensões. Adicione uma única linha, usando um caminho absoluto para o arquivo de loader:
```
zend_extension=/full/path/to/ioncube_loader_lin_8.4.so
```
No Windows, use o caminho completo até o .dll:
```
zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"
```
Se a sua plataforma usa diretórios de include no estilo conf.d, coloque esta linha em um arquivo que seja lido cedo (por exemplo, um 00-ioncube.ini) para que o Loader seja inicializado antes das outras extensões.
Reinicie o runtime do PHP. Reinicie o PHP-FPM, o seu servidor web (Apache/Nginx) ou simplesmente reexecute a CLI — o que quer que execute a sua aplicação. Um processo de longa duração mantém a configuração antiga até ser reiniciado.

Verificar

Confirme que o Loader está ativo antes de tentar carregar o NextPDF.

Primeiro, verifique o banner de versão do PHP. Quando o Loader está instalado, o php -v acrescenta uma linha que o nomeia:

php -v

PHP 8.4.x (cli) ...
    with Zend OPcache v8.4.x, ...
    with the ionCube PHP Loader ...

A frase “with the ionCube PHP Loader” é o sinal de que o Loader está ativo para aquele runtime. Para uma implantação web (FPM / mod_php), o banner da CLI não é suficiente — esse runtime pode usar um php.ini diferente. Confirme o runtime web com um pequeno script servido pelo servidor web:

<?php
// loader-check.php — delete after verifying.
var_dump(extension_loaded('ionCube Loader'));
phpinfo(); // The output includes an "ionCube PHP Loader" section when active.

Por fim, confirme que uma classe premium do NextPDF de fato é carregada por meio do autoloader do Composer. Isso prova que o código codificado é executado de ponta a ponta:

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

// A premium class resolves only when the Loader can decode the package.
var_dump(class_exists(\NextPDF\Pro\Document\PdfPortfolio::class));

Se o php -v nomear o Loader, o phpinfo() web exibir a seção do ionCube e a classe premium for resolvida, o Loader está configurado corretamente.

Posicionamento da licença (a build paga do Pro codificada com ionCube)

O ionCube usa um modelo de licenciamento simples: o código codificado verifica a existência de um arquivo de licença em tempo de execução e se recusa a executar quando o arquivo está ausente, ilegível ou expirado. Isso se aplica à build paga do Pro codificada com ionCube — para ela, você coloca o arquivo de licença fornecido pela sua compra em um local onde o runtime possa encontrá-lo.

Esse mecanismo de arquivo de licença do ionCube é específico da build codificada com ionCube. A entrega oficial do NextPDF Enterprise não é presumida aqui como codificada com ionCube; o seu empacotamento e o tratamento da licença são regidos pelos termos da sua licença — consulte Licenciamento e ativação.

Os caminhos exatos dependem do ambiente, então mantenha isto em termos gerais:

Coloque o arquivo de licença no local que as instruções de entrega do NextPDF especificam — geralmente junto ao pacote codificado ou em um diretório que a aplicação possa ler. Garanta que o usuário do processo do PHP tenha permissão de leitura.
Não renomeie o arquivo, a menos que as suas instruções digam para fazê-lo; o loader procura por um nome específico.
Em contêineres e em implantações somente leitura, monte ou copie o arquivo de licença para dentro da imagem ou para um caminho legível e gravável que o runtime enxergue (consulte Docker e contêineres).

O arquivo de licença rege a ativação no nível do runtime; ele é separado da licença no nível da aplicação que seleciona a sua edição e os seus recursos. Para os termos, durações e o que a sua assinatura dá direito, consulte Licenciamento e ativação e o seu contrato de licença — esta página não define os termos da licença.

Solução de problemas

”Loader not installed” / “Failed loading … ioncube_loader”

O Loader não está ativo no runtime que executou o código, ou o caminho está errado. Verifique novamente se a linha zend_extension aponta para um arquivo existente com um caminho absoluto, se você reiniciou o runtime e se verificou o mesmo runtime (CLI vs FPM) com php -v / phpinfo(). Uma mensagem Failed loading geralmente significa que o arquivo existe, mas não corresponde à build do PHP (consulte o próximo item).

Divergência de versão do PHP, de NTS/ZTS ou de arquitetura

Um Loader compilado para uma versão de PHP, um modo de thread safety ou uma arquitetura diferentes não será carregado. Confirme PHP Version, Thread Safety e Architecture a partir de php -i e, então, instale o arquivo do Loader para o PHP 8.4 com o NTS/ZTS e a quantidade de bits correspondentes. O sufixo 8.4 vs 8.4_ts (ou _ts.dll) é o seletor de thread safety — usar o errado é um erro frequente.

Ordem de carregamento do Loader

O ionCube Loader precisa ser um zend_extension e deve ser inicializado antes das outras extensões. Se você vir avisos sobre o Loader sendo carregado depois de outras extensões, mova a sua linha zend_extension para mais cedo — ou, com um layout conf.d, dê ao seu arquivo de include um nome que apareça primeiro na ordenação (por exemplo, 00-ioncube.ini).

A CLI, o FPM e o servidor web usam arquivos php.ini diferentes

O PHP costuma carregar um php.ini diferente para a CLI e para o PHP-FPM ou o mod_php. Configurar apenas a CLI deixa o runtime web sem o Loader (ou vice-versa). Execute php --ini para ver qual arquivo a CLI usa e verifique a linha Loaded Configuration File na saída do phpinfo() web. Adicione a linha zend_extension a todos os arquivos php.ini que executam o NextPDF e reinicie cada runtime.

Arquivo de licença não encontrado ou expirado

Para a build paga do Pro codificada com ionCube, um arquivo de licença ausente, ilegível ou expirado impede a execução do código codificado. Verifique se o arquivo está no local esperado, se o usuário do processo do PHP consegue lê-lo e se ele não expirou. Para dúvidas sobre renovação e prazos, consulte Licenciamento e ativação e o seu contrato de licença.

Interações com o OPcache

O OPcache armazena em cache os scripts compilados, mas os arquivos codificados com ionCube são decodificados pelo Loader em tempo de execução. Se você alterou o Loader ou a sua configuração e o runtime ainda se comporta como se ele estivesse ausente, reinicie o runtime do PHP (o que limpa o OPcache) em vez de depender de um hot reload. Mantenha o zend_extension do ionCube registrado para que ele carregue antes do OPcache; os dois coexistem, e o php -v deve listar ambos.

Docker e contêineres

Em uma implantação conteinerizada, instale o Loader na imagem e garanta que ele corresponda à build de PHP do contêiner — não à do seu host. A imagem base fixa a versão do PHP, o SO, a arquitetura e o modo de thread safety, então baixe o pacote do Loader para esses valores.

Um build de imagem típico:

Comece a partir de uma imagem base de PHP 8.4 (observe se ela é NTS ou ZTS — as tags oficiais php:8.4-cli / 8.4-fpm / 8.4-apache são NTS, enquanto as tags que contêm zts são thread-safe; escolha o Loader correspondente).
Adicione o arquivo do ionCube Loader correspondente ao extension_dir da imagem.
Escreva a linha zend_extension=... no php.ini da imagem (ou em um include conf.d).
Para a build paga do Pro codificada com ionCube, forneça o arquivo de licença copiando-o para dentro da imagem ou montando-o em tempo de execução em um caminho que o contêiner possa ler.

Como o Loader é incorporado à imagem, o mesmo contêiner é executado de forma idêntica em todos os lugares. Se mais tarde você atualizar o PHP da imagem base, substitua o arquivo do Loader pela build que corresponde ao novo runtime.