From 5f235711697aff6c5e57ddb95f487504ccecff95 Mon Sep 17 00:00:00 2001 From: lacatoire Date: Thu, 27 Aug 2026 17:47:40 +0200 Subject: [PATCH] [Sync-En] yaconf: sync the Yaconf extension documentation with EN --- reference/yaconf/book.xml | 115 ++++++++++++++--------------- reference/yaconf/ini.xml | 102 ++++++++++++++++++++------ reference/yaconf/setup.xml | 46 +++++++++++- reference/yaconf/yaconf/get.xml | 125 ++++++++++++++++++++------------ reference/yaconf/yaconf/has.xml | 68 ++++++++++++++--- 5 files changed, 312 insertions(+), 144 deletions(-) diff --git a/reference/yaconf/book.xml b/reference/yaconf/book.xml index b014b5427e..ad633b73da 100644 --- a/reference/yaconf/book.xml +++ b/reference/yaconf/book.xml @@ -1,6 +1,5 @@ - - + @@ -9,65 +8,61 @@ &reftitle.intro; - - Otro contenedor de configuraciones - (Yaconf) es un contenedor de configuraciones, - analiza los archivos INI, y almacena el resultado - en PHP cuando se inicia PHP, el resultado vive con el - todo el ciclo de vida de PHP. - - - 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 Yaconf, podría considerarse como una copia cero, muy rápido. - - - Yaconf soporta secciones y hrencia de secciones - en los archivos del INI. 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 INI. - - + + Yet Another Configurations Container + (Yaconf) es un contenedor de configuraciones. Analiza + los archivos INI 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. + + + 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é. + + + 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. + + + 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. + + + 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, Yaconf::get("users.database.master") lee la + clave master del archivo + database.ini situado en el subdirectorio + users/. + + + 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 .ini pueden colocarse en su lugar en un + directorio legible únicamente por root, como + /etc/yaconf: 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. + + Yaconf requiere PHP 7.0 o superior. - - - Ejemplo INI - - - - - - Ejemplo de secciones INI - - - - + &reference.yaconf.setup; diff --git a/reference/yaconf/ini.xml b/reference/yaconf/ini.xml index 7c3e9de52c..bf89afcd96 100644 --- a/reference/yaconf/ini.xml +++ b/reference/yaconf/ini.xml @@ -1,6 +1,5 @@ - - +
&reftitle.runtime; @@ -19,14 +18,14 @@ - yaconf.check_delay - 300 + yaconf.directory + "" INI_SYSTEM - yaconf.directory - /tmp/conf/ + yaconf.check_delay + 300 INI_SYSTEM @@ -39,30 +38,89 @@ - + - yaconf.check_delay - int + yaconf.directory + string - - 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. - + + El directorio donde se encuentran todos los archivos de configuración + INI. Solo se cargan los archivos con la extensión + .ini. 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 + database.ini situado en el subdirectorio + users/ se referencia como + "users.database". Disponible desde Yaconf 1.2.0; + antes de esa versión solo se cargaban los archivos situados + directamente en el directorio. + + + Los ejemplos siguientes suponen el archivo + database.ini mostrado a continuación, situado en + el directorio configurado, junto a un archivo + features.ini que contiene los ajustes de cada + funcionalidad. + + + Sintaxis de un archivo INI + + + + + + Ejemplo de secciones INI + + + + - - + + - yaconf.directory - string + yaconf.check_delay + int - - Ruta al directorio en el que se encuentran todos los archivos de configuración INI. - + + 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 0 hace que Yaconf + compruebe en cada petición. + + + + 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. + + - - +
diff --git a/reference/yaconf/setup.xml b/reference/yaconf/setup.xml index f81dee0b07..36dde3c389 100644 --- a/reference/yaconf/setup.xml +++ b/reference/yaconf/setup.xml @@ -1,7 +1,5 @@ - - - + &reftitle.setup; @@ -15,6 +13,10 @@
&reftitle.install; + + Yaconf puede instalarse de tres maneras: mediante PECL, mediante PIE o + compilándolo a partir del código fuente. + &pecl.moved; @@ -25,6 +27,44 @@ &pecl.windows.download.avail; + + Instalación de Yaconf con PECL + + + + + + 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. + + + Instalación de Yaconf con PIE + + + + + + El código fuente está alojado en + GitHub. 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. + + + Compilación de Yaconf a partir del código fuente + + + +
&reference.yaconf.ini; diff --git a/reference/yaconf/yaconf/get.xml b/reference/yaconf/yaconf/get.xml index 4869770fbe..1f61f39d09 100644 --- a/reference/yaconf/yaconf/get.xml +++ b/reference/yaconf/yaconf/get.xml @@ -1,12 +1,10 @@ - - - + Yaconf::get - Recuperar un elemento + Recupera un valor de configuración por su nombre @@ -14,11 +12,19 @@ public static mixedYaconf::get stringname - mixeddefault_valueNULL + mixeddefault&null; - - - + + Recupera el valor de configuración almacenado bajo + name. Los nombres emplean la notación de punto + para recorrer las claves anidadas: "app" hace + referencia al archivo app.ini analizado por + completo, "app.name" a una clave dentro de él y, desde + Yaconf 1.2.0, "users.database.master" a una clave del + archivo database.ini situado en el subdirectorio + users/. La notación de punto admite hasta 64 niveles + de anidamiento. + @@ -27,17 +33,22 @@ name - - Clave de configuración, la clave se ve como "filename.key", o "filename.sectionName,key". - + + El nombre de configuración a buscar, empleando la notación de punto + para recorrer las claves anidadas, por ejemplo + "app.name", "app.features.1" + o, desde Yaconf 1.2.0, "users.database.master" + para los archivos en subdirectorios. + - default_value + default - - si la clave no existe, Yaconf::get devolverá esto como resultado. - + + El valor a devolver cuando no se encuentra + name. Si se omite, se devuelve &null;. + @@ -45,52 +56,72 @@ &reftitle.returnvalues; - - Devuelve el resultado de configuración (string o array) si la clave existe, - devuelve default_value si no. - + + El valor de configuración almacenado, un string o un + array, cuando name existe; en caso + contrario, default (o &null; si no se indicó + ningún valor por defecto). + &reftitle.examples; - - Ejemplo de <function>INI</function> - + + Los ejemplos siguientes suponen los dos archivos mostrados a + continuación, situados en el directorio configurado con + yaconf.directory. + + - - &example.outputs.similar; - + + + + + Ejemplo de <methodname>Yaconf::get</methodname> + + ]]> - + + + &reftitle.seealso; + + + Yaconf::has + Yaconf::__debug_info + + + + - - + Yaconf::has - Determinar si un elemento existe + Comprueba si existe un valor de configuración @@ -15,9 +13,14 @@ public static boolYaconf::has stringname - - - + + Determina si existe un valor de configuración bajo + name, que emplea la misma notación de punto que + Yaconf::get: por ejemplo, + "app.name" o, desde Yaconf 1.2.0, + "users.database.master" para los archivos en + subdirectorios. + @@ -26,9 +29,12 @@ name - - - + + El nombre de configuración a buscar, empleando la notación de punto + para recorrer las claves anidadas, por ejemplo + "app.name" o + "users.database.master". + @@ -36,11 +42,49 @@ &reftitle.returnvalues; - + + Devuelve &true; si existe un valor de configuración en + name, &false; en caso contrario. + + - + + &reftitle.examples; + + Los ejemplos siguientes suponen un archivo + app.ini situado en el directorio configurado con + yaconf.directory, que contiene las claves + name="shop" y debug=0. + + + Ejemplo de <methodname>Yaconf::has</methodname> + + +]]> + + + + &reftitle.seealso; + + + Yaconf::get + Yaconf::__debug_info + + +