Configurar el ionCube Loader para las ediciones premium de NextPDF

En resumen

Algunas distribuciones premium de NextPDF se entregan como PHP codificado con ionCube, de modo que el ionCube Loader correspondiente debe instalarse en el runtime de PHP antes de que el código pueda ejecutarse. Esto se aplica a:

• Las compilaciones de evaluación de NextPDF Pro y Enterprise, y
• La compilación oficial (de pago) de NextPDF Pro.

Para la entrega oficial de NextPDF Enterprise, el mecanismo de empaquetado depende del contrato. Conviene seguir las instrucciones de entrega de los términos de licencia en lugar de dar por supuesto un runtime concreto; véase Licencias y activación.

Esta página es una guía práctica de configuración: qué es ionCube, cómo instalar y verificar el Loader, dónde se coloca el archivo de licencia para la compilación de pago de Pro codificada con ionCube, cómo ejecutarlo en contenedores y cómo resolver los fallos habituales. La versión de PHP admitida es 8.4, y el Loader que se instale debe coincidir exactamente con ese runtime.

Qué es ionCube y por qué NextPDF lo utiliza

ionCube es un codificador de PHP comercial acompañado de un componente de runtime gratuito llamado ionCube Loader. El Loader es una extensión de PHP (Zend). Cuando PHP arranca, el Loader permite descodificar y ejecutar los archivos codificados; sin él, un archivo codificado no puede ejecutarse y PHP informa de un error del loader en su lugar.

NextPDF utiliza la codificación ionCube para proteger el código fuente premium propietario sin dejar de entregar PHP instalable que se despliega y se ejecuta como cualquier otro paquete de Composer. La codificación no cambia la forma de invocar la biblioteca —la aplicación apunta a los mismos contratos públicos—, solo añade el requisito de que el Loader esté presente en el runtime.

Para las descargas del Loader y las instrucciones oficiales específicas de cada versión, conviene usar la documentación del proveedor en ioncube.com (la documentación y la guía de instalación del ionCube Loader). Esta página cubre la configuración específica de NextPDF; el proveedor es la fuente de verdad del Loader en sí.

Requisitos

Instale el ionCube Loader que coincida con su runtime de PHP en todos los ejes. Un desajuste en cualquiera de ellos es la causa de fallo más habitual:

Eje	Debe coincidir con
Versión de PHP	8.4 (NextPDF premium requiere >=8.4 <9.0).
Sistema operativo	El SO al que está destinado el paquete del Loader (Linux, Windows, macOS).
Arquitectura	La arquitectura de CPU del host, normalmente de 64 bits (x86-64 o aarch64).
Seguridad de hilos	Sin seguridad de hilos (NTS) o con seguridad de hilos (ZTS), según su compilación de PHP.

Además del Loader, también se necesita:

• El paquete premium de NextPDF instalado a través de Composer: nextpdf/pro, nextpdf/enterprise o el metapaquete nextpdf/premium.
• Para las compilaciones de pago, su archivo de licencia. Para la compilación de pago de Pro codificada con ionCube, véase Ubicación de la licencia más abajo.

Para consultar los valores actuales de su compilación, ejecute php -i (o llame a phpinfo()) y revise las líneas PHP Version, Architecture y Thread Safety. En la mayoría de los despliegues de CLI y PHP-FPM la seguridad de hilos está deshabilitada (NTS); el clásico mod_php de Apache en algunas plataformas es ZTS. Descargue el paquete del Loader para esos valores exactos.

Instalar el Loader

Los pasos siguientes son el flujo general. Remítase a la documentación del ionCube Loader en ioncube.com para conocer los nombres de archivo y la disposición de directorios exactos del paquete actual.

1. Descargue el paquete del Loader que coincida con su entorno (PHP 8.4, su SO, arquitectura y NTS/ZTS). El paquete contiene un archivo de loader por cada versión de PHP y variante de seguridad de hilos.

2. Coloque el archivo de loader en el directorio de extensiones de PHP. Use el extension_dir que indica php -i. En Linux/macOS el archivo es ioncube_loader_<os>_8.4.so (use ..._8.4_ts.so para una compilación ZTS); en Windows es ioncube_loader_win_8.4.dll (o la variante ZTS ..._ts.dll).

3. Regístrelo en php.ini como zend_extension. El ionCube Loader debe cargarse como zend_extension, no como un extension normal, y debería cargarse antes que otras extensiones. Añada una sola línea, usando una ruta absoluta al archivo del loader:

   zend_extension=/full/path/to/ioncube_loader_lin_8.4.so

   En Windows, use la ruta completa al .dll:

   zend_extension="C:\php\ext\ioncube_loader_win_8.4.dll"

   Si su plataforma usa directorios de inclusión al estilo conf.d, coloque esta línea en un archivo que se lea pronto (por ejemplo, un 00-ioncube.ini) para que el Loader se inicialice antes que otras extensiones.

4. Reinicie el runtime de PHP. Reinicie PHP-FPM, su servidor web (Apache/Nginx) o simplemente vuelva a ejecutar la CLI, según lo que ejecute su aplicación. Un proceso de larga duración conserva la configuración anterior hasta que se reinicia.

Verificar

Confirme que el Loader está activo antes de intentar cargar NextPDF.

Primero, revise el banner de versión de PHP. Cuando el Loader está instalado, php -v añade una línea que lo nombra:

php -v

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

La frase «with the ionCube PHP Loader» es la señal de que el Loader está activo para ese runtime. Para un despliegue web (FPM / mod_php), el banner de la CLI no basta: ese runtime puede usar un php.ini distinto. Confirme el runtime web con un pequeño script servido por el 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 último, confirme que una clase premium de NextPDF se carga realmente a través del autoloader de Composer. Esto demuestra que el código codificado se ejecuta de principio a fin:

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

Si php -v nombra el Loader, el phpinfo() web muestra la sección de ionCube y la clase premium se resuelve, el Loader está configurado correctamente.

Ubicación de la licencia (la compilación de pago de Pro codificada con ionCube)

ionCube usa un modelo de licencias sencillo: el código codificado busca un archivo de licencia en tiempo de ejecución y se niega a ejecutarse cuando el archivo falta, es ilegible o ha caducado. Esto se aplica a la compilación de pago de Pro codificada con ionCube: para ella, se coloca el archivo de licencia que proporciona la compra allí donde el runtime pueda encontrarlo.

Este mecanismo de archivo de licencia de ionCube es específico de la compilación codificada con ionCube. Aquí no se da por supuesto que la entrega oficial de NextPDF Enterprise esté codificada con ionCube; su empaquetado y la gestión de su licencia se rigen por sus términos de licencia; véase Licencias y activación.

Las rutas exactas dependen del entorno, así que conviene mantener esto en términos generales:

• Coloque el archivo de licencia en la ubicación que indiquen las instrucciones de entrega de NextPDF, habitualmente junto al paquete codificado o en un directorio que la aplicación pueda leer. Asegúrese de que el usuario del proceso de PHP tenga permiso de lectura.
• No cambie el nombre del archivo a menos que sus instrucciones lo indiquen; el loader busca un nombre concreto.
• En contenedores y en despliegues de solo lectura, monte o copie el archivo de licencia dentro de la imagen o en una ruta escribible y legible que el runtime vea (véase Docker y contenedores).

El archivo de licencia rige la activación a nivel de runtime; es independiente de la licencia a nivel de aplicación que selecciona la edición y las funciones. Para conocer los términos, las duraciones y lo que da derecho su suscripción, véase Licencias y activación y su contrato de licencia; esta página no define los términos de licencia.

Resolución de problemas

«Loader not installed» / «Failed loading … ioncube_loader»

El Loader no está activo en el runtime que ejecutó el código, o la ruta es incorrecta. Vuelva a comprobar que la línea zend_extension apunta a un archivo existente con una ruta absoluta, que reinició el runtime y que verificó el mismo runtime (CLI o FPM) con php -v / phpinfo(). Un mensaje de Failed loading suele significar que el archivo existe pero no coincide con la compilación de PHP (véase el punto siguiente).

Desajuste de versión de PHP, NTS/ZTS o arquitectura

Un Loader compilado para una versión de PHP, un modo de seguridad de hilos o una arquitectura distintos no se cargará. Confirme PHP Version, Thread Safety y Architecture con php -i y, a continuación, instale el archivo del Loader para PHP 8.4 con el NTS/ZTS y la arquitectura de bits coincidentes. El sufijo 8.4 frente a 8.4_ts (o _ts.dll) es el selector de seguridad de hilos: usar el equivocado es un error frecuente.

Orden de carga del Loader

El ionCube Loader debe ser un zend_extension y debería inicializarse antes que otras extensiones. Si ve advertencias sobre la carga del Loader después de otras extensiones, mueva su línea zend_extension más arriba o, con una disposición conf.d, dé a su archivo de inclusión un nombre que se ordene primero (por ejemplo, 00-ioncube.ini).

La CLI, FPM y el servidor web usan archivos php.ini distintos

PHP suele cargar un php.ini distinto para la CLI que para PHP-FPM o mod_php. Configurar solo la CLI deja el runtime web sin el Loader (o viceversa). Ejecute php --ini para ver qué archivo usa la CLI, y revise la línea Loaded Configuration File en la salida del phpinfo() web. Añada la línea zend_extension a cada php.ini que ejecute NextPDF, y reinicie cada runtime.

Archivo de licencia no encontrado o caducado

Para la compilación de pago de Pro codificada con ionCube, un archivo de licencia ausente, ilegible o caducado impide que el código codificado se ejecute. Verifique que el archivo está en la ubicación esperada, que el usuario del proceso de PHP puede leerlo y que no ha caducado. Para las preguntas sobre renovación y términos, véase Licencias y activación y su contrato de licencia.

Interacciones con OPcache

OPcache almacena en caché los scripts compilados, pero los archivos codificados con ionCube los descodifica el Loader en tiempo de ejecución. Si cambió el Loader o su configuración y el runtime sigue comportándose como si estuviera ausente, reinicie el runtime de PHP (lo que vacía OPcache) en lugar de confiar en una recarga en caliente. Mantenga el zend_extension de ionCube registrado para que se cargue antes que OPcache; ambos coexisten, y php -v debería listar los dos.

Docker y contenedores

En un despliegue en contenedores, instale el Loader en la imagen y asegúrese de que coincide con la compilación de PHP del contenedor, no con la de su host. La imagen base fija la versión de PHP, el SO, la arquitectura y el modo de seguridad de hilos, así que descargue el paquete del Loader para esos valores.

Una compilación de imagen típica:

1. Parta de una imagen base de PHP 8.4 (fíjese en si es NTS o ZTS: las etiquetas oficiales php:8.4-cli / 8.4-fpm / 8.4-apache son NTS, mientras que las etiquetas que contienen zts son de seguridad de hilos; elija el Loader para que coincida).
2. Añada el archivo del ionCube Loader coincidente al extension_dir de la imagen.
3. Escriba la línea zend_extension=... en el php.ini de la imagen (o en una inclusión conf.d).
4. Para la compilación de pago de Pro codificada con ionCube, proporcione el archivo de licencia copiándolo en la imagen o montándolo en tiempo de ejecución en una ruta que el contenedor pueda leer.

Como el Loader está integrado en la imagen, el mismo contenedor se ejecuta de forma idéntica en todas partes. Si más adelante actualiza el PHP de la imagen base, sustituya el archivo del Loader por la compilación que coincida con el nuevo runtime.

Véase también

• Licencias y activación
• NextPDF Premium
• Elija su camino