Compilación e instalación de módulos PHP personalizados en ServBay

ServBay es un potente entorno local de desarrollo web para macOS y Windows que integra una amplia variedad de paquetes tecnológicos, diseñados para cubrir las necesidades de los desarrolladores web modernos. Incluye PHP, Node.js, Python, Go, Java, bases de datos (MySQL, PostgreSQL, MongoDB), sistemas de caché (Redis) y servidores web (Caddy, Nginx, Apache), entre otros. ServBay ofrece soporte multiversión para cada paquete, permitiéndole cambiar de entorno de manera flexible según las necesidades de su proyecto.

Aunque ServBay ya incluye muchos de los módulos PHP más utilizados, en ciertos escenarios de desarrollo puede requerirse compilar e instalar módulos adicionales para ampliar las funcionalidades de PHP o integrar servicios de terceros específicos.

En este artículo encontrará una guía detallada sobre cómo compilar e instalar módulos PHP personalizados para la versión de PHP que esté utilizando en ServBay. Usaremos como ejemplo dos módulos populares: el de procesamiento de imágenes imagick y el controlador de bases de datos SQL Server sqlsrv, explicando el proceso paso a paso para que pueda añadir nuevas capacidades a su entorno PHP en ServBay sin complicaciones.

Requisitos previos

Información importante

Antes de comenzar a compilar cualquier módulo PHP, el paso crucial es inicializar correctamente el entorno de compilación siguiendo las instrucciones de la documentación oficial de ServBay y asegurarse de configurar adecuadamente las variables de entorno del sistema. Este paso es fundamental para compilar cualquier paquete de ServBay (incluidos los módulos PHP) con éxito. Si se omite o realiza incorrectamente este proceso, lo más probable es que la compilación falle, generando errores como comandos no encontrados, bibliotecas ausentes o archivos de cabecera inexistentes.

El script de inicialización de ServBay configura variables de entorno esenciales, tales como PATH (que apunta a las herramientas de construcción internas), SERVBAY_PACKAGE_FULL_PATH (ruta raíz de los paquetes de ServBay) y CPU_NUMBER (para compilaciones paralelas con varios núcleos). Estas variables son indispensables para los comandos de compilación.

Para ver los pasos detallados de inicialización del entorno de compilación de ServBay, consulte la documentación: Compilación secundaria en ServBay. Asegúrese de entender y seguir todas las indicaciones antes de continuar.

Antes de proceder a compilar módulos, verifique que ha completado exitosamente la inicialización del entorno de compilación de ServBay y que las variables de entorno necesarias estén correctamente configuradas en su terminal.

Importancia de especificar la versión de PHP

Uno de los pilares de ServBay es el soporte para múltiples versiones de PHP en un mismo sistema, lo cual proporciona una gran flexibilidad para gestionar distintos proyectos. Sin embargo, al compilar módulos PHP, es imprescindible seleccionar la versión específica de PHP para la que desea realizar la compilación. Las herramientas cruciales como phpize y php-config están ligadas a cada versión concreta de PHP.

• phpize: prepara el entorno de compilación para extensiones PHP, leyendo el archivo config.m4 y generando el script estándar configure, que es el primer paso habitual para compilar software en C/C++.
• php-config: proporciona información detallada de configuración de la versión específica de PHP instalada, incluidos flags de compilador, rutas a directorios de cabeceras, rutas de bibliotecas y carpetas de instalación de extensiones. El script configure usa php-config para obtener estos datos y asegurar una correcta construcción y vinculación del módulo con la versión objetivo de PHP.

Por lo tanto, siempre debe especificar la ruta completa de las herramientas phpize, php-config y cualquier otro comando relacionado con la compilación de PHP, para la versión de PHP sobre la que quiere instalar el módulo.

Ejemplo de rutas

Si quiere compilar un módulo para PHP 8.3 instalado en ServBay:

macOS:

• phpize: /Applications/ServBay/package/php/8.3/current/bin/phpize
• php-config: /Applications/ServBay/package/php/8.3/current/bin/php-config

Windows:

• phpize: C:\ServBay\package\php\8.3\current\bin\phpize
• php-config: C:\ServBay\package\php\8.3\current\bin\php-config

Elegir correctamente la versión asegura que el módulo compilado sea compatible con su entorno PHP objetivo, evitando errores de compilación y problemas de símbolos no encontrados en tiempo de ejecución.

En esta documentación, los ejemplos se basan en PHP 8.3 de ServBay. En sus operaciones reales, reemplace la ruta de los comandos por la correspondiente a la versión de PHP instalada en su ServBay.

Compilación del módulo PHP imagick

El módulo imagick es una extensión muy popular que, basada en la potente biblioteca de herramientas de línea de comandos ImageMagick, añade avanzadas capacidades de procesamiento de imágenes a PHP. Con imagick podrá realizar operaciones como redimensionado, recorte, conversión de formatos, marcas de agua, composición de imágenes y mucho más. A continuación se detallan los pasos para compilar e instalar este módulo para una versión específica de PHP en ServBay:

Paso 1: Instalar la biblioteca ImageMagick

El módulo PHP imagick requiere que la biblioteca ImageMagick esté instalada en el sistema.

macOS

Se recomienda utilizar el gestor de paquetes Homebrew. Si no lo tiene instalado, visite el sitio oficial de Homebrew para ver cómo hacerlo.

Abra la terminal y ejecute:

brew install imagemagick

Windows

En Windows, es necesario descargar y instalar manualmente ImageMagick. Visite la página oficial de descargas de ImageMagick y seleccione la versión adecuada.

Asegúrese de instalar una versión con bibliotecas de desarrollo y agregue la ruta de instalación a sus variables de entorno del sistema.

Paso 2: Obtener el código fuente de imagick

A continuación, descargue el código fuente del módulo imagick desde el repositorio oficial de extensiones de PHP (PECL). Acceda a la página de imagick en PECL, elija la versión que necesite (se recomienda la última estable) y obtenga el enlace de descarga. El ejemplo utiliza la versión 3.7.0:

wget https://pecl.php.net/get/imagick-3.7.0.tgz

Paso 3: Descomprimir el paquete fuente y acceder al directorio

Después de la descarga, descomprima el archivo y cambie al directorio del código fuente:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Paso 4: Preparar el entorno de compilación (phpize)

Dentro del directorio fuente, use la herramienta phpize correspondiente a la versión de PHP seleccionada. Recuerde utilizar la ruta completa adecuada a su objetivo PHP. Suponiendo PHP 8.3 y que tiene la variable de entorno SERVBAY_PACKAGE_FULL_PATH configurada:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

Si se ejecuta correctamente, se generará el script configure y demás archivos de construcción necesarios, mostrando información sobre el entorno de compilación.

Paso 5: Configuración de opciones de compilación

Ejecute el script configure para preparar la compilación, especificando el php-config correspondiente a su versión de PHP mediante el parámetro --with-php-config:

./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

El script buscará dependencias como la biblioteca y cabeceras de ImageMagick, generando el Makefile. Si aparecen errores, normalmente se deben a dependencias no instaladas o rutas incorrectas.

Paso 6: Compilar e instalar el módulo

Una vez creado el Makefile, compile el módulo con make y luego instálelo en el directorio de extensiones PHP usando make install. La variable ${CPU_NUMBER} puede acelerar el proceso aprovechando todos los núcleos disponibles:

make -j ${CPU_NUMBER}
make install

make install colocará la extensión en:

• macOS: /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/
• Windows: C:\ServBay\package\php\8.3\current\lib\php\extensions\no-debug-non-zts-YYYYMMDD\

La ruta exacta depende de la versión de PHP y la configuración.

Paso 7: Activar el módulo

Una vez instalado el módulo, debe habilitarlo en la configuración de PHP correspondiente. ServBay permite hacerlo gráficamente:

• Abra la aplicación ServBay
• En el menú lateral vaya a Lenguajes - PHP - PHP 8.3
• Seleccione la pestaña PHP a la derecha, desplácese hasta el final, y en "Parámetros adicionales" añada extension=imagick.so
• Pulse Guardar; el proceso PHP se reiniciará automáticamente cargando el nuevo módulo

Paso 8: Verificar la carga del módulo

Tras activar el módulo, reinicie el paquete PHP desde la interfaz de ServBay o usando su utilidad de línea de comandos (consulte la documentación para los comandos exactos).

Para comprobar que el módulo se ha cargado, ejecute:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick

Esto mostrará imagick en la lista si se ha cargado correctamente.

Para una verificación más detallada, cree un archivo PHP (por ejemplo, info.php) en el directorio raíz web con el siguiente contenido: <?php phpinfo(); ?>. Las ubicaciones por defecto del directorio web son:

• macOS: /Applications/ServBay/www
• Windows: C:\ServBay\www

Acceda al archivo vía navegador, por ejemplo: http://localhost/info.php o mediante su dominio configurado en ServBay. En la página de salida de phpinfo(), busque "imagick" para comprobar que está habilitado y ver sus detalles.

Compilación de los módulos PHP sqlsrv y pdo_sqlsrv

Los módulos sqlsrv y pdo_sqlsrv son extensiones oficiales para conectar y manejar bases de datos Microsoft SQL Server desde PHP, basados en el driver ODBC proporcionado por Microsoft. Si necesita conectarse a SQL Server desde PHP en ServBay, es imprescindible compilar e instalar estos módulos. Siga estos pasos:

Advertencia: Requisito importante

Antes de compilar e instalar el módulo sqlsrv, es imprescindible instalar previamente el driver ODBC oficial de Microsoft para SQL Server y las herramientas asociadas. ServBay no incluye estos paquetes; deben instalarse manualmente.

macOS

Utilice Homebrew para instalar las dependencias. Si no tiene Homebrew, consulte el sitio oficial.

Los comandos de instalación son (posiblemente requiera aceptar el acuerdo de licencia, usando HOMEBREW_ACCEPT_EULA=Y):

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

Las dependencias suelen instalarse en /opt/homebrew/ (Mac Apple Silicon) o /usr/local/ (Mac Intel). Asegure que las rutas sean correctas al compilar.

Windows

Descargue e instale el driver ODBC desde la página oficial de Microsoft:

• Descargue el paquete adecuado para su sistema
• Instálelo y asegúrese de que el sistema lo detecte correctamente

Antes de compilar sqlsrv, asegure que todas las dependencias estén funcionando.

Nota

Tanto sqlsrv como pdo_sqlsrv son módulos diferentes y deben compilarse por separado, pero los pasos son casi idénticos. El ejemplo mostrará el proceso con sqlsrv.

Paso 1: Instalar Microsoft ODBC Driver y herramientas

(Vea las instrucciones anteriores para instalar msodbcsql18 y mssql-tools18 con Homebrew.)

Paso 2: Obtener el código fuente del módulo sqlsrv

Descargue los paquetes fuente de sqlsrv y pdo_sqlsrv desde PECL. Vaya a la página de sqlsrv en PECL para obtener la versión necesaria. En el ejemplo se usa la versión 5.12.0:

wget https://pecl.php.net/get/sqlsrv-5.12.0.tgz  # sqlsrv
wget https://pecl.php.net/get/pdo_sqlsrv-5.12.0.tgz  # pdo_sqlsrv

Paso 3: Descomprimir los paquetes fuente y acceder al directorio

Descomprima el paquete y acceda al directorio de código fuente:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# Para pdo_sqlsrv repita el proceso; aquí seguimos con sqlsrv.

Paso 4: Preparar el entorno de compilación (phpize)

En el directorio del módulo, utilice el phpize correspondiente para preparar la compilación. Ejemplo para PHP 8.3:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

Paso 5: Configuración de opciones de compilación (incluyendo rutas de dependencias)

Como sqlsrv depende de los drivers ODBC instalados por Homebrew y UnixODBC, antes de ejecutar configure debe establecer variables de entorno para indicar las rutas correctas a librerías y archivos de cabecera. Ejemplo si Homebrew está en /opt/homebrew:

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # Añada /opt/homebrew/include para asegurar encontrar todas las cabeceras
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: directorio de búsqueda de librerías para el linker.
• CPPFLAGS: directorios para cabeceras C/C++. ${CPPFLAGS} y ${LDFLAGS} mantienen cualquier flag adicional del entorno ServBay.

Paso 6: Compilar e instalar el módulo

Tras generar el Makefile, compile e instale el módulo:

make -j ${CPU_NUMBER}
make install

Los archivos .so resultantes (sqlsrv.so, pdo_sqlsrv.so si compila ambos) se copiarán al directorio de extensiones PHP de ServBay correspondiente.

Paso 7: Activar el módulo

Después de instalar el módulo, habilítelo en la configuración de PHP usando la interfaz gráfica de ServBay:

• Abra la aplicación ServBay
• Vaya a Lenguajes - PHP - PHP 8.3
• En la pestaña PHP, al final de la página, en “Parámetros adicionales”, añada extension=sqlsrv.so y extension=pdo_sqlsrv.so
• Presione Guardar; PHP se reiniciará automáticamente para cargar los nuevos módulos

Paso 8: Verificar la carga del módulo

Tras activar los módulos, reinicie el paquete PHP relevante.

Compruebe desde la terminal:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep sqlsrv
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep pdo_sqlsrv

Si se han cargado correctamente, verá sqlsrv y pdo_sqlsrv en la salida. También puede verificar el estado y detalles del módulo con phpinfo().

Preguntas frecuentes (FAQ)

• P: ¿Durante la compilación aparece el error "Cannot find autoconf" o similares?
  • R: Este error suele indicar que el entorno de compilación de ServBay no se ha inicializado correctamente. Revise la sección “Requisitos previos” y siga la documentación de Compilación secundaria en ServBay asegurándose de que todas las herramientas (autoconf, automake, libtool, etc.) estén instaladas y referenciadas mediante las variables de entorno. Normalmente, ejecutar el script de inicialización de ServBay y reiniciar la terminal soluciona el problema.
• P: ¿El script configure falla indicando que falta alguna biblioteca o archivo de cabecera?
  • R: Significa que falta alguna dependencia o no es localizada correctamente.
    • Para imagick: asegúrese de que ImageMagick y sus cabeceras estén instalados, por ejemplo con Homebrew: brew install imagemagick.
    • Para sqlsrv: compruebe que el driver ODBC de Microsoft (msodbcsql18) y mssql-tools18 estén instalados según el requisito previo. Antes de ejecutar ./configure, asegúrese de haber definido bien las variables LDFLAGS y CPPFLAGS con las rutas correctas (por ejemplo /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
    • Compruebe que la configuración del entorno de compilación de ServBay incluya las rutas de Homebrew o agregue manualmente el directorio bin de Homebrew al PATH si fuera necesario.
• P: ¿Fallos durante make o make install?
  • R: Las causas habituales:
    • Faltan dependencias: Consulte el mensaje de error y instale la dependencia correspondiente.
    • Parámetros incorrectos: Compruebe los argumentos de configure, especialmente el valor de --with-php-config.
    • Problemas de permisos: Si recibe errores de permisos al copiar archivos, pruebe sudo make install, pero extreme las precauciones.
    • Código fuente corrupto: Verifique que el paquete del módulo esté íntegro.
• P: ¿El archivo .so está en el directorio de extensiones y está activado en el .ini, pero no aparece en php -m o phpinfo()?
  • R:
    • Lo más común: Olvidó reiniciar el paquete PHP en ServBay. Tras modificar el archivo .ini, reinicie el servicio PHP desde el panel de ServBay o con su herramienta de línea de comandos. No basta con recargar la web o reiniciar el servidor web (Caddy/Nginx); debe reiniciar PHP.
    • Error de sintaxis en .ini: Revise cuidadosamente el contenido (extension=modulename.so).
    • Ruta incorrecta del directorio de extensiones: Compruebe que la directiva extension_dir en el php.ini apunte al directorio adecuado. Use php-config --extension-dir para confirmar la ubicación.
    • Archivo incompatible o corrupto: Recompile el módulo y verifique la compatibilidad de la versión. Consulte los logs de PHP (carpeta logs en la instalación ServBay) si hay errores durante la carga del módulo.

Resumen

Siguiendo los pasos detallados de esta guía, podrá compilar e instalar correctamente módulos PHP personalizados (como imagick y sqlsrv) en su entorno local de ServBay. Los puntos fundamentales son:

1. Inicialice completa y correctamente el entorno de compilación de ServBay: Es la base de cualquier otro procedimiento de compilación.
2. Especifique y utilice la ruta de la versión de PHP adecuada: Cada comando (phpize, php-config) debe apuntar directamente a la versión de PHP objetivo en ServBay.
3. Gestione correctamente las dependencias externas del módulo: Instale los paquetes y herramientas necesarias (ImageMagick, drivers ODBC de Microsoft, etc.) y asegúrese de que los scripts de configuración puedan localizarlas, usando variables de entorno (LDFLAGS, CPPFLAGS) o parámetros.
4. Habilite correctamente el módulo: Edite o cree archivos .ini en el directorio conf.d correspondiente, usando la directiva extension=modulename.so.
5. Reinicie el paquete PHP en ServBay: Es fundamental para aplicar cualquier cambio en la carga de módulos.

ServBay es un entorno de desarrollo local completo y flexible para todo tipo de necesidades. Además de la compilación de módulos PHP, incluye soporte y preintegración para MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust, etc. ServBay incorpora herramientas adicionales como gestión de certificados SSL reales vía ACME, configuración de CORS, copias de seguridad automáticas (incluyendo configuración, web, BBDD, certificados), recuperación de contraseñas root de BBDD, y entornos de CA propios para desarrollo HTTPS local.

Esperamos que esta guía le ayude a ampliar las capacidades de PHP en ServBay y le permita trabajar de forma más eficiente en sus proyectos web. Ante cualquier duda, consulte la documentación oficial de ServBay o busque soporte en la comunidad.