Skip to content

[Sync-En] Revise the Yaconf extension documentation (#5801) #3379

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lacatoire merged 1 commit into from
Aug 26, 2026
Merged

[Sync-En] Revise the Yaconf extension documentation (#5801) #3379

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 50 additions & 62 deletions reference/yaconf/book.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 4a87d61dbfcaddeafeebe5fd9546c5d9c6bc9ea2 Maintainer: girgias Status: ready -->
<!-- Reviewed: no -->
<!-- EN-Revision: 3b052562d228be18fa6dce221df7e375469fb7ad Maintainer: girgias Status: ready -->

<book xml:id="book.yaconf" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<?phpdoc extension-membership="pecl" ?>
Expand All @@ -10,67 +8,57 @@

<preface xml:id="intro.yaconf">
&reftitle.intro;
<para>
<simpara>
<literal>Yet Another Configurations Container</literal>
(<acronym>Yaconf</acronym>) est un conteneur de configuration,
il analyse les fichiers <literal>INI</literal>, enregistre le résultat en
PHP quand PHP est démarré, le résultat vit tout
le long du cycle de vie de PHP.
</para>
<para>
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 <acronym>Yaconf</acronym>, ceci peut être considéré sans copie,
très rapide.
</para>
<para>
Yaconf supporte les sections et l'héritage des sections
dans les fichiers <literal>INI</literal>. Si PHP est compilé en tant que non-ZTS,
Yaconf supporte aussi le rechargement automatique après que les
fichiers <literal>INI</literal> sont modifiés.
</para>
<para>
(<acronym>Yaconf</acronym>) est un conteneur de configuration. Il analyse
les fichiers <literal>INI</literal> 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.
</simpara>
<simpara>
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.
</simpara>
<simpara>
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.
</simpara>
<simpara>
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.
</simpara>
<simpara>
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,
<literal>Yaconf::get("users.database.master")</literal> lit la clé
<literal>master</literal> depuis le fichier
<filename>database.ini</filename> placé dans le sous-répertoire
<filename>users/</filename>.
</simpara>
<simpara>
Stocker des configurations sensibles en dehors de l'arborescence web réduit
aussi la surface d'attaque. Avec Yaconf, les fichiers
<filename>.ini</filename> peuvent être placés dans un répertoire accessible
uniquement par root, comme <filename>/etc/yaconf</filename> : 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.
</simpara>
<simpara>
Yaconf nécessite PHP 7.0 ou supérieur.
</para>
<example>
<title>Exemple INI</title>
<programlisting role="ini">
<![CDATA[
;Simple key val
key=val

;Hash
hash.a=val

;Array
arr.0=val

;or
arr[]=val

;PHP constants
version=PHP_VERSION

;Environment variable
env=${PATH}
]]>
</programlisting>
</example>
<example>
<title>Exemple avec les sections INI</title>
<programlisting role="ini">
<![CDATA[
[SectionA]
key=val
hash.a=val

;SectionB inherits SectionA
[SectionB:SectionA]
key=new_val ;override configuration key in SectionA
]]>
</programlisting>
</example>
</simpara>
</preface>

&reference.yaconf.setup;
Expand Down
116 changes: 85 additions & 31 deletions reference/yaconf/ini.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d4d5216e7a965ca194f6b1c9dee84cecab2674e5 Maintainer: girgias Status: ready -->
<!-- Reviewed: no -->
<!-- EN-Revision: 3b052562d228be18fa6dce221df7e375469fb7ad Maintainer: girgias Status: ready -->

<section xml:id="yaconf.configuration" xmlns="http://docbook.org/ns/docbook">
&reftitle.runtime;
Expand All @@ -20,14 +18,14 @@
</thead>
<tbody>
<row>
<entry><link linkend="ini.yaconf.check-delay">yaconf.check_delay</link></entry>
<entry>300</entry>
<entry><link linkend="ini.yaconf.directory">yaconf.directory</link></entry>
<entry><literal>""</literal></entry>
<entry><constant>INI_SYSTEM</constant></entry>
<entry><!-- leave empty, this will be filled by an automatic script --></entry>
</row>
<row>
<entry><link linkend="ini.yaconf.directory">yaconf.directory</link></entry>
<entry>/tmp/conf/</entry>
<entry><link linkend="ini.yaconf.check-delay">yaconf.check_delay</link></entry>
<entry><literal>300</literal></entry>
<entry><constant>INI_SYSTEM</constant></entry>
<entry><!-- leave empty, this will be filled by an automatic script --></entry>
</row>
Expand All @@ -40,31 +38,87 @@

<para>
<variablelist>
<varlistentry xml:id="ini.yaconf.check-delay">
<term>
<parameter>yaconf.check_delay</parameter>
<type>int</type>
</term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.yaconf.directory">
<term>
<parameter>yaconf.directory</parameter>
<type>string</type>
</term>
<listitem>
<para>
Chemin vers le dossier où tous les fichiers de configuration INI sont placés.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.yaconf.directory">
<term>
<parameter>yaconf.directory</parameter>
<type>string</type>
</term>
<listitem>
<simpara>
Le répertoire où tous les fichiers de configuration INI sont placés.
Seuls les fichiers avec l'extension <filename>.ini</filename> 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 <filename>database.ini</filename> placé dans le
sous-répertoire <filename>users/</filename> est adressé comme
<literal>"users.database"</literal>. Disponible depuis Yaconf 1.2.0 ;
avant cela, seuls les fichiers directement dans le répertoire étaient
chargés.
</simpara>
<simpara>
Les exemples ci-dessous supposent le
<filename>database.ini</filename> suivant placé dans le répertoire
configuré, à côté d'un <filename>features.ini</filename> contenant
des paramètres par fonctionnalité.
</simpara>
<example>
<title>Syntaxe du fichier INI</title>
<programlisting role="ini">
<![CDATA[
; database.ini
name=production ; valeur scalaire
version=PHP_VERSION ; les constantes PHP sont résolues
connection_string=${DATABASE_URL} ; les variables d'environnement sont résolues
options.max_connections=50 ; clé de hachage imbriquée
options.timeout=30

; entrées de tableau, les deux notations sont équivalentes
replicas.0=replica-1.example.com
replicas[]=replica-2.example.com
]]>
</programlisting>
</example>
<example>
<title>Exemple de sections INI</title>
<programlisting role="ini">
<![CDATA[
; features.ini
[default]
cache_enabled=on
rate_limit=100

; la section "premium" hérite de toutes les clés de "default" et
; remplace celles qu'elle redéfinit
[premium:default]
rate_limit=1000
]]>
</programlisting>
</example>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.yaconf.check-delay">
<term>
<parameter>yaconf.check_delay</parameter>
<type>int</type>
</term>
<listitem>
<simpara>
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 à <literal>0</literal> fait vérifier Yaconf à chaque
requête.
</simpara>
<note>
<simpara>
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.
</simpara>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
Expand Down
45 changes: 42 additions & 3 deletions reference/yaconf/setup.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: aebf045bfb7f4f2350db5e1e908cf290be334075 Maintainer: girgias Status: ready -->
<!-- Reviewed: no -->
<!-- EN-Revision: 3b052562d228be18fa6dce221df7e375469fb7ad Maintainer: girgias Status: ready -->

<chapter xml:id="yaconf.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
Expand All @@ -15,6 +13,10 @@

<section xml:id="yaconf.installation">
&reftitle.install;
<simpara>
Yaconf peut être installé de trois façons : via PECL, via PIE, ou en
compilant depuis les sources.
</simpara>
<para>
&pecl.moved;
</para>
Expand All @@ -25,6 +27,43 @@
<para>
&pecl.windows.download.avail;
</para>
<example>
<title>Installation de Yaconf avec PECL</title>
<programlisting role="shell">
<![CDATA[
pecl install yaconf
]]>
</programlisting>
</example>
<simpara>
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.
</simpara>
<example>
<title>Installation de Yaconf avec PIE</title>
<programlisting role="shell">
<![CDATA[
pie install laruence/yaconf
]]>
</programlisting>
</example>
<simpara>
Le code source est hébergé sur
<link xlink:href="&url.git.hub;laruence/yaconf">GitHub</link>. Pour
compiler l'extension depuis les sources, exécutez les commandes suivantes,
en remplaçant les chemins par ceux de l'installation PHP locale.
</simpara>
<example>
<title>Compilation de Yaconf depuis les sources</title>
<programlisting role="shell">
<![CDATA[
/path/to/phpize
./configure --with-php-config=/path/to/php-config
make && make install
]]>
</programlisting>
</example>
</section>

&reference.yaconf.ini;
Expand Down
Loading
Loading