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

ServBay es un potente entorno local de desarrollo web diseñado especialmente para macOS, que integra una amplia variedad de paquetes de software para cubrir las necesidades de los desarrolladores web modernos. Incluye PHP, Node.js, Python, Go, Java, bases de datos como MySQL, PostgreSQL, MongoDB, sistemas de caché como Redis y servidores web como Caddy, Nginx y Apache, todos con soporte multiversión para que puedas adaptar el entorno a tu proyecto según tus requerimientos.

Aunque ServBay ya incluye muchos módulos PHP usados habitualmente, en algunos escenarios de desarrollo podrías necesitar compilar e instalar módulos adicionales para ampliar la funcionalidad de PHP o integrar servicios de terceros específicos.

En este artículo encontrarás una guía paso a paso sobre cómo compilar e instalar módulos personalizados para la versión de PHP que uses en ServBay. Como ejemplo, mostraremos el proceso detallado para compilar el módulo común imagick para procesamiento de imágenes y el módulo del controlador para bases de datos de Microsoft SQL Server sqlsrv, ayudándote a dotar a tu ambiente PHP en ServBay de las características que necesites.

Requisitos previos

Aviso importante

Antes de empezar a compilar cualquier módulo PHP, el paso más importante es inicializar correctamente el entorno de compilación siguiendo la documentación oficial de ServBay y establecer las variables de entorno del sistema de manera adecuada. Este paso es fundamental para compilar con éxito cualquier paquete en ServBay (incluyendo módulos PHP). Si omites o ejecutas mal este paso, seguramente el proceso de compilación fallará, mostrando errores como comandos, librerías o archivos de cabecera no encontrados.

El script de inicialización del entorno de compilación de ServBay configura todas las variables necesarias, como PATH (apuntando a las herramientas internas de compilación de ServBay), SERVBAY_PACKAGE_FULL_PATH (directorio raíz de los paquetes de ServBay) y CPU_NUMBER (para compilación en paralelo con múltiples núcleos). Estas variables son esenciales para los comandos de compilación posteriores.

Asegúrate de seguir los pasos detallados en la documentación: Compilación secundaria en ServBay, y no continúes hasta comprender y realizar correctamente toda la configuración necesaria.

Antes de continuar con la compilación de módulos, verifica que ya has inicializado el entorno de compilación de ServBay correctamente y que las variables de entorno asociadas estén activas en tu terminal actual.

Importancia de especificar la versión de PHP

Una funcionalidad clave de ServBay es permitir instalar y ejecutar múltiples versiones de PHP en un mismo sistema, facilitando el cambio de entorno para distintos proyectos. Sin embargo, al compilar módulos PHP, debes compilar específicamente para la versión de PHP deseada, ya que herramientas como phpize y php-config están vinculadas a la versión de PHP concreta para la que compilarás el módulo.

• phpize: Prepara el entorno de compilación del módulo PHP, leyendo el archivo config.m4 y generando scripts estándar como configure, que es el primer paso para compilar software en C/C++.
• php-config: Proporciona información de configuración detallada de la instalación de esa versión específica de PHP, como rutas de compilador, directorios de inclusión, directorios de librerías y el destino de instalación de extensiones. El script configure lo emplea para garantizar la compilación y vinculación correctas del módulo.

Por tanto, al usar phpize, php-config o cualquier comando relacionado con la compilación PHP, debes indicar la ruta completa del ejecutable para la versión de PHP deseada. Por ejemplo, para compilar un módulo para PHP 8.3 instalado en ServBay, utiliza /Applications/ServBay/package/php/8.3/current/bin/phpize y /Applications/ServBay/package/php/8.3/current/bin/php-config. Seleccionando la ruta y versión correctas, te aseguras de que el módulo resultante sea compatible y evitas errores de compilación o problemas en tiempo de ejecución.

En toda la guía usaremos como ejemplo la versión PHP 8.3 de ServBay. Cuando lo pongas en práctica debes ajustar las rutas a la versión real instalada de PHP en tu ServBay.

Compilar el módulo PHP imagick

El módulo imagick es una extensión muy popular en PHP, basada en la potente librería de línea de comandos ImageMagick, que permite realizar todo tipo de operaciones complejas sobre imágenes: redimensionamiento, recorte, conversiones de formato, marcas de agua, composición y más. Aquí te mostramos detalladamente cómo compilar e instalar imagick para una versión concreta de PHP en ServBay:

Paso 1: Instalar la librería ImageMagick como dependencia

El módulo PHP imagick depende de que ImageMagick esté instalado en el sistema. En macOS, la forma recomendada es usando Homebrew. Si no tienes Homebrew, descárgalo siguiendo la guía de su sitio oficial.

Abre tu terminal y ejecuta:

brew install imagemagick

Paso 2: Descargar el código fuente del módulo imagick

Ahora descarga el código fuente del módulo imagick desde el repositorio oficial de extensiones PHP (PECL). Visita la página de PECL imagick, selecciona la versión que quieras (por lo general, la más reciente y estable) y copia el enlace de descarga. A modo de ejemplo, descargaremos la versión 3.7.0:

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

Paso 3: Extraer el paquete fuente y acceder al directorio

Una vez descargado el paquete, descomprímelo y accede al directorio creado:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

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

Dentro del directorio fuente del módulo, ejecuta la herramienta phpize correspondiente a la versión PHP objetivo — recuerda especificar la ruta completa. Por ejemplo, para PHP 8.3:

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

Si el comando se ejecuta correctamente, generará el script configure y otros archivos necesarios. El terminal mostrará mensajes de que el entorno de compilación está listo.

Paso 5: Configurar las opciones de compilación

Ejecuta el script configure recién generado para definir las opciones de compilación. Es obligatorio especificar la ruta de php-config para tu versión PHP objetivo usando el parámetro --with-php-config:

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

Durante este paso, el script buscará las dependencias (como ImageMagick) y, si todo está correcto, generará el fichero Makefile de compilación. Si encuentras errores, normalmente se deben a dependencias que faltan o rutas incorrectas.

Paso 6: Compilar e instalar el módulo

Con el Makefile ya creado, ejecuta el proceso de compilación con make y después instala el módulo con make install. La variable ${CPU_NUMBER} (definida al inicializar ServBay) permite compilar en paralelo para ahorrar tiempo:

make -j ${CPU_NUMBER}
make install

Esto copiará el fichero generado imagick.so al directorio estándar de extensiones de la versión de PHP correspondiente (por ejemplo, /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/, aunque la ruta concreta depende de la versión/configuración).

Paso 7: Activar el módulo

Después de instalarlo, activa el módulo editando la configuración de tu versión de PHP desde la interfaz gráfica de ServBay:

• Abre la aplicación ServBay.
• Ve al menú de la izquierda: Lenguajes - PHP - PHP 8.3
• En la página de la derecha, selecciona la pestaña PHP, baja hasta “Parámetros extra” e introduce extension=imagick.so
• Haz clic en Guardar para reiniciar el proceso PHP y cargar el módulo nuevo.

Paso 8: Verificar la carga del módulo

Tras habilitar el módulo, debes reiniciar el paquete PHP de ServBay para que la nueva configuración entre en vigor. Esto puede hacerse desde el panel de administrador gráfico de ServBay, buscando el paquete PHP correspondiente y pulsando el botón de reinicio, o con las herramientas de línea de comandos si lo prefieres (consulta la documentación de ServBay para los comandos exactos).

Después del reinicio, puedes verificar desde la terminal si el módulo imagick se ha cargado correctamente:

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

Este comando usa el ejecutable PHP de ServBay especificando la versión y muestra la lista de módulos cargados (-m). Si imagick aparece en la salida, la carga ha sido exitosa.

Para una comprobación más detallada, crea un archivo PHP (por ejemplo, info.php) en el directorio raíz web (por defecto /Applications/ServBay/www) con este contenido:

<?php phpinfo(); ?>

Accede después a http://localhost/info.php o la URL/localhost de tu ServBay en el navegador y busca "imagick" en la página de salida para confirmar que está habilitado, así como su configuración y versión.

Compilar los módulos PHP sqlsrv/pdo_sqlsrv

Los módulos sqlsrv y pdo_sqlsrv son extensiones oficiales de PHP para conectar y operar con bases de datos Microsoft SQL Server, usando el controlador ODBC proporcionado por Microsoft. Si necesitas conectarte a una base de datos SQL Server desde tu entorno PHP en ServBay, deberás instalar estos módulos. Aquí tienes los pasos para compilar e instalar sqlsrv/pdo_sqlsrv en ServBay:

Nota: requisitos previos importantes

Para compilar sqlsrv en macOS, es imprescindible instalar previamente el controlador ODBC de SQL Server de Microsoft (msodbcsql18) y sus herramientas en línea de comandos (mssql-tools18). Estos paquetes no se incluyen en ServBay y requieren instalación manual.

La opción recomendada es instalar estas dependencias utilizando Homebrew. Si no tienes Homebrew, sigue la instalación desde su sitio web oficial.

Para instalar los drivers y herramientas de Microsoft con Homebrew, ejecuta estos comandos (podrías tener que aceptar el acuerdo de licencia usando la variable de entorno 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

Antes de intentar compilar sqlsrv, confirma que estas dependencias se han instalado correctamente. Por defecto, Homebrew instala en /opt/homebrew/ (Mac con Apple Silicon) o en /usr/local/ (Mac Intel). Deberás usar la ruta adecuada en el proceso de compilación.

Consejo

sqlsrv y pdo_sqlsrv son módulos independientes que deben compilarse por separado, pero el procedimiento es similar. En el siguiente ejemplo nos centramos en sqlsrv.

Paso 1: Instalar el driver ODBC de Microsoft y herramientas

(Sigue los pasos explicados arriba para instalar msodbcsql18 y mssql-tools18 usando Homebrew.)

Paso 2: Descargar el código fuente de sqlsrv

Descarga los paquetes fuente de sqlsrv y pdo_sqlsrv desde PECL. Consulta la página de PECL sqlsrv para el enlace a la versión que prefieras. Aquí usamos la versión 5.12.0 como ejemplo:

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 el paquete fuente y acceder al directorio

Descomprime y entra en el directorio del módulo:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# Para pdo_sqlsrv el proceso es igual, aquí seguimos solo con sqlsrv

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

Ejecuta ahora phpize para la versión de PHP adecuada, por ejemplo PHP 8.3:

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

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

Al ejecutar el script configure, es habitual que sqlsrv necesite localizar el driver ODBC y las librerías unixODBC instaladas por Homebrew. Por ello, antes de ejecutar ./configure, establece las variables de entorno LDFLAGS y CPPFLAGS con las rutas de librerías y cabeceras correspondientes, y especifica la ruta de php-config:

Adapta la ruta de Homebrew: para Mac Intel suele ser /usr/local, en Apple Silicon /opt/homebrew. En el ejemplo suponemos /opt/homebrew:

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # Asegura encontrar todos los headers necesarios
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: especifica dónde buscar las librerías al enlazar.
• CPPFLAGS: indica dónde buscar archivos de cabecera (headers).
• Finalmente, el parámetro --with-php-config es imprescindible para identificar la versión de PHP en ServBay.

Paso 6: Compilar e instalar el módulo

Con la configuración lista, compila el módulo e instálalo:

make -j ${CPU_NUMBER}
make install

Esto copiará a la carpeta de extensiones PHP los archivos sqlsrv.so y pdo_sqlsrv.so (si compilas ambos).

Paso 7: Activar el módulo

Para activar el módulo, hazlo desde la interfaz gráfica de ServBay:

• Abre ServBay
• Ve a Lenguajes - PHP - PHP 8.3
• En la pestaña PHP, al final en "Parámetros extra", añade: extension=sqlsrv.so y extension=pdo_sqlsrv.so
• Haz clic en Guardar para que PHP se reinicie y cargue los nuevos módulos.

Paso 8: Verificar la carga del módulo

Tras activar los módulos, no olvides reiniciar el paquete PHP en ServBay para que los cambios surtan efecto.

Verifica desde terminal que los módulos están correctamente cargados:

${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 la carga es correcta, ambos nombres aparecerán en el resultado. También puedes usar la función phpinfo() para comprobar la información de cada módulo en detalle.

Preguntas frecuentes (FAQ)

• P: ¿Obtengo el error "Cannot find autoconf" o similar al compilar?
  • R: Es casi seguro que no has inicializado correctamente el entorno de compilación de ServBay. Revisa la sección “Requisitos previos” al inicio y sigue la guía Compilación secundaria en ServBay para configurar el entorno por completo, asegurando que las herramientas necesarias (autoconf, automake, libtool, etc.) estén instaladas y accesibles en las variables de entorno. Normalmente, ejecutando el script de inicialización y reiniciando el terminal se soluciona.
• P: ¿Error en configure indicando que falta una librería o archivo de cabecera?
  • R: Falta alguna biblioteca del sistema o cabecera, o están instaladas pero no se encuentran:
    • Para imagick, comprueba que has instalado ImageMagick con Homebrew: brew install imagemagick.
    • Para sqlsrv, asegúrate de haber instalado msodbcsql18 y mssql-tools18 con Homebrew. Antes de ejecutar ./configure, revisa que las variables LDFLAGS y CPPFLAGS tienen las rutas correctas (por ejemplo, /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
    • Por último, asegúrate de que el PATH del entorno de compilación de ServBay incluya, en caso necesario, los directorios de Homebrew o añade manualmente el directorio bin de Homebrew al PATH si la dependencia se instaló así.
• P: ¿Falla make o make install?
  • R: Las causas pueden ser varias:
    • No se instalaron los requisitos previos: Consulta el error específico para saber qué fichero o librería falta e instálala.
    • Parámetros incorrectos en configure: Revisa las rutas, especialmente la de --with-php-config para PHP en ServBay.
    • Faltan permisos: make install necesita copiar ficheros a la ruta de extensiones PHP. Si no tienes permisos, puedes probar con sudo make install (usa esta opción con precaución y sabiendo los riesgos).
    • Problema con el código fuente: El archivo descargado podría estar dañado o incompleto; vuelve a descargar la fuente del módulo.
• P: El archivo .so del módulo está en el directorio de extensiones y lo tengo habilitado en el .ini, pero ni php -m ni phpinfo() lo muestran. ¿Por qué?
  • R:
    • Causa más frecuente: No has reiniciado el paquete PHP en ServBay tras el cambio de configuración. Hazlo desde el panel de ServBay o con las herramientas de línea de comandos. Reiniciar solo el servidor web (Nginx/Caddy) no es suficiente.
    • Revisa si hay errores en la sintaxis del .ini (extension=modulename.so).
    • Comprueba si extension_dir en tu php.ini apunta a la carpeta de extensiones PHP de ServBay. Consulta la ruta esperada ejecutando php-config --extension-dir.
    • El archivo del módulo podría estar dañado o no es compatible con esa versión de PHP. Compila de nuevo, asegurando que el proceso sea correcto y los fuentes adecuados. Revisa también el log de errores PHP de ServBay.

Resumen

Siguiendo meticulosamente estos pasos, deberías poder compilar e instalar con éxito módulos PHP personalizados como imagick y sqlsrv en tu entorno local de ServBay para macOS. Las claves del proceso son:

1. Inicializar correctamente el entorno de compilación de ServBay: Es la base para que cualquier compilación funcione.
2. Especificar la ruta y versión correcta de PHP: Siempre usa la ruta absoluta al ejecutar phpize y php-config.
3. Resolver todas las dependencias externas del módulo: Instala librerías y herramientas requeridas (ImageMagick, ODBC de Microsoft, etc.), y asegura que las variables de entorno o los parámetros de ./configure apunten a las rutas correctas.
4. Activar el módulo de forma correcta: Crea o edita el archivo .ini necesario para la versión de PHP objetivo usando extension=modulename.so.
5. Recargar el paquete PHP en ServBay: Así se cargan los módulos recién configurados.

ServBay ofrece mucha flexibilidad y potencia para cubrir todas tus necesidades de desarrollo. Además de la compilación de módulos PHP explicada aquí, ServBay soporta y preinstala tecnologías como MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust, entre otras. Entre sus funciones extra destacan la solicitud automatizada de certificados SSL reales via ACME, configuraciones fáciles de CORS, copias de seguridad automáticas (de configuración, webs, bases de datos y certificados SSL), restablecimiento de la contraseña 'root' de base de datos, así como el uso de ServBay User CA y ServBay Public CA para el desarrollo HTTPS local.

Esperamos que esta guía te ayude a ampliar las capacidades de tu entorno PHP en ServBay y a desarrollar aplicaciones web de forma más eficiente. Si tienes cualquier otro problema, consulta la documentación oficial de ServBay o recurre a la comunidad de soporte.