Cómo cargar extensiones PHP de terceros en ServBay

ServBay es un potente entorno local de desarrollo web que incluye de forma predeterminada muchas extensiones PHP habituales. Normalmente, el usuario solo necesita ir a Paquetes (Packages) -> Lenguajes (Languages) -> Versión de PHP -> Extensiones para habilitarlas y configurarlas.

Sin embargo, en ocasiones los desarrolladores necesitan cargar extensiones PHP de terceros o personalizadas compiladas que ServBay no incluye por defecto. Este documento te guía detalladamente para cargar este tipo de extensiones en la versión de PHP deseada en ServBay, usando ionCube Loader como ejemplo. El proceso sirve igualmente para otras extensiones Zend o archivos .so que hayas compilado tú mismo.

Nota especial sobre extensiones Zend: ionCube Loader es una extensión Zend, las cuales interactúan de forma más profunda con el motor Zend de PHP. Por ello, al configurar deben utilizar la directiva zend_extension en lugar de extension que se usa para extensiones comunes. Es fundamental distinguir y usar la directiva correcta.

Requisitos previos

• Tienes ServBay instalado y funcionando en macOS.
• Dispones de permisos de administrador, con acceso a los archivos del sistema y la interfaz de configuración de ServBay.
• Estás familiarizado con el uso de la Terminal de macOS.
• Has identificado el archivo de extensión PHP de terceros que necesitas cargar (usualmente un archivo .so) y confirmaste que es totalmente compatible con la versión de PHP objetivo en ServBay, la arquitectura (Intel o Apple Silicon), y las opciones de compilación (NTS/ZTS).

Atención: La compatibilidad de arquitectura es crítica

ServBay ofrece paquetes PHP nativos tanto para plataformas Intel (x86_64) como para Apple Silicon (ARM64, como los chips M1/M2/M3/M4). Cuando cargues un archivo de extensión .so, asegúrate de que la arquitectura con la que fue compilado el archivo .so coincida exactamente con la del paquete PHP correspondiente en ServBay.

No mezcles archivos de arquitecturas diferentes. Si hay discrepancia, PHP no podrá iniciar o podría fallar.

Puedes usar el comando file para determinar la arquitectura de un ejecutable o archivo .so:

1. Para conocer la arquitectura del paquete PHP incluido en ServBay (reemplaza 8.3 con la versión de PHP que usas):

   file /Applications/ServBay/package/php/8.3/current/bin/php

   Salida típica:

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable arm64 # Indica arquitectura ARM64 de Apple Silicon

   o

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable x86_64 # Indica arquitectura Intel x86_64

2. Para la arquitectura de tu archivo de extensión .so descargado o compilado (reemplaza xdebug.so por el nombre de tu extensión):

   file xdebug.so

   Salida típica:

   xdebug.so: Mach-O 64-bit bundle arm64 # Indica ARM64 de Apple Silicon

   o

   xdebug.so: Mach-O 64-bit bundle x86_64 # Indica arquitectura Intel x86_64

   Asegúrate de que la arquitectura de los archivos en los pasos 1 y 2 coinciden perfectamente.

Pasos para cargar la extensión

Paso 1: Descarga el archivo de extensión de terceros (ejemplo: ionCube Loader)

1. Ve a la página oficial de descargas de ionCube Loader. Elige la versión adecuada según la arquitectura de tu macOS. Para macOS ARM64 (chips Apple Silicon serie M), descarga la versión Darwin ARM64. Puedes usar este enlace en ejemplo (verifica si hay nuevas versiones en la web oficial): https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
2. Al terminar la descarga, tendrás un archivo comprimido .tar.gz, por ejemplo ioncube_loaders_dar_arm64.tar.gz.

Paso 2: Identifica la versión de PHP objetivo y el directorio de instalación de extensiones en ServBay

1. Abre la aplicación ServBay.

2. En la barra de navegación a la izquierda, haz clic en Paquetes (Packages) y luego en Lenguajes (Languages).

3. Localiza en la lista de la derecha la versión de PHP en la que quieres instalar ionCube Loader (por ejemplo, PHP 8.3). Toma nota de esta versión.

4. Identifica el directorio de instalación de extensiones (extension_dir) para esa versión de PHP en ServBay. Aquí es donde se deben ubicar los archivos .so. La ruta depende del directorio de instalación de ServBay, de la versión de PHP y de las opciones de compilación.

   La forma más fiable es a través de la línea de comandos:

   Abre Terminal y ejecuta el comando (ajusta la ruta a la versión y ubicación de PHP concreta):

   /Applications/ServBay/package/php/8.3/current/bin/php -i | grep extension_dir

   Obtendrás una salida similar a:

   extension_dir => /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831

   Escribe exactamente esa ruta. La necesitarás más adelante.

Paso 3: Extrae y coloca el archivo Loader

1. Abre la Terminal.

2. Usa el comando cd para ir a la carpeta donde descargaste el archivo .tar.gz (normalmente ~/Downloads):

   cd ~/Downloads

3. Extrae el contenido:

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   Esto creará un nuevo directorio llamado ioncube en tu ubicación actual.

4. Entra al directorio ioncube:

   cd ioncube

5. Aquí verás archivos .so para diversas versiones de PHP, por ejemplo ioncube_loader_dar_8.3.so. Localiza el que corresponde a la versión de PHP que identificaste en el paso 2.

6. Copia el archivo .so correcto al directorio de extensiones de PHP (que obtuviste en el paso anterior). Por ejemplo:

   cp ioncube_loader_dar_8.3.so /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/

   • Asegúrate de reemplazar la ruta /Applications/ServBay/.../no-debug-non-zts-20230831/ por la que obtuviste con php -i.
   • Verifica que estás copiando el archivo .so correspondiente a la versión exacta y la arquitectura de PHP en ServBay (ver requerimientos previos).

Paso 4: Configura PHP en ServBay

1. Vuelve a la interfaz de ServBay.

2. Confirma que está seleccionada la opción Lenguajes (Languages) y haz clic en la versión de PHP objetivo (ejemplo: PHP 8.3).

3. En la parte de configuración que se despliega a la derecha, haz clic en la pestaña PHP.

4. Desplázate hasta encontrar la caja de texto Additional Parameters (Parámetros adicionales).

5. Añade la siguiente línea para indicar el nombre del Loader usado:

   zend_extension = ioncube_loader_dar_8.3.so

   • Importante: Reemplaza ioncube_loader_dar_8.3.so por el nombre real del archivo que copiaste.
   • Utiliza zend_extension en vez de extension ya que ionCube Loader es una extensión Zend.
   • Como el archivo .so ya se encuentra en el extension_dir, solo debes poner el nombre del archivo (sin ruta completa).
   • Si ya hay otras configuraciones en la caja, pon la nueva en una línea aparte.

   (La captura es ejemplo, la interfaz real podría variar según la versión)

6. Haz clic en el botón Guardar (Save) en la parte inferior derecha para guardar la configuración.

Paso 5: Reinicia el servicio PHP

Al hacer clic en Guardar, ServBay detectará automáticamente el cambio en la configuración e intentará reiniciar suavemente los servicios correspondientes (incluido PHP). Habitualmente no es necesario realizar pasos adicionales para reiniciar.

Paso 6: Verifica que la carga fue exitosa

Puedes comprobar si ionCube Loader se cargó correctamente de dos maneras habituales:

1. Por línea de comandos:

   • Abre la Terminal.

   • Ejecuta el siguiente comando para listar los módulos PHP cargados (usa la ruta completa del PHP objetivo):

     /Applications/ServBay/package/php/8.3/current/bin/php -m | grep -i ioncube

     Si todo fue bien, verás una línea similar a ionCube Loader.

   • También puedes ejecutar php -v para obtener la información de versión de PHP, normalmente ionCube Loader aparece justo debajo de la información del motor Zend:

     /Applications/ServBay/package/php/8.3/current/bin/php -v

     Ejemplo de salida con éxito (los números pueden variar):

     PHP 8.3.16 (cli) (built: Jan 31 2025 15:09:39) (NTS)
     Copyright (c) The PHP Group
     Zend Engine v4.3.16, Copyright (c) Zend Technologies
         with the ionCube PHP Loader v14.4.0, Copyright (c) 2002-2024, by ionCube Ltd.

     Observa la línea with the ionCube PHP Loader ....

2. Por la función phpinfo():

   • Crea un nuevo archivo PHP, por ejemplo info.php, en el directorio raíz de tu web (p. ej.: /Applications/ServBay/www/servbay.demo/ u otra ruta de dominio local).
   • El archivo solo debe contener lo siguiente:

     <?php
     phpinfo();
     ?>

   • Accede a este archivo desde el navegador (ejemplo: http://servbay.demo/info.php, ajusta al dominio local correspondiente).
   • En la página de salida de phpinfo(), busca "ionCube" (usando la función buscar del navegador, normalmente Cmd + F o Ctrl + F). Si la extensión cargó bien, verás un bloque específico de información sobre ionCube Loader, mostrando versión, licencia, y otros detalles.

Si en cualquiera de los pasos aparece la información de ionCube Loader, la extensión está correctamente cargada.

Preguntas frecuentes y resolución de problemas

• PHP no inicia o falla: Lo más frecuente es que la arquitectura del archivo de extensión no coincide con la del paquete PHP. Verifica cuidadosamente la compatibilidad de arquitectura siguiendo los pasos de requisitos previos. También pueden influir incompatibilidades de versión o de opciones de compilación.
• Ruta incorrecta de extension_dir: Asegúrate de copiar el archivo .so en el directorio real extension_dir de la versión de PHP en ServBay. El comando php -i | grep extension_dir te indica la ruta exacta.
• Error en la directiva de configuración: Comprueba que la línea añadida en Additional Parameters es correcta. Para extensiones Zend usa zend_extension = nombre.so; para extensiones comunes, extension = nombre.so. El nombre debe coincidir exactamente con el del archivo en extension_dir (mayúsculas y minúsculas incluidas).
• Problemas de permisos de archivo: El usuario con el que corre ServBay (normalmente tu usuario de macOS) debe tener permisos de lectura sobre el archivo .so copiado y la carpeta donde está ubicado. Normalmente no hay conflictos de permisos si copias en el directorio del paquete ServBay, pero si cambiaste permisos manualmente, revisa esto.
• ServBay no se reinicia: Aunque normalmente ServBay reinicia automáticamente, si los cambios parecen no aplicarse, intenta parar y reiniciar manualmente el servicio en la interfaz de ServBay, o reinicia la aplicación.
• No aparece la información en phpinfo(): Asegúrate de estar accediendo desde un sitio gestionado por ServBay y con la versión de PHP configurada. Si tienes varias versiones de PHP o múltiples sitios, verifica que estés consultando el entorno correcto.

Resumen

Siguiendo estos pasos detallados, podrás cargar correctamente ionCube Loader u otras extensiones PHP en formato .so de terceros en la versión de PHP gestionada por ServBay que elijas. La clave es identificar con precisión la versión de PHP objetivo, encontrar el extension_dir adecuado, ubicar allí el archivo de extensión compatible y en la configuración de ServBay añadir la directiva correcta (zend_extension o extension) con el nombre del archivo. Si surge algún problema, revisa la sección de resolución de problemas, y pon especial atención a la compatibilidad de arquitectura y a las rutas de los archivos.