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 archivoconfig.m4
y generando el script estándarconfigure
, 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 scriptconfigure
usaphp-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:
bash
brew install imagemagick
1
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
:
bash
wget https://pecl.php.net/get/imagick-3.7.0.tgz
1
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:
bash
tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0
1
2
2
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:
bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize
1
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
:
bash
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config
1
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:
bash
make -j ${CPU_NUMBER}
make install
1
2
2
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ñadaextension=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:
bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick
1
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
):
bash
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18
1
2
3
2
3
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
:
bash
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
1
2
2
Paso 3: Descomprimir los paquetes fuente y acceder al directorio
Descomprima el paquete y acceda al directorio de código fuente:
bash
tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0
# Para pdo_sqlsrv repita el proceso; aquí seguimos con sqlsrv.
1
2
3
4
2
3
4
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:
bash
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize
1
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
:
bash
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
1
2
3
2
3
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:
bash
make -j ${CPU_NUMBER}
make install
1
2
2
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ñadaextension=sqlsrv.so
yextension=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:
bash
${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
1
2
2
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
) ymssql-tools18
estén instalados según el requisito previo. Antes de ejecutar./configure
, asegúrese de haber definido bien las variablesLDFLAGS
yCPPFLAGS
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 alPATH
si fuera necesario.
- Para
- R: Significa que falta alguna dependencia o no es localizada correctamente.
- P: ¿Fallos durante
make
omake 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.
- R: Las causas habituales:
- P: ¿El archivo
.so
está en el directorio de extensiones y está activado en el.ini
, pero no aparece enphp -m
ophpinfo()
?- 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 elphp.ini
apunte al directorio adecuado. Usephp-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.
- Lo más común: Olvidó reiniciar el paquete PHP en ServBay. Tras modificar el archivo
- R:
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:
- Inicialice completa y correctamente el entorno de compilación de ServBay: Es la base de cualquier otro procedimiento de compilación.
- 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. - 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. - Habilite correctamente el módulo: Edite o cree archivos
.ini
en el directorioconf.d
correspondiente, usando la directivaextension=modulename.so
. - 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.