Como instalar ionCube Loader no HestiaCP com validação por versão PHP

Quando uma aplicação comercial exige ionCube e o módulo não está carregado, o sintoma costuma aparecer como erro genérico de execução ou tela branca. Neste guia, documento o processo operacional que utilizo para instalar ionCube no HestiaCP sem quebrar múltiplas versões de PHP.

Pré-check de ambiente

Identifique versão ativa do PHP CLI e do pool web:

php -v
php -m | grep -i ioncube || echo 'ionCube não carregado no CLI'

No HestiaCP, confira versão do domínio em uso para não instalar loader errado.

Download e extração do loader

cd /usr/local/src
wget https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz
tar -xzf ioncube_loaders_lin_x86-64.tar.gz
cd ioncube
ls -lah

Descobrir extensão correta para a versão PHP

Para PHP 8.1, por exemplo, use ioncube_loader_lin_8.1.so.

Descubra diretório de extensão:

php -i | grep '^extension_dir'

Copie loader:

cp ioncube_loader_lin_8.1.so /usr/lib/php/20210902/

Ajuste o caminho conforme seu extension_dir.

Habilitar no PHP-FPM (Hestia)

Crie arquivo dedicado no mods-available:

echo 'zend_extension=/usr/lib/php/20210902/ioncube_loader_lin_8.1.so' > /etc/php/8.1/mods-available/ioncube.ini
phpenmod ioncube

Reinicie serviços:

systemctl restart php8.1-fpm
systemctl reload nginx
systemctl reload apache2

Validação pós-instalação

php -v | grep -i ioncube
php -m | grep -i ioncube

No painel web, crie info.php temporário:

<?php phpinfo();

Confirme seção ionCube e remova o arquivo após teste.

Erros comuns e correções

Wrong architecture

Causa: loader x86 em host x86_64 ou incompatibilidade de binário.

Cannot load ... undefined symbol

Causa: versão do loader incompatível com versão do PHP.

Funciona no CLI e falha no web

Causa: módulo habilitado no CLI mas não no FPM do domínio.

Diagnóstico avançado por pool e SAPI

Em hosts com múltiplas versões, eu valido SAPI por contexto para garantir que o mesmo módulo esteja carregado no processo correto.

Validar CLI:

php -i | grep -i 'loaded configuration file'
php -i | grep -i ioncube

Validar FPM do domínio via script temporário:

<?php
echo PHP_VERSION . PHP_EOL;
echo php_sapi_name() . PHP_EOL;
var_dump(extension_loaded('ionCube Loader'));

Se CLI estiver com ionCube e FPM não, o problema está no caminho de .ini do pool ativo (/etc/php/X.Y/fpm/conf.d/) e não no loader em si.

Checklist de homologação pós-instalação

1. validar tela de login da aplicação ionCube;
2. executar funcionalidade crítica (não só abrir dashboard);
3. validar logs PHP-FPM:

journalctl -u php8.1-fpm -n 100 --no-pager

1. validar erros no webserver:

tail -n 100 /var/log/nginx/error.log
tail -n 100 /var/log/apache2/error.log

Observação sobre atualizações de PHP

Após upgrade de PHP (8.1 -> 8.2), o ionCube precisa ser revalidado para a nova versão. O loader antigo não é reaproveitável entre majors/minors sem compatibilidade explícita.

Rollback

Se houver impacto:

phpdismod ioncube
systemctl restart php8.1-fpm

Mantenha backup do .ini e registre mudança no controle operacional.

Conclusão

ionCube em HestiaCP exige precisão de versão e validação por contexto de execução (CLI e FPM). Quando esse checklist é seguido, a instalação fica estável e auditável para ambientes multi-PHP.

Este post está licenciado sob CC BY-NC.