diff --git a/reference/yaconf/book.xml b/reference/yaconf/book.xml index 60b08af08f..78ec1373d8 100644 --- a/reference/yaconf/book.xml +++ b/reference/yaconf/book.xml @@ -1,7 +1,5 @@ - - - + @@ -10,67 +8,57 @@ &reftitle.intro; - + Yet Another Configurations Container - (Yaconf) est un conteneur de configuration, - il analyse les fichiers INI, enregistre le résultat en - PHP quand PHP est démarré, le résultat vit tout - le long du cycle de vie de PHP. - - - Yaconf enregistre toutes les configurations en tant que - chaîne internée ou un tableau immuable, ce qui signifie qu'ils ne sont pas - comptabilisés dans les références, ainsi lors de la récupération des - configurations depuis Yaconf, ceci peut être considéré sans copie, - très rapide. - - - Yaconf supporte les sections et l'héritage des sections - dans les fichiers INI. Si PHP est compilé en tant que non-ZTS, - Yaconf supporte aussi le rechargement automatique après que les - fichiers INI sont modifiés. - - + (Yaconf) est un conteneur de configuration. Il analyse + les fichiers INI au démarrage de PHP et conserve le + résultat en mémoire persistante pour toute la durée du cycle de vie de PHP, + de sorte que chaque accès est une simple recherche dans une table de hachage, + sans aucune E/S disque ni analyse par requête. + + + Yaconf enregistre toutes les configurations sous forme de chaînes internées + ou de tableaux immuables. Ils ne sont pas comptabilisés dans les références, + donc la récupération d'une configuration depuis Yaconf est effectivement + sans copie. Depuis Yaconf 1.2.0, l'arbre de configuration analysé est en + outre compacté dans un bloc contigu unique, ce qui réduit l'empreinte + mémoire et améliore la localité du cache. + + + La configuration analysée réside en mémoire persistante partagée par tous + les workers PHP-FPM via la copie sur écriture : tant qu'un fichier de + configuration ne change pas, les workers partagent les mêmes pages mémoire + physiques, quel que soit leur nombre. + + + Yaconf supporte les sections et l'héritage de sections dans les fichiers + INI. Sur les compilations non-ZTS, il recharge aussi les fichiers + automatiquement lorsqu'ils changent ; sur les compilations ZTS + (thread-safe), les configurations sont chargées au démarrage et un + redémarrage est nécessaire pour prendre en compte les modifications. + + + Depuis Yaconf 1.2.0, les sous-répertoires du répertoire configuré sont + chargés récursivement (jusqu'à 16 niveaux de profondeur) et adressés avec + le nom du répertoire comme niveau de clé : par exemple, + Yaconf::get("users.database.master") lit la clé + master depuis le fichier + database.ini placé dans le sous-répertoire + users/. + + + Stocker des configurations sensibles en dehors de l'arborescence web réduit + aussi la surface d'attaque. Avec Yaconf, les fichiers + .ini peuvent être placés dans un répertoire accessible + uniquement par root, comme /etc/yaconf : le master + PHP-FPM charge les configurations au démarrage du service, tandis que les + workers forqués — qui s'exécutent sous un utilisateur non privilégié et + traitent les requêtes web — n'ont pas besoin, et ne reçoivent pas, l'accès + à ce répertoire. + + Yaconf nécessite PHP 7.0 ou supérieur. - - - Exemple INI - - - - - - Exemple avec les sections INI - - - - + &reference.yaconf.setup; diff --git a/reference/yaconf/ini.xml b/reference/yaconf/ini.xml index 05c30aa37a..3d46f06694 100644 --- a/reference/yaconf/ini.xml +++ b/reference/yaconf/ini.xml @@ -1,7 +1,5 @@ - - - +
&reftitle.runtime; @@ -20,14 +18,14 @@ - yaconf.check_delay - 300 + yaconf.directory + "" INI_SYSTEM - yaconf.directory - /tmp/conf/ + yaconf.check_delay + 300 INI_SYSTEM @@ -40,31 +38,87 @@ - - - yaconf.check_delay - int - - - - Intervalle dans lequel Yaconf détectera les modifications de fichier - INI (grâce au mtime du dossier), si ceci est défini à zéro, il faut - redémarrer PHP pour recharger les configurations. - - - - - - yaconf.directory - string - - - - Chemin vers le dossier où tous les fichiers de configuration INI sont placés. - - - + + + yaconf.directory + string + + + + Le répertoire où tous les fichiers de configuration INI sont placés. + Seuls les fichiers avec l'extension .ini sont + chargés. Les sous-répertoires sont chargés récursivement (jusqu'à + 16 niveaux de profondeur) ; chacun agit comme un niveau de clé, de + sorte qu'un fichier database.ini placé dans le + sous-répertoire users/ est adressé comme + "users.database". Disponible depuis Yaconf 1.2.0 ; + avant cela, seuls les fichiers directement dans le répertoire étaient + chargés. + + + Les exemples ci-dessous supposent le + database.ini suivant placé dans le répertoire + configuré, à côté d'un features.ini contenant + des paramètres par fonctionnalité. + + + Syntaxe du fichier INI + + + + + + Exemple de sections INI + + + + + + + + + yaconf.check_delay + int + + + + L'intervalle, en secondes, auquel Yaconf vérifie si un fichier INI + chargé a changé et recharge les fichiers modifiés (la modification est + détectée en comparant les temps de modification du répertoire). Définir + cette valeur à 0 fait vérifier Yaconf à chaque + requête. + + + + Cette directive n'est enregistrée que sur les compilations non-ZTS. + Sur les compilations ZTS (thread-safe), les configurations sont + chargées au démarrage et le rechargement automatique n'est pas + disponible ; redémarrer PHP pour prendre en compte les modifications. + + + +
diff --git a/reference/yaconf/setup.xml b/reference/yaconf/setup.xml index 2dd1fadf71..0db6c1f291 100644 --- a/reference/yaconf/setup.xml +++ b/reference/yaconf/setup.xml @@ -1,7 +1,5 @@ - - - + &reftitle.setup; @@ -15,6 +13,10 @@
&reftitle.install; + + Yaconf peut être installé de trois façons : via PECL, via PIE, ou en + compilant depuis les sources. + &pecl.moved; @@ -25,6 +27,43 @@ &pecl.windows.download.avail; + + Installation de Yaconf avec PECL + + + + + + Depuis Yaconf 1.2.0, l'extension peut être installée avec + &link.pie;, le PHP Installer for Extensions, en exécutant la commande + suivante. + + + Installation de Yaconf avec PIE + + + + + + Le code source est hébergé sur + GitHub. Pour + compiler l'extension depuis les sources, exécutez les commandes suivantes, + en remplaçant les chemins par ceux de l'installation PHP locale. + + + Compilation de Yaconf depuis les sources + + + +
&reference.yaconf.ini; diff --git a/reference/yaconf/yaconf/debuginfo.xml b/reference/yaconf/yaconf/debuginfo.xml new file mode 100644 index 0000000000..ea466a32ca --- /dev/null +++ b/reference/yaconf/yaconf/debuginfo.xml @@ -0,0 +1,143 @@ + + + + + + Yaconf::__debug_info + Inspecte la façon dont une valeur de configuration est stockée + + + + &reftitle.description; + + public static arraynullYaconf::__debug_info + stringname + + + Retourne des informations de débogage sur la valeur stockée sous + name : l'adresse mémoire de la valeur stockée et + si la valeur réside toujours dans le bloc de stockage compacté de Yaconf. + + + + Cette méthode existe uniquement pour la suite de tests de Yaconf, qui + l'utilise pour vérifier que l'extension fonctionne correctement. Ne pas + l'utiliser dans du code de production, et ne pas se fier au format de sa + sortie : le tableau retourné peut changer à tout moment. + + + + + + &reftitle.parameters; + + + name + + + Le nom de configuration à inspecter, en utilisant la même notation + pointée que Yaconf::get. + + + + + + + + &reftitle.returnvalues; + + Un &array; avec quatre entrées lorsque la configuration existe, &null; + sinon : + + + + + key — le nom recherché. + + + + + address — l'adresse mémoire de la valeur stockée. + Les valeurs sont stockées comme des chaînes internées ou des tableaux + immuables, donc cette adresse reste constante jusqu'au rechargement de + la configuration. + + + + + val — la valeur stockée elle-même. + + + + + changed — &false; tant que les données de la valeur + résident dans le bloc de stockage compacté, ce qui signifie que le + système d'exploitation n'a pas eu besoin de copier la page (la + copie-sur-écriture s'applique toujours) ; &true; lorsque la valeur a + été réallouée en dehors du bloc. + + + + + + + &reftitle.examples; + + Exemple avec <methodname>Yaconf::__debug_info</methodname> + + + string(8) "app.name" + ["address"]=> + string(14) "0x7f8b1c0a3d20" + ["val"]=> + string(4) "shop" + ["changed"]=> + bool(false) +} +*/ + +var_dump(Yaconf::__debug_info("app.missing")); // NULL +?> +]]> + + + + + + &reftitle.seealso; + + + Yaconf::get + Yaconf::has + + + + + + + diff --git a/reference/yaconf/yaconf/get.xml b/reference/yaconf/yaconf/get.xml index f3331d2196..c91b019451 100644 --- a/reference/yaconf/yaconf/get.xml +++ b/reference/yaconf/yaconf/get.xml @@ -1,12 +1,10 @@ - - - + Yaconf::get - Récupère une entrée + Récupère une valeur de configuration par son nom @@ -14,11 +12,18 @@ public static mixedYaconf::get stringname - mixeddefault_valueNULL + mixeddefault&null; - - - + + Récupère la valeur de configuration stockée sous name. + Les noms utilisent la notation pointée pour traverser les clés imbriquées : + "app" adresse le fichier app.ini + entier, "app.name" une clé à l'intérieur, et depuis + Yaconf 1.2.0 "users.database.master" une clé dans le + fichier database.ini placé dans le sous-répertoire + users/. La notation pointée supporte jusqu'à 64 + niveaux d'imbrication. + @@ -27,18 +32,22 @@ name - - Clé de configuration, la clé ressemble à "filename.key", - ou "filename.sectionName,key". - + + Le nom de configuration à rechercher, en utilisant la notation pointée + pour traverser les clés imbriquées, par exemple + "app.name", "app.features.1" + ou, depuis Yaconf 1.2.0, "users.database.master" + pour les fichiers dans des sous-répertoires. + - default_value + default - - Si la clé n'existe pas, Yaconf::get retourne ceci comme résultat. - + + La valeur à retourner lorsque name n'est pas + trouvé. Lorsqu'omis, &null; est retourné. + @@ -46,52 +55,71 @@ &reftitle.returnvalues; - - Retourne la valeur de configuration (&string; ou &array;) si la clé existe, - retourne default_value sinon. - + + La valeur de configuration stockée, une &string; ou un &array;, lorsque + name existe ; sinon la valeur + default (ou &null; lorsqu'aucun défaut n'a été + fourni). + &reftitle.examples; - - Exemple <function>INI</function> - + + Les exemples ci-dessous supposent les deux fichiers suivants placés dans + le répertoire configuré avec yaconf.directory. + + - - &example.outputs.similar; - + + + + + Exemple avec <methodname>Yaconf::get</methodname> + + ]]> - + + + &reftitle.seealso; + + + Yaconf::has + Yaconf::__debug_info + + + + - - + Yaconf::has - Détermine si une entrée existe + Vérifie si une valeur de configuration existe @@ -15,9 +13,14 @@ public static boolYaconf::has stringname - - - + + Détermine si une valeur de configuration existe sous + name, qui utilise la même notation pointée que + Yaconf::get : par exemple, + "app.name" ou, depuis Yaconf 1.2.0, + "users.database.master" pour les fichiers dans des + sous-répertoires. + @@ -26,9 +29,12 @@ name - - - + + Le nom de configuration à rechercher, en utilisant la notation pointée + pour traverser les clés imbriquées, par exemple + "app.name" ou + "users.database.master". + @@ -36,12 +42,49 @@ &reftitle.returnvalues; + + Retourne &true; si une valeur de configuration existe à + name, &false; sinon. + + + + + &reftitle.examples; + + Les exemples ci-dessous supposent un fichier app.ini + placé dans le répertoire configuré avec yaconf.directory, + contenant les clés name="shop" et + debug=0. + + + Exemple avec <methodname>Yaconf::has</methodname> + + +]]> + + + + + + &reftitle.seealso; - + + Yaconf::get + Yaconf::__debug_info + -