Comment utiliser le fichier .user.ini dans ServBay : Guide de personnalisation locale de PHP

ServBay est un environnement de développement web local tout-en-un, puissant et conçu pour les développeurs, qui prend en charge de nombreux langages et stacks, avec une gestion flexible des versions de PHP et des options de configuration pratiques. En développement, chaque projet peut avoir des besoins différents en matière de configuration PHP, par exemple la taille maximale des fichiers uploadés, la limite mémoire ou le niveau de rapport des erreurs. Modifier directement le fichier global php.ini affectera tous les projets, ce qui n’est pas pratique pour la gestion multi-projets.

Heureusement, PHP fournit le mécanisme des fichiers .user.ini, permettant aux développeurs de définir des paramètres PHP spécifiques à un répertoire et à ses sous-répertoires, sans toucher au php.ini global. ServBay prend entièrement en charge les .user.ini, ce qui rend la personnalisation des paramètres PHP pour un projet ou un dossier simple et efficace.

Ce guide détaille le fonctionnement des fichiers .user.ini, comment les utiliser dans ServBay, et propose des exemples pratiques pour adapter la configuration PHP à un projet donné.

Introduction au fichier .user.ini

Le fichier .user.ini a été introduit avec PHP 5.3.0 pour offrir une alternative plus flexible et plus sûre à l’ancienne méthode utilisant php_value et php_flag dans la configuration des serveurs web (par exemple, dans .htaccess sous Apache). Ce système permet de placer un fichier .user.ini dans un répertoire web, dont les directives de configuration ne s’appliqueront qu’à ce dossier et à ses sous-dossiers.

Principales caractéristiques

1. Portée locale : Les directives d’un fichier .user.ini ne s’appliquent qu’au dossier où il se trouve et à ses sous-répertoires, sans modifier la configuration globale php.ini de ServBay ni celle des autres projets.
2. Haute flexibilité : Chaque projet peut obtenir son propre ensemble de réglages PHP selon ses besoins.
3. Gestion simplifiée : Inutile de toucher aux fichiers de configuration globaux du serveur ou de PHP, ce qui réduit les risques de conflits et améliore l’indépendance et la portabilité des projets.
4. Pas besoin de redémarrer : Contrairement à la modification de php.ini, qui nécessite en général un redémarrage de PHP-FPM ou du serveur web, les changements dans .user.ini prennent effet automatiquement après l’intervalle défini par user_ini.cache_ttl (par défaut 300 secondes, soit 5 minutes).

Directives configurables

Toutes les directives PHP ne sont pas modifiables via .user.ini. Leur disponibilité dépend de leur « mode de modification » (Changeable Modes). Seules les directives de type PHP_INI_USER, PHP_INI_PERDIR ou PHP_INI_ALL peuvent y être définies.

Exemples courants de directives configurables dans .user.ini :

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

Les directives au mode PHP_INI_SYSTEM (par exemple extension_dir, zend_extension, disable_functions, etc.) ne peuvent pas être paramétrées dans .user.ini : celles-ci doivent obligatoirement être définies dans le php.ini principal ou la configuration du serveur web.

Pour consulter le mode de chaque directive, rendez-vous sur la documentation officielle PHP des directives du php.ini.

Utilisation de .user.ini dans ServBay

L’utilisation des fichiers .user.ini sous ServBay est très simple. Voici les étapes à suivre, illustrées en prenant l’exemple de la configuration de upload_max_filesize et memory_limit.

Imaginons que le dossier racine de votre site soit /Applications/ServBay/www/ et que vous souhaitez personnaliser la configuration PHP d’un projet nommé myproject, dont le répertoire web se situe dans /Applications/ServBay/www/myproject/public.

Étape 1 : Déterminer le répertoire cible

D’abord, identifiez le dossier où vous voulez appliquer la configuration PHP personnalisée. Il s’agit généralement du dossier racine du projet accessible par le web (par exemple, le dossier public pour un projet Laravel ou Symfony), ou d’un sous-répertoire qui nécessite une configuration spécifique.

Exemple : /Applications/ServBay/www/myproject/public

Étape 2 : Créer ou éditer le fichier .user.ini

Dans ce dossier cible, créez un fichier nommé .user.ini (ou modifiez-le s’il existe déjà). Notez que sous la plupart des systèmes de fichiers, un fichier commençant par un point est caché ; vous devrez peut-être ajuster l’affichage des fichiers cachés dans votre gestionnaire de fichiers.

Pour créer le fichier via le terminal :

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

Ouvrez ensuite le fichier .user.ini dans un éditeur de texte, et ajoutez vos directives PHP souhaitées, une par ligne :

; Définit la taille maximale d’upload de fichier à 20 Mo
upload_max_filesize = 20M

; Définit la limite de mémoire PHP à 256 Mo
memory_limit = 256M

; Active l’affichage des erreurs (recommandé uniquement en environnement de développement)
display_errors = On

Enregistrez et fermez le fichier .user.ini.

Étape 3 : Attendre la prise en compte de la configuration ou rafraîchir manuellement

Les changements apportés à .user.ini ne sont pas appliqués instantanément : PHP met en cache ce fichier pour des raisons de performance. Par défaut, l’intervalle de rafraîchissement est contrôlé par la directive user_ini.cache_ttl, généralement à 300 secondes (5 minutes).

Pour que vos modifications prennent effet immédiatement, voici plusieurs méthodes possibles (cela dépend de la version de ServBay et de sa configuration) :

1. Redémarrer le processus PHP-FPM concerné : depuis l’interface ServBay, trouvez la version de PHP utilisée par votre site, puis stoppez et relancez le service PHP-FPM correspondant.
2. Redémarrer ServBay : cela garantira la prise en compte des modifications, mais interrompra tous les services locaux.
3. Attendre l’expiration du cache : c’est la méthode la plus recommandée en dehors des cas urgents.

Étape 4 : Vérifier l’application du fichier .user.ini

Pour vérifier si vos réglages dans .user.ini sont bien pris en compte, créez un fichier PHP simple affichant les informations PHP.

Dans le même dossier que votre .user.ini (par exemple /Applications/ServBay/www/myproject/public), créez un fichier nommé info.php avec le contenu suivant :

<?php
phpinfo();
?>

Enregistrez le fichier info.php.

Ouvrez ensuite ce fichier dans un navigateur via l’URL correspondant à votre projet ServBay. Par exemple, si le domaine ServBay de votre projet est myproject.servbay.demo et que info.php se trouve dans le dossier public, l’adresse sera probablement : https://myproject.servbay.demo/info.php.

Sur la page générée par phpinfo(), cherchez les directives que vous avez renseignées (upload_max_filesize, memory_limit, display_errors, etc.). Vous y verrez deux colonnes : Master Value (valeur globale php.ini) et Local Value (valeur effective pour ce script).

• Master Value : valeur définie dans le fichier php.ini global.
• Local Value : valeur effectivement utilisée par le script, issue de .user.ini ou de la configuration serveur.

Si la colonne Local Value affiche les valeurs définies dans votre .user.ini (par exemple 20M, 256M, On), votre fichier .user.ini est correctement pris en compte.

Important : Pensez à supprimer ou à restreindre l’accès à votre fichier info.php une fois la vérification terminée, car il affiche l’ensemble de la configuration de votre serveur.

Informations et précautions complémentaires

• Nom et emplacement du fichier : Il doit strictement s’appeler .user.ini et se trouver dans le répertoire cible où appliquer la configuration. Il affecte ce dossier et tous ses sous-dossiers.
• Mode des directives : Seules certaines directives peuvent être modifiées de cette manière. Les directives de type PHP_INI_SYSTEM ne s’appliquent pas via .user.ini. Consultez la documentation PHP pour confirmer.
• Mise en cache : Soyez attentif à la valeur de user_ini.cache_ttl. Si vous devez tester fréquemment les effets de modifications dans .user.ini, vous pouvez temporairement réduire cette valeur dans le php.ini global (par exemple user_ini.cache_ttl = 5). Cependant, cela n’est pas recommandé en production pour éviter une dégradation des performances. Toute modification du php.ini global nécessite un redémarrage de PHP-FPM.
• Priorités : L’ordre de priorité des configurations PHP est généralement : valeurs par défaut < php.ini (ou autres fichiers .ini chargés) < configuration serveur web (php_value/php_flag, si utilisé via Apache/nginx) < .user.ini < appels à la fonction ini_set() dans le code. Une directive dans .user.ini remplacera la valeur globale, mais sera écrasée par ini_set() si utilisé dans un script.
• Sécurité : N’enregistrez pas d’informations sensibles dans un fichier .user.ini. Même si son effet est limité au dossier courant, il reste dans une partie potentiellement accessible du Web (même si l’accès direct est en général interdit).

Foire aux questions (FAQ)

Q : J’ai créé un fichier .user.ini avec mes réglages, mais ils ne semblent pas appliqués. Pourquoi ?

R : Plusieurs causes possibles :

1. Nom ou emplacement incorrect : Assurez-vous qu’il s’appelle bien .user.ini et qu’il est placé dans le bon dossier.
2. Directive non supportée : Seules les directives de type PHP_INI_USER ou PHP_INI_PERDIR sont autorisées. Vérifiez leur compatibilité dans la documentation PHP.
3. Cache non expiré : Patientez le temps défini par user_ini.cache_ttl (par défaut 5 minutes), ou redémarrez PHP-FPM.
4. Erreur de syntaxe : Relisez attentivement le contenu de votre fichier .user.ini.
5. Priorité dépassée : Votre réglage pourrait être surchargé par une fonction ini_set() appelée dans le code.

Q : Quelle différence entre le fichier .user.ini et le fichier global php.ini ?

R : Le php.ini global affecte l’ensemble de l’environnement PHP (ou tous les projets utilisant une même version de PHP). Ses réglages s’appliquent partout, sauf s’ils sont envoyés par une configuration de priorité supérieure. Le fichier .user.ini, lui, est local au dossier où il se trouve (et sous-dossiers), et ne permet de modifier que certaines directives. Son principal intérêt réside dans la personnalisation fine et sans impact sur les autres projets ou la configuration globale.

Conclusion

L’utilisation des fichiers .user.ini dans ServBay est une méthode recommandée pour gérer les paramètres PHP spécifiques à chaque projet. Elle offre une flexibilité maximale, permettant aux développeurs d’ajuster l’environnement PHP selon les besoins d’un projet sans impacter ni la configuration globale de ServBay, ni les autres projets. Grâce à ce guide et ses exemples, vous pouvez désormais personnaliser votre configuration PHP localement dans vos projets ServBay, et ainsi améliorer efficacement votre productivité et la gestion de vos environnements de développement. L’approche de ServBay est de proposer des outils locaux puissants et modulables pour les développeurs — et le support avancé de .user.ini en est une belle illustration.