Cómo usar el archivo .user.ini en ServBay: Guía de configuración local de PHP

ServBay es un potente entorno local de desarrollo web integrado, diseñado especialmente para desarrolladores, que admite múltiples lenguajes y stacks tecnológicos, incluyendo una gestión flexible de versiones de PHP y opciones de configuración sencillas. En la práctica, diferentes proyectos pueden requerir configuraciones de PHP distintas, como límites de tamaño para subida de archivos, límites de memoria o niveles de reporte de errores. Modificar directamente el archivo global php.ini afecta a todos los proyectos, lo que puede resultar muy poco práctico al gestionar múltiples desarrollos.

Afortunadamente, PHP ofrece el mecanismo de archivos .user.ini, que permite a los desarrolladores definir ajustes personalizados de PHP por directorio y sus subdirectorios, sin necesidad de tocar el archivo global php.ini. ServBay proporciona soporte total para .user.ini, haciendo que el ajuste fino de la configuración de PHP para un solo proyecto o directorio sea simple y eficiente.

En este artículo exploraremos en detalle cómo funciona el archivo .user.ini, cómo utilizarlo en ServBay y mostraremos ejemplos para establecer configuraciones personalizadas de PHP en proyectos concretos.

Introducción al archivo .user.ini

El archivo .user.ini es una característica introducida en PHP 5.3.0, diseñada para proporcionar un método más flexible y seguro que los antiguos ajustes php_value y php_flag en la configuración del servidor web (como el archivo .htaccess de Apache). Permite a los desarrolladores colocar un archivo .user.ini en cualquier directorio web accesible, y las directivas configuradas solo afectan a ese directorio y sus subdirectorios para los scripts PHP.

Características principales

1. Alcance local: Las directivas en un archivo .user.ini solo son efectivas dentro del directorio donde se encuentra y sus subdirectorios, sin afectar la configuración global de php.ini en ServBay ni a otros proyectos.
2. Gran flexibilidad: Los desarrolladores pueden definir conjuntos de configuraciones de PHP independientes adaptados a las necesidades de cada proyecto.
3. Gestión sencilla: No se requiere modificar archivos de configuración del servidor o de PHP a nivel global, lo que reduce el riesgo de conflictos y hace que la configuración de cada proyecto sea más independiente y fácil de portar.
4. Sin reinicios: A diferencia de las modificaciones en php.ini, que normalmente requieren reiniciar PHP-FPM o el servidor web, los cambios en .user.ini suelen activarse automáticamente tras el intervalo especificado por user_ini.cache_ttl (por defecto, normalmente 300 segundos, es decir, 5 minutos).

Directivas que se pueden configurar

No todas las directivas de configuración de PHP pueden establecerse en un archivo .user.ini. La posibilidad depende de su "modo de cambio" (Changeable Modes). Solo aquellas en los modos PHP_INI_USER, PHP_INI_PERDIR o PHP_INI_ALL pueden definirse en .user.ini.

Algunas de las directivas comunes que puedes establecer en .user.ini incluyen:

• upload_max_filesize
• post_max_size
• memory_limit
• display_errors
• log_errors
• max_execution_time
• session.save_path
• date.timezone

Las directivas con el modo PHP_INI_SYSTEM (como extension_dir, zend_extension, disable_functions, entre otras) no se pueden definir en .user.ini; solo pueden configurarse en el archivo principal de php.ini o directamente en la configuración del servidor web.

Para consultar el modo de cambio de cada directiva, revisa la documentación oficial sobre directivas de configuración en php.ini.

Cómo usar .user.ini en ServBay

El uso del archivo .user.ini en ServBay es muy sencillo. A continuación, explicamos los pasos concretos; tomaremos como ejemplo los ajustes de upload_max_filesize y memory_limit.

Supongamos que la raíz de tu sitio web se encuentra en la ruta predeterminada de ServBay /Applications/ServBay/www/, y que deseas aplicar una configuración PHP personalizada para un proyecto llamado myproject, cuya raíz web es /Applications/ServBay/www/myproject/public.

Paso 1: Identifica el directorio objetivo

Primero, determina en qué directorio quieres aplicar la configuración personalizada de PHP. Por lo general, este será el directorio raíz de tu proyecto accesible para el servidor web (por ejemplo, el directorio public en proyectos Laravel o Symfony), o algún subdirectorio que requiera ajustes específicos.

Ejemplo: /Applications/ServBay/www/myproject/public

Paso 2: Crea o edita el archivo .user.ini

En el directorio objetivo, crea un archivo llamado .user.ini (si ya existe, edítalo). Ten presente que los archivos que comienzan por punto, como .user.ini, son ocultos en la mayoría de sistemas de archivos, por lo que es posible que debas mostrar los archivos ocultos en tu gestor de archivos.

Puedes crear el archivo desde la terminal con:

cd /Applications/ServBay/www/myproject/public
touch .user.ini

Luego, abre el archivo .user.ini con tu editor de texto preferido y añade las directivas de configuración PHP necesarias, una por línea. Por ejemplo:

; Establecer el tamaño máximo de carga de archivos a 20MB
upload_max_filesize = 20M

; Establecer el límite de memoria para los scripts PHP a 256MB
memory_limit = 256M

; Activar la visualización de errores (recomendado solo en entorno de desarrollo)
display_errors = On

Guarda y cierra el archivo .user.ini.

Paso 3: Espera a que los cambios se apliquen o fuerza la recarga

Los cambios en el archivo .user.ini no se aplican de inmediato, ya que PHP los cachéa para optimizar el rendimiento. Por defecto, la directiva user_ini.cache_ttl controla la duración de esta caché, que suele ser 300 segundos (5 minutos). Los cambios se cargarán automáticamente una vez expire la caché.

Si quieres ver los efectos de inmediato, puedes probar las siguientes opciones (la efectividad depende de la versión y configuración concreta de ServBay):

1. Reinicia el proceso PHP-FPM correspondiente: En la interfaz de la aplicación ServBay, localiza la versión de PHP que está usando tu sitio web y detén y reinicia el servicio PHP-FPM correspondiente.
2. Reinicia ServBay: Es la opción más radical, pero también la más garantizada; ten en cuenta que detendrá todos los servicios locales en ejecución.
3. Espera a que la caché expire: Es la opción más recomendable, sobre todo si no hay urgencia.

Paso 4: Verifica que el archivo .user.ini está activo

Para comprobar si tu configuración en .user.ini se ha aplicado correctamente, puedes crear un archivo PHP sencillo que muestre la información de configuración de PHP.

En el mismo directorio donde colocaste el archivo .user.ini (por ejemplo, /Applications/ServBay/www/myproject/public), crea un archivo llamado info.php con este contenido:

<?php
phpinfo();
?>

Guarda el archivo info.php.

Luego, accede a info.php desde tu navegador visitando la URL correspondiente en tu sitio ServBay. Si tu proyecto tiene asignado el dominio myproject.servbay.demo y info.php está en el directorio public, la dirección será algo como https://myproject.servbay.demo/info.php.

En la página que muestra phpinfo(), busca las directivas que configuraste en .user.ini (por ejemplo, upload_max_filesize, memory_limit, display_errors). Deberías encontrar dos columnas: Master Value y Local Value.

• Master Value muestra el valor definido en el archivo global php.ini.
• Local Value muestra el valor efectivo para el script en cuestión, que puede provenir de .user.ini o de la configuración del servidor web.

Si el Local Value coincide con los valores que pusiste en .user.ini (por ejemplo, 20M, 256M, On), significa que tu archivo .user.ini está funcionando correctamente.

Nota importante: Una vez verificado, por motivos de seguridad, elimina o restringe el acceso al archivo info.php, ya que revela información sensible sobre la configuración de tu servidor.

Notas adicionales y consideraciones

• Nombre y ubicación del archivo: El archivo debe llamarse exactamente .user.ini y situarse en el directorio al que quieres aplicar la configuración. Afectará tanto a ese directorio como a todos sus subdirectorios.
• Modo de las directivas: Reiteramos que solo determinadas directivas pueden establecerse en .user.ini. Si intentas configurar una directiva en modo PHP_INI_SYSTEM, no tendrá efecto y normalmente no aparecerá ningún error. Consulta la documentación de PHP para confirmar las directivas compatibles.
• Caché: Ten en cuenta el valor de user_ini.cache_ttl. Si modificas con frecuencia .user.ini y necesitas que los cambios se apliquen rápido, puedes ajustar temporalmente user_ini.cache_ttl a un valor pequeño (por ejemplo, user_ini.cache_ttl = 5) en el php.ini global, aunque no se recomienda en producción por motivos de rendimiento. Ten presente que cualquier cambio en el php.ini global requiere reiniciar PHP-FPM.
• Prioridad: El orden de prioridad de los ajustes de PHP suele ser: valor predeterminado del núcleo < php.ini (o archivos .ini adicionales cargados) < configuración del servidor web (php_value/php_flag, si usas módulos Apache/nginx) < .user.ini < llamadas a la función ini_set() en el script. Las configuraciones en .user.ini sobrescriben las del php.ini global para las directivas correspondientes, pero pueden ser sobrescritas por ini_set() en el propio código.
• Seguridad: Evita almacenar información sensible en archivos .user.ini. Aunque solo afecta al directorio y subdirectorios donde reside, sigue siendo un archivo visible desde el sistema de archivos que normalmente es accesible vía web (aunque lo habitual es que esté protegido contra acceso directo).

Preguntas frecuentes (FAQ)

P: He creado un archivo .user.ini y añadido configuraciones, pero no parecen tener efecto, ¿por qué?

R: Las posibles causas incluyen:

1. Nombre o ubicación incorrecta de .user.ini: Asegúrate de que el archivo se llame exactamente .user.ini y esté en el directorio correcto.
2. Directiva incompatible: Puede que estés intentando establecer una directiva no válida para .user.ini (modos distintos a PHP_INI_USER o PHP_INI_PERDIR). Consulta la documentación de PHP.
3. Caché activa: Espera el tiempo especificado en user_ini.cache_ttl (por defecto, 5 minutos) o prueba reiniciar PHP-FPM.
4. Errores de sintaxis: Verifica que el archivo .user.ini no contenga errores de sintaxis.
5. Sobrescritura por prioridad mayor: Verifica si algún script usa ini_set() para redefinir la configuración.

P: ¿Cuál es la diferencia entre el archivo .user.ini y el archivo global php.ini?

R: El archivo global php.ini afecta a todo el entorno PHP (o a todas las aplicaciones de una versión concreta de PHP); sus configuraciones son globales para todos los scripts, salvo que sean sobrescritas por configuraciones con mayor prioridad. El archivo .user.ini solo afecta a los scripts en el directorio donde se encuentra y sus subdirectorios, y solo para ciertas directivas compatibles. Su principal ventaja es la configuración local sin modificar el archivo global.

Conclusión

Aprovechar el archivo .user.ini en ServBay es la forma recomendada de gestionar configuraciones PHP específicas para cada proyecto. Ofrece una gran flexibilidad, permitiéndote adaptar el entorno PHP para las necesidades de cada desarrollo sin afectar a otros proyectos ni a la configuración global de ServBay. Con la guía y los ejemplos de este artículo, deberías poder usar con soltura los archivos .user.ini en tus proyectos ServBay para mejorar tanto la eficiencia como la facilidad de gestión de tus entornos de desarrollo. La filosofía de ServBay es ofrecer herramientas locales potentes y flexibles para desarrolladores, y el sólido soporte de archivos .user.ini es una clara muestra de este enfoque.