Guía de Configuración de PHP en ServBay: Ajustando php.ini, PHP-FPM y Módulos de Extensión

ServBay ofrece a los desarrolladores web un entorno local de desarrollo PHP potente y flexible. Dependiendo de las necesidades de tus proyectos, es posible que desees ajustar diferentes configuraciones de PHP, como el límite de memoria, el tamaño máximo de archivos subidos, el nivel de reporte de errores o la activación de módulos de extensión específicos.

Este artículo explica en detalle cómo modificar la configuración de PHP en ServBay. ServBay recomienda y proporciona una interfaz gráfica de usuario (UI) amigable para gestionar estos ajustes. Aunque también es útil conocer la ubicación y estructura de los archivos de configuración subyacentes (como php.ini y php-fpm.conf), se recomienda encarecidamente realizar los cambios desde la UI de ServBay para garantizar la persistencia y compatibilidad de la configuración.

Aviso importante

Por favor, no edites manualmente los archivos de configuración PHP generados por ServBay (ubicados en /Applications/ServBay/etc/php/<version>/ y sus subdirectorios). Estos archivos son gestionados por ServBay y cualquier modificación manual será sobrescrita al actualizar, reiniciar o realizar otras operaciones relacionadas con ServBay. Todos los cambios de configuración deben hacerse a través de la interfaz gráfica de ServBay.

Descripción general

En ServBay, las configuraciones de cada versión de PHP se almacenan en directorios independientes. Por ejemplo, los archivos principales de configuración para PHP 8.3 se encuentran en /Applications/ServBay/etc/php/8.3.

Los archivos clave de configuración son:

• php.ini: Archivo principal de configuración de PHP que afecta tanto al entorno de línea de comandos (CLI) como al entorno web.
• php-fpm.conf: Configuración del gestor de procesos PHP-FPM (FastCGI Process Manager), la cual influye principalmente en el rendimiento y funcionamiento de PHP dentro de servidores web (como Caddy o Nginx).
• conf.d/: Este directorio contiene archivos de configuración individual (archivos .ini) para cada módulo de extensión de PHP, como xdebug.ini, opcache.ini, etc.

Aunque estos archivos están presentes, ServBay ofrece un método mucho más seguro y cómodo para modificar sus parámetros.

Configuración a través de la interfaz de usuario de ServBay (recomendado)

ServBay proporciona una interfaz gráfica intuitiva que te permite modificar directamente todas las variables de configuración de PHP. Al guardar los cambios desde la UI, ServBay los aplica automáticamente y, cuando es necesario (generalmente de forma automática), reinicia los servicios PHP —sin necesidad de editar archivos manualmente o usar la terminal.

Para acceder a la configuración de PHP:

1. Abre la ventana principal de ServBay.
2. En la barra de navegación izquierda, haz clic en Lenguajes.
3. En la lista de lenguajes de desarrollo, localiza y selecciona la versión de PHP que deseas configurar (por ejemplo, haz clic en PHP 8.3).
4. El panel derecho mostrará toda la información y opciones de configuración para la versión de PHP seleccionada.

A continuación tienes un ejemplo típico de la interfaz de ajustes de PHP:

La interfaz suele dividirse en tres secciones principales, correspondientes a la configuración de PHP-FPM, PHP (php.ini) y los módulos de extensión de PHP. A continuación se detalla cada una de ellas.

Configuración de PHP-FPM

Consejo

Los ajustes en php-fpm.conf influyen principalmente en el comportamiento de PHP bajo servidores web. Los parámetros que se configuren en esta sección desde la UI de ServBay tendrán prioridad (sobrescribirán) sobre los correspondientes en php.ini, pero solo afectarán las peticiones web. Estos ajustes no afectan la ejecución de PHP desde la línea de comandos (CLI).

El servicio web integrado en ServBay (Caddy o Nginx) se comunica con PHP a través de PHP-FPM. La interfaz de configuración de PHP-FPM en ServBay te permite modificar varios parámetros que influyen directamente en el rendimiento y la estabilidad del entorno web, como:

• Gestión de procesos (pm): Controla cómo PHP-FPM genera y administra los procesos de trabajo (por ejemplo, dynamic, static).
• Cantidad de procesos (pm.max_children, pm.start_servers, etc.): Define el número máximo de procesos hijo, procesos iniciales, etc., afectando la capacidad de concurrencia.
• Límite de memoria (memory_limit): El valor configurado aquí sobrescribe el de php.ini y solo afecta las peticiones web.
• Logs y errores: Determina la ubicación del archivo de logs, el nivel de errores y si se muestran errores en el navegador.

Por ejemplo, si quieres aumentar el límite de memoria PHP en el entorno web de su valor por defecto (como 64M o 128M) a 1G, solo tienes que localizar la opción memory_limit en la configuración de PHP-FPM en ServBay, seleccionar 1G en el desplegable y guardar los cambios. Este ajuste solamente afectará a los scripts PHP accedidos desde el servidor web; los scripts ejecutados vía CLI seguirán sujetos al límite definido en php.ini.

Ejemplo comparativo: Si el memory_limit está establecido en 512M en php.ini, pero en la configuración de PHP-FPM está en 128M:

• Los scripts PHP ejecutados en CLI tendrán un límite de 512M.
• Los scripts PHP ejecutados vía web tendrán un límite de 128M.

Configuración de php.ini

Consejo

Los ajustes en php.ini son globales y afectan tanto al entorno CLI como al entorno web de PHP. Sin embargo, como se ha explicado antes, cualquier valor equivalente configurado en PHP-FPM sobrescribirá el de php.ini únicamente para el entorno web.

La sección de configuración PHP en la UI de ServBay corresponde a los parámetros principales del archivo php.ini. Aquí puedes modificar una gran variedad de ajustes generales del entorno de ejecución de PHP, por ejemplo:

• post_max_size: Límite máximo de datos enviados por POST.
• upload_max_filesize: Tamaño máximo de archivos permitidos para carga.
• date.timezone: Zona horaria predeterminada utilizada por PHP.
• display_errors / error_reporting: Controla si los errores se muestran en la página y el nivel de reporte de errores.
• max_execution_time: Tiempo máximo permitido de ejecución de un script (en segundos).
• disable_functions / disable_classes: Desactiva funciones o clases específicas de PHP para mejorar la seguridad.
• open_basedir: Limita los caminos del sistema de archivos accesibles por PHP. Se recomienda almacenar todos los proyectos web en el directorio raíz predeterminado de ServBay /Applications/ServBay/www para así poder especificar fácilmente ese directorio al ajustar open_basedir sin tener que listar múltiples rutas.

Puedes modificar estos y otros parámetros frecuentes de php.ini directamente desde la UI de ServBay.

Para una descripción completa de todos los campos de configuración de php.ini, consulta la documentación oficial de PHP: PHP Runtime Configuration.

Configuración de Módulos de Extensión PHP

ServBay incluye de serie muchos de los módulos de extensión PHP más comunes, abarcando áreas como conexiones a bases de datos, cachés, depuración, soporte para frameworks, entre otros. La UI de ServBay facilita la activación, desactivación y configuración específica de cada módulo según tus necesidades.

Entre los módulos soportados por ServBay destacan —pero no se limitan a— xDebug, OPcache, ImageMagick, Redis, MongoDB, Phalcon, Swoole, etc. También hay soporte para numerosos motores de base de datos (MySQL, PostgreSQL, MongoDB), sistemas de colas de mensajes, almacenamiento en caché, etc.

La gestión de extensiones es muy sencilla:

1. En la interfaz de configuración de PHP de ServBay, accede a la pestaña "Extensiones" o similar.
2. Localiza el módulo de extensión deseado (por ejemplo, xdebug).
3. Activa o desactiva el módulo usando el interruptor correspondiente.
4. Para módulos con parámetros adicionales (como xDebug), puedes configurar opciones específicas directamente desde la interfaz (por ejemplo, xdebug.mode, xdebug.client_port, etc.).
5. Guarda los cambios para aplicarlos.

Para consultar la lista completa y más información sobre los módulos de extensión compatibles, dirígete a la sección Lista de extensiones PHP de la documentación de ServBay (asegúrate de consultar la versión documentada más reciente).

Comprender la estructura de los archivos de configuración de PHP (no recomendado editar manualmente)

Aunque es altamente recomendable usar la UI de ServBay para gestionar la configuración, comprender la ubicación y el formato de los archivos de configuración ayuda a entender cómo funciona PHP en profundidad.

Los archivos de configuración generados por ServBay se encuentran en /Applications/ServBay/etc/php/<version>/:

• php.ini: Archivo principal de configuración.
• php-fpm.conf: Configuración de PHP-FPM (gestor de procesos).
• conf.d/: Carpeta donde se alojan los archivos .ini de cada módulo de extensión.

Ejemplo de estructura del archivo php.ini

El archivo php.ini usa formato INI. Aquí tienes ejemplos de algunos parámetros comunes en el archivo:

; Modificar el límite de memoria
memory_limit = 256M

; Cambiar el tamaño máximo permitido para subida de archivos
upload_max_filesize = 50M
post_max_size = 50M

; Configuración de la zona horaria
date.timezone = "Asia/Shanghai" ; O bien "UTC", "America/New_York", etc., ajústalo según tu necesidad

; Mostrar errores (¡solo para entornos de desarrollo!)
display_errors = On
error_reporting = E_ALL

; Modificar el tiempo máximo de ejecución
max_execution_time = 300

; Limitar rutas accesibles (ejemplo)
; open_basedir = /Applications/ServBay/www/:/tmp/

Ejemplo de estructura del archivo php-fpm.conf

El archivo de configuración php-fpm.conf incluye ajustes globales y de pools (grupos de procesos). ServBay suele crear un pool por defecto llamado www.

[global]
; Ruta para el log de errores global
error_log = /Applications/ServBay/logs/php/8.3/errors.log

[www]
; Dirección y puerto de escucha o archivo socket
listen = /Applications/ServBay/tmp/php-cgi-8.3.sock
listen.backlog = -1
listen.allowed_clients = 127.0.0.1

; Usuario y grupo (habitualmente el usuario actual)
; user = servbay-demo
; group = staff

; Gestor de procesos (static, dynamic, ondemand)
pm = dynamic
pm.max_children = 10       ; Número máximo de procesos hijo
pm.start_servers = 2       ; Número de procesos al iniciar
pm.min_spare_servers = 1   ; Procesos en espera mínimos
pm.max_spare_servers = 6   ; Procesos en espera máximos
pm.max_requests = 1024     ; Número máximo de peticiones por proceso antes de reinicio

; Activa el log de peticiones lentas (registro si la petición tarda más de request_slowlog_timeout)
request_slowlog_timeout = 5s
slowlog = /Applications/ServBay/logs/php/8.3/slow.log

; Configuración php que sobrescribe la de php.ini (ejemplo)
; php_admin_value[memory_limit] = 128M
; php_admin_flag[display_errors] = on

Ejemplo de configuración de carga de módulos PHP (conf.d/)

Los archivos .ini en la carpeta conf.d/ sirven para cargar y ajustar módulos de extensión concretos. Por ejemplo, el archivo xdebug.ini podría verse así:

[Xdebug]
; Cargar la extensión Xdebug
zend_extension = xdebug.so

; Modo de Xdebug (debug, develop, profile, trace, coverage)
xdebug.mode=debug,develop

; Método de inicio de la depuración (yes, trigger, develop)
; yes: siempre inicia
; trigger: bajo petición específica (por parámetro GET/POST o cookie)
; develop: solo funciones auxiliares para desarrollo (como stack trace)
xdebug.start_with_request=yes

; Host y puerto cliente para conectar con un IDE
xdebug.client_host=localhost
xdebug.client_port=39083

; Ruta del log de Xdebug
xdebug.log=/Applications/ServBay/logs/xdebug/8.3/xdebug.log

Reiteramos: aunque puedes encontrar estos archivos, no debes editarlos manualmente. Haz los ajustes desde la interfaz de ServBay.

Aplicar los cambios: reiniciar el servicio PHP

Tras modificar la configuración desde la UI de ServBay, normalmente los cambios se aplican de forma automática. En determinados casos, puede ser necesario reiniciar el servicio PHP correspondiente para que todo funcione según lo esperado.

Puedes reiniciar el servicio PHP de dos maneras:

Reinicio desde la interfaz gráfica de ServBay

1. Abre la ventana principal de ServBay.
2. En la barra lateral izquierda, haz clic en Paquetes.
3. Localiza la versión de PHP cuyo ajuste has modificado.
4. Haz clic en el botón de reinicio junto a la versión de PHP (usualmente un icono de flecha circular).

Reinicio por línea de comandos usando servbayctl

Si prefieres usar la terminal, puedes aprovechar la utilidad servbayctl que ofrece ServBay para gestionar servicios, incluyendo el reinicio de una versión específica de PHP.

Abre la aplicación de Terminal y ejecuta (sustituye 8.3 por la versión de PHP que desees reiniciar):

servbayctl restart php 8.3

Esto reiniciará el proceso PHP-FPM de la versión indicada para que los nuevos ajustes entren en vigor.

Preguntas Frecuentes (FAQ)

• P: He editado manualmente el archivo php.ini, ¿por qué mis cambios no tienen efecto o desaparecen?

  • R: ServBay se encarga de gestionar y generar los archivos de configuración de sus paquetes. Cualquier cambio manual podría ser sobrescrito durante actualizaciones, reinicios de servicios u otras operaciones internas. Es fundamental usar la interfaz gráfica de ServBay, ya que este es el método recomendado y permanente.

• P: ¿Cómo aumento el límite de memoria de PHP o el tamaño máximo de carga de archivos?

  • R: Abre la UI de ServBay y navega a Lenguajes -> selecciona tu versión de PHP. Ajusta el memory_limit en la configuración de PHP-FPM (afecta el entorno web), y los valores upload_max_filesize y post_max_size en la configuración de php.ini (afecta entornos globales; en la web puede ser sobrescrito por la configuración FPM). Guarda los cambios y reinicia el servicio PHP.

• P: ¿Cómo habilito o configuro Xdebug?

  • R: En la UI de ServBay, ve a Lenguajes -> selecciona tu versión de PHP. En la sección de módulos de extensión, localiza xdebug, actívalo y personaliza los parámetros que necesites (xdebug.mode, xdebug.client_host, xdebug.client_port, etc.). Guarda y reinicia el servicio PHP.

• P: ¿Cuál es la diferencia entre php.ini y la configuración PHP-FPM? ¿Cuál debo modificar?

  • R: php.ini es el archivo de configuración global de PHP y afecta tanto al entorno CLI como al web. La configuración PHP-FPM (php-fpm.conf) corresponde específicamente a la ejecución PHP bajo servidores web, y cualquier variable con nombre equivalente tendrá preferencia sobre la de php.ini en el entorno web. Si necesitas modificar parámetros para peticiones web (como memoria, tiempo de ejecución, visualización de errores), revisa primero PHP-FPM; si tu cambio afecta el CLI o todo el entorno, ajusta php.ini. ServBay separa claramente estas opciones en la interfaz.

Resumen

ServBay facilita con su interfaz gráfica la gestión segura y sencilla de todas las configuraciones PHP: desde php.ini, pasando por PHP-FPM, hasta los módulos de extensión. Modifica los ajustes desde la UI, guarda y reinicia el servicio PHP para que tu entorno de desarrollo funcione exactamente como necesitas. Aunque conocer la ubicación de los archivos de configuración de bajo nivel ayuda a entender su funcionamiento, siempre realiza los cambios desde la UI de ServBay para evitar sobrescrituras. Gracias a la flexibilidad y potencia de ServBay, puedes personalizar sin problemas tu entorno PHP para cualquier proyecto.