Gestión de versiones PHP en ServBay: Guía de configuración para CLI y sitios web

ServBay es una potente herramienta de entorno de desarrollo web local compatible con macOS y Windows, que admite múltiples lenguajes de programación y bases de datos. En este artículo se explica en detalle cómo gestionar de forma flexible las distintas versiones de PHP en ServBay para cada proyecto, tanto al ejecutar scripts desde la línea de comandos como al prestar servicios a sitios web específicos. Dominar el sistema de gestión de versiones PHP de ServBay te permite aumentar notablemente tu productividad y asegurar el aislamiento y estabilidad del entorno de tus proyectos.

1. Entorno de línea de comandos: gestión de versión PHP por proyecto a través de .servbay.config

Crear un archivo .servbay.config en la raíz de tu proyecto permite a los desarrolladores asignar de forma independiente la versión de PHP utilizada por cada proyecto desde la terminal. ServBay carga automáticamente el entorno PHP correspondiente según la carpeta actual de la terminal, logrando así aislamiento de versión entre proyectos y evitando conflictos con configuraciones globales.

1.1 Propósito y funcionamiento de .servbay.config

• Control de versión por proyecto: ServBay te permite instalar y ejecutar múltiples versiones de PHP simultáneamente, desde PHP 5.6 hasta la más reciente estable o de desarrollo. Mediante .servbay.config, puedes especificar con precisión la versión requerida para cada proyecto.
• Cambio transparente: Al navegar a un directorio que contiene .servbay.config mediante el comando cd en la terminal, ServBay detecta el archivo y modifica temporalmente las variables de entorno de la sesión actual (principalmente PATH), de modo que comandos como php o composer utilicen la versión de PHP elegida. Al salir de ese directorio, el entorno se restablece al valor predeterminado global configurado en ServBay, sin afectar el entorno del sistema.

1.2 Cómo configurarlo

Crea un archivo llamado .servbay.config en la raíz de tu proyecto y agrega lo siguiente para definir la versión de PHP:

# Especifica la versión de PHP para este proyecto (ejemplo: PHP 8.3)
PHP_VERSION=8.3

# Si tu proyecto depende de una versión específica de Node.js, también puedes definirla (ejemplo: Node.js 20)
# NODE_VERSION=20

• El valor de PHP_VERSION debe coincidir con los identificadores de versiones instaladas en ServBay, normalmente el número principal o principal/secundario como 7.4, 8.1, 8.3, 8.5, etc. Asegúrate de que la versión elegida esté instalada y habilitada en ServBay.
• La configuración de NODE_VERSION es similar, y sirve para definir la versión de Node.js que necesita tu proyecto.

Verificación de la configuración:

Abre una terminal en el directorio de tu proyecto que contenga .servbay.config y ejecuta los siguientes comandos para comprobar que todo está correcto:

$ pwd # Verifica que estás en la raíz del proyecto
$ php -v  # Comprueba que la salida refleje la versión de PHP configurada (por ejemplo: PHP 8.3.x)
$ composer install  # La instalación de dependencias se realiza usando la versión de PHP activa

Si después de modificar .servbay.config no ves el cambio de versión, prueba cerrando y abriendo la terminal, o ejecuta cd . para forzar la recarga de la configuración por parte de ServBay.

1.3 Recomendaciones y consejos avanzados

• Compatibilidad de versiones: Si al ejecutar comandos del proyecto encuentras errores como "Class not found" o "Call to undefined function", revisa primero los requisitos de versión definidos en las dependencias (composer.json) y confirma que la versión PHP asignada es compatible con el proyecto y sus dependencias. Algunos proyectos antiguos pueden depender de funciones o extensiones ya eliminadas en versiones recientes (por ejemplo, PHP 7.2 retiró la extensión mcrypt).
• Valor predeterminado global: Si ni el directorio actual ni sus superiores contienen un archivo .servbay.config, ServBay empleará la versión PHP global configurada desde la interfaz gráfica, en “Ajustes”.
• Colaboración de servicios: Además de PHP, .servbay.config permite definir la versión de Node.js (NODE_VERSION). Esto resulta útil para proyectos que usan PHP en el backend, y Node.js como herramienta frontend de construcción (Webpack, Vite, etc.).

1.4 Ejemplo de funcionamiento

A continuación, se muestra un ejemplo demostrativo de cómo .servbay.config permite cambiar automáticamente la versión de PHP al moverse entre diferentes proyectos:

Descripción de la imagen: En ServBay, al entrar en directorios con diferentes archivos .servbay.config y ejecutar php -v, la terminal cambia automáticamente a la versión de PHP indicada en el archivo.

2. Entorno de sitio web: gestión de versión PHP mediante la interfaz gráfica de ServBay

La interfaz gráfica de ServBay facilita la asignación de versiones PHP independientes para cada sitio web. La versión PHP del entorno web es completamente independiente de la versión CLI, y puedes ajustarla según lo que requiera tu sitio.

2.1 Proceso de configuración

1. Abre la interfaz de ServBay: Inicia la aplicación ServBay.
2. Accede a gestión de sitios: Haz clic en la pestaña Sitios (Websites) del menú lateral izquierdo.
3. Agrega o edita un sitio:
   • Para agregar un nuevo sitio, haz clic en el botón + situado en la parte inferior izquierda.
   • Para editar un sitio existente, selecciónalo y accede a sus opciones.
4. Configura las propiedades del sitio:
   • Root Directory (Raíz del sitio): Especifica la carpeta donde están los archivos de tu sitio. Se recomienda usar subcarpetas bajo la ruta predeterminada /Applications/ServBay/www/, por ejemplo: /Applications/ServBay/www/tu-sitio/public (ideal para proyectos Laravel o Symfony).
   • Domain (Dominio): Define el dominio de desarrollo que usarás para acceder a tu sitio, como tu-sitio.servbay.demo. ServBay se encarga de configurar automáticamente la resolución DNS local y generar certificados HTTPS (por CA de usuario ServBay o pública), simplificando el desarrollo y pruebas locales.
   • PHP Version (Versión PHP): Elige en el menú desplegable la versión de PHP que debe usar el sitio. ServBay muestra todas las versiones instaladas y habilitadas, como 7.4, 8.1, 8.3, 8.5, etc.
5. Guarda la configuración: Haz clic en el botón de guardar al completar los ajustes. ServBay aplicará los cambios automáticamente; en algunos casos será necesario recargar o reiniciar el servidor web y los procesos PHP-FPM asociados.

2.2 Detalles técnicos y ventajas

• Aislamiento de servicios: ServBay ejecuta la versión PHP asignada a cada sitio mediante procesos PHP-FPM independientes. Así, los distintos sitios web se mantienen aislados; los errores o pérdidas de memoria de un sitio no afectan a los demás.
• Optimización de rendimiento: Los paquetes de ServBay (incluyendo todas las versiones de PHP) están optimizados tanto para ARM64 (Apple Silicon) como para X86_64, asegurando un desempeño excelente en cualquier hardware.
• Depuración de errores:
  • Revisa el log de errores PHP en /Applications/ServBay/var/log/php/php_error.log.
  • Verifica el estado de los procesos PHP-FPM usando la herramienta de línea de comandos servbayctl, por ejemplo, servbayctl status php 8.3.

2.3 Integración con servidores web y bases de datos

ServBay ofrece gran flexibilidad para que adaptes el servidor web y la base de datos a las necesidades de cada proyecto:

• Compatibilidad con servidores Web: A partir de ServBay 1.7.0, puedes cambiar el servidor web utilizado por cada sitio, con soporte para Apache, Nginx y Caddy, todos perfectamente integrados con los procesos PHP-FPM gestionados por ServBay.
• Gestión de bases de datos: ServBay permite instalar y administrar múltiples versiones de MySQL, MariaDB, PostgreSQL, MongoDB y Redis. Puedes conectar tu proyecto al servicio de base de datos que corresponda, tanto desde la configuración del sitio como directamente en el código del proyecto. Así puedes responder fácilmente a requerimientos como usar MariaDB 11.x para ciertos proyectos Laravel.

3. Colaboración entre entornos y mejores prácticas

Comprender la independencia y la configuración de las versiones PHP en el entorno de línea de comandos y el entorno web te ayuda a elegir la mejor opción para cada escenario:

Escenario	Configuración en CLI (.servbay.config)	Configuración en entorno web (GUI de ServBay)	Notas
Mantenimiento de sistemas heredados	Define PHP_VERSION=5.6 en la raíz del proyecto	Selecciona PHP 5.6 en la configuración del sitio	Asegúrate de que la versión y las extensiones requeridas estén instaladas.
Desarrollo de nuevos proyectos (ej: Laravel 11)	Configura PHP_VERSION=8.3 (o superior), y si es necesario, NODE_VERSION=20	Da de alta un nuevo sitio con carpeta raíz apuntando a public, usa PHP 8.3+, define el dominio y habilita HTTPS	Recomienda mantener versiones coherentes entre CLI y entorno web para evitar conflictos.
Pruebas con versiones futuras de PHP	Define PHP_VERSION=8.5 en la raíz del proyecto	Configura un sitio de pruebas con PHP 8.5	Útil para verificar la compatibilidad de tus proyectos con PHP en desarrollo.
Ejecución de Composer	Verifica que .servbay.config especifique la versión correcta	N/A (Composer se ejecuta principalmente vía CLI)	Composer usará la versión de PHP activa según el entorno de la terminal.

Consideraciones

• Diferencias entre CLI y entorno web: Aunque uses el mismo número de versión PHP, la configuración y los módulos activos pueden variar entre el entorno CLI y el entorno web (PHP-FPM). Por ejemplo, la extensión opcache suele estar habilitada en PHP-FPM para mejorar el rendimiento, pero puede estar desactivada por defecto en CLI. Si detectas comportamientos distintos, revisa el archivo php.ini de cada versión en ServBay y verifica los módulos cargados.
• Mantén ServBay Runtime actualizado: Asegúrate de tener la versión más reciente de la aplicación ServBay y su Runtime, ya que el equipo actualiza regularmente los paquetes incluidos, nuevas versiones de PHP y parches de seguridad. Actualizar ServBay también actualiza el Runtime con las últimas mejoras y funcionalidades.

Preguntas Frecuentes (FAQ)

¿Qué hacer si hay conflicto de versiones PHP entre CLI y el entorno web?

La versión PHP usada en la línea de comandos (gestionada por .servbay.config) y la utilizada por el sitio web (configurada mediante la GUI de ServBay) son independientes. .servbay.config sólo modifica el comando php en la terminal de acuerdo a lo definido para esa sesión; la configuración del sitio determina qué versión PHP-FPM procesa las peticiones web para ese sitio en concreto. No existe conflicto directo entre ambas. Puedes utilizar una versión para comandos CLI (p.ej. Composer, Artisan), y otra distinta en el entorno web, aunque no es lo más recomendable; para evitar problemas y asegurar coherencia entre desarrollo y producción, mantén preferentemente las mismas versiones en ambos entornos.

Conclusión

ServBay, mediante los archivos .servbay.config y su intuitiva interfaz gráfica, te ofrece un sistema flexible y eficaz para gestionar distintas versiones de PHP. Tanto si trabajas en proyectos heredados que requieren versiones antiguas, como si desarrollas aplicaciones con las últimas novedades de PHP, ServBay facilita la configuración y el aislamiento de cada entorno. Aprovecha estas funciones para asegurar que tu ambiente local de desarrollo se corresponde con el de producción, aumentando tu productividad y la estabilidad de tus proyectos.