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
- 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 globalephp.ini
de ServBay ni celle des autres projets. - Haute flexibilité : Chaque projet peut obtenir son propre ensemble de réglages PHP selon ses besoins.
- 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.
- 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 paruser_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
2
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
2
3
4
5
6
7
8
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) :
- 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.
- Redémarrer ServBay : cela garantira la prise en compte des modifications, mais interrompra tous les services locaux.
- 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();
?>
2
3
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 fichierphp.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 lephp.ini
global (par exempleuser_ini.cache_ttl = 5
). Cependant, cela n’est pas recommandé en production pour éviter une dégradation des performances. Toute modification duphp.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 fonctionini_set()
dans le code. Une directive dans.user.ini
remplacera la valeur globale, mais sera écrasée parini_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 :
- Nom ou emplacement incorrect : Assurez-vous qu’il s’appelle bien
.user.ini
et qu’il est placé dans le bon dossier. - Directive non supportée : Seules les directives de type
PHP_INI_USER
ouPHP_INI_PERDIR
sont autorisées. Vérifiez leur compatibilité dans la documentation PHP. - Cache non expiré : Patientez le temps défini par
user_ini.cache_ttl
(par défaut 5 minutes), ou redémarrez PHP-FPM. - Erreur de syntaxe : Relisez attentivement le contenu de votre fichier
.user.ini
. - 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.