Skip to content

[Sync-En] yaconf: sync the Yaconf extension documentation with EN #1146

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
julionc merged 1 commit into from
Aug 28, 2026
Merged

[Sync-En] yaconf: sync the Yaconf extension documentation with EN #1146

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
115 changes: 55 additions & 60 deletions reference/yaconf/book.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 4a87d61dbfcaddeafeebe5fd9546c5d9c6bc9ea2 Maintainer: Marqitos Status: ready -->
<!-- Reviewed: no -->
<!-- EN-Revision: 3b052562d228be18fa6dce221df7e375469fb7ad Maintainer: Marqitos 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 @@ -9,65 +8,61 @@

<preface xml:id="intro.yaconf">
&reftitle.intro;
<para>
<literal>Otro contenedor de configuraciones</literal>
(<acronym>Yaconf</acronym>) es un contenedor de configuraciones,
analiza los archivos <literal>INI</literal>, y almacena el resultado
en PHP cuando se inicia PHP, el resultado vive con el
todo el ciclo de vida de PHP.
</para>
<para>
Yaconf almacena todas las configuraciones como
string interno o array inmutable, eso significa que no se pueden
devolver, por lo que al recuperar las configuraciones
de <acronym>Yaconf</acronym>, podría considerarse como una copia cero, muy rápido.
</para>
<para>
Yaconf soporta secciones y hrencia de secciones
en los archivos del <literal>INI</literal>. si PHP se construye como una construcción no-ZTS,
Yaconf también soporta la recarga automática después de que se cambien
los archivos del <literal>INI</literal>.
</para>
<para>
<simpara>
<literal>Yet Another Configurations Container</literal>
(<acronym>Yaconf</acronym>) es un contenedor de configuraciones. Analiza
los archivos <literal>INI</literal> cuando PHP se inicia y conserva el
resultado en memoria persistente durante todo el ciclo de vida de PHP,
de modo que cada recuperación es una rápida búsqueda en una tabla hash,
sin E/S de archivos y sin análisis por petición.
</simpara>
<simpara>
Yaconf almacena todas las configuraciones como cadenas internalizadas o
arrays inmutables. No están sujetas al conteo de referencias, por lo que
recuperar una configuración de Yaconf es, en la práctica, una operación
sin copia. Desde Yaconf 1.2.0, todo el árbol de configuración analizado
se compacta además en un único bloque contiguo, lo que reduce el consumo
de memoria y mejora la localidad de caché.
</simpara>
<simpara>
La configuración analizada reside en memoria persistente compartida por
todos los procesos de trabajo de PHP-FPM mediante copia al escribir:
mientras un archivo de configuración no cambie, los procesos de trabajo
comparten las mismas páginas físicas de memoria sin importar cuántos
estén en ejecución.
</simpara>
<simpara>
Yaconf admite secciones y herencia de secciones en los archivos INI. En
las compilaciones no ZTS también recarga los archivos automáticamente
cuando cambian; en las compilaciones ZTS (seguras para hilos), las
configuraciones se cargan al inicio y es necesario reiniciar para tener
en cuenta los cambios.
</simpara>
<simpara>
Desde Yaconf 1.2.0, los subdirectorios del directorio configurado se
cargan de forma recursiva (hasta 16 niveles de profundidad) y se
referencian usando el nombre del directorio como un nivel de clave: por
ejemplo, <literal>Yaconf::get("users.database.master")</literal> lee la
clave <literal>master</literal> del archivo
<filename>database.ini</filename> situado en el subdirectorio
<filename>users/</filename>.
</simpara>
<simpara>
Almacenar las configuraciones sensibles fuera del árbol web también
reduce la superficie de ataque. Los archivos de configuración situados
bajo la raíz web pueden ser recuperados por un atacante, por ejemplo a
través de una vulnerabilidad de divulgación de archivos. Con Yaconf, los
archivos <filename>.ini</filename> pueden colocarse en su lugar en un
directorio legible únicamente por root, como
<filename>/etc/yaconf</filename>: el proceso maestro de PHP-FPM carga las
configuraciones cuando el servicio arranca, mientras que los procesos de
trabajo derivados —que se ejecutan con un usuario sin privilegios y son
los que atienden las peticiones web— no necesitan, y no reciben, acceso a
ese directorio.
</simpara>
<simpara>
Yaconf requiere PHP 7.0 o superior.
</para>
<example>
<title>Ejemplo INI</title>
<programlisting role="ini">
<![CDATA[
;Simple clave valor
key=valor

;Hash
hash.a=valor

;Array
arr.0=valor
;o
arr[]=valor

;Constante PHP
version=PHP_VERSION

;Variable de entorno
env=${PATH}
]]>
</programlisting>
</example>
<example>
<title>Ejemplo de secciones INI</title>
<programlisting role="ini">
<![CDATA[
[SectionA]
key=valor
hash.a=valor

;SectionB hereda de SectionA
[SectionB:SectionA]
key=nuevo_valor ;Sobrescribe la clave de configuración en la SecciónA
]]>
</programlisting>
</example>
</simpara>
</preface>

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

<section xml:id="yaconf.configuration" xmlns="http://docbook.org/ns/docbook">
&reftitle.runtime;
Expand All @@ -19,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 @@ -39,30 +38,89 @@

<para>
<variablelist>
<varlistentry xml:id="ini.yaconf.check-delay">
<varlistentry xml:id="ini.yaconf.directory">
<term>
<parameter>yaconf.check_delay</parameter>
<type>int</type>
<parameter>yaconf.directory</parameter>
<type>string</type>
</term>
<listitem>
<para>
En que intervalo Yaconf detectará el cambio del archivo ini (por el directorio mtime),
si se pone a cero, hay que reiniciar el php para recargar las configuraciones.
</para>
<simpara>
El directorio donde se encuentran todos los archivos de configuración
INI. Solo se cargan los archivos con la extensión
<filename>.ini</filename>. Los subdirectorios se cargan de forma
recursiva (hasta 16 niveles de profundidad); cada uno actúa como un
nivel de clave, de modo que un archivo
<filename>database.ini</filename> situado en el subdirectorio
<filename>users/</filename> se referencia como
<literal>"users.database"</literal>. Disponible desde Yaconf 1.2.0;
antes de esa versión solo se cargaban los archivos situados
directamente en el directorio.
</simpara>
<simpara>
Los ejemplos siguientes suponen el archivo
<filename>database.ini</filename> mostrado a continuación, situado en
el directorio configurado, junto a un archivo
<filename>features.ini</filename> que contiene los ajustes de cada
funcionalidad.
</simpara>
<example>
<title>Sintaxis de un archivo INI</title>
<programlisting role="ini">
<![CDATA[
; database.ini
name=production ; valor escalar
version=PHP_VERSION ; las constantes de PHP se resuelven
connection_string=${DATABASE_URL} ; las variables de entorno se resuelven
options.max_connections=50 ; clave hash anidada
options.timeout=30

; entradas de array, ambas notaciones son equivalentes
replicas.0=replica-1.example.com
replicas[]=replica-2.example.com
]]>
</programlisting>
</example>
<example>
<title>Ejemplo de secciones INI</title>
<programlisting role="ini">
<![CDATA[
; features.ini
[default]
cache_enabled=on
rate_limit=100

; la sección "premium" hereda todas las claves de "default" y
; sobrescribe las que redefine
[premium:default]
rate_limit=1000
]]>
</programlisting>
</example>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.yaconf.directory">
</varlistentry>
<varlistentry xml:id="ini.yaconf.check-delay">
<term>
<parameter>yaconf.directory</parameter>
<type>string</type>
<parameter>yaconf.check_delay</parameter>
<type>int</type>
</term>
<listitem>
<para>
Ruta al directorio en el que se encuentran todos los archivos de configuración INI.
</para>
<simpara>
El intervalo, en segundos, con el que Yaconf comprueba si alguno de
los archivos INI cargados ha cambiado y recarga los que hayan
cambiado (el cambio se detecta comparando las fechas de modificación
del directorio). Establecerlo a <literal>0</literal> hace que Yaconf
compruebe en cada petición.
</simpara>
<note>
<simpara>
Esta directiva solo se registra en las compilaciones no ZTS. En las
compilaciones ZTS (seguras para hilos), las configuraciones se cargan
al inicio y la recarga automática no está disponible; hay que
reiniciar PHP para tener en cuenta los cambios.
</simpara>
</note>
</listitem>
</varlistentry>

</varlistentry>
</variablelist>
</para>
</section>
Expand Down
46 changes: 43 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: andresdzphp Status: ready -->
<!-- Reviewed: yes Maintainer: julionc -->
<!-- EN-Revision: 3b052562d228be18fa6dce221df7e375469fb7ad Maintainer: andresdzphp 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 puede instalarse de tres maneras: mediante PECL, mediante PIE o
compilándolo a partir del código fuente.
</simpara>
<para>
&pecl.moved;
</para>
Expand All @@ -25,6 +27,44 @@
<para>
&pecl.windows.download.avail;
</para>
<example>
<title>Instalación de Yaconf con PECL</title>
<programlisting role="shell">
<![CDATA[
pecl install yaconf
]]>
</programlisting>
</example>
<simpara>
Desde Yaconf 1.2.0, la extensión puede instalarse con &link.pie;, el
instalador de extensiones de PHP, ejecutando lo siguiente en la línea de
órdenes.
</simpara>
<example>
<title>Instalación de Yaconf con PIE</title>
<programlisting role="shell">
<![CDATA[
pie install laruence/yaconf
]]>
</programlisting>
</example>
<simpara>
El código fuente está alojado en
<link xlink:href="&url.git.hub;laruence/yaconf">GitHub</link>. Para
compilar la extensión a partir del código fuente, hay que ejecutar lo
siguiente en la línea de órdenes, reemplazando las rutas por las de la
instalación local de PHP.
</simpara>
<example>
<title>Compilación de Yaconf a partir del código fuente</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