Skip to content

新增 Yaconf 扩展文档的中文翻译 #1060

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

新增 Yaconf 扩展文档的中文翻译 #1060

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
80 changes: 80 additions & 0 deletions reference/yaconf/book.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 3b052562d228be18fa6dce221df7e375469fb7ad Maintainer: laruence 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" ?>
<title>Yaconf</title>
<titleabbrev>Yaconf</titleabbrev>

<preface xml:id="intro.yaconf">
&reftitle.intro;
<simpara>
<literal>Yet Another Configurations Container</literal>（又一个配置容器，
简称 <acronym>Yaconf</acronym>）是一个配置容器。它在 PHP 启动时解析
<literal>INI</literal> 文件，并将解析结果常驻保存在内存中，贯穿 PHP
的整个生命周期。因此每一次读取配置都是一次快速的哈希表查找，
既没有文件 I/O，也不需要每个请求重新解析。
</simpara>
<simpara>
Yaconf 把所有配置以驻留字符串（interned string）或不可变数组的形式存储。
它们不参与引用计数，所以从 Yaconf 读取配置几乎是零拷贝的。
从 Yaconf 1.2.0 起，解析后的整棵配置树还会被进一步压缩到一块连续的
内存中，既降低了内存开销，也提升了缓存局部性。
</simpara>
<simpara>
解析后的配置保存在持久内存中，所有 PHP-FPM worker 通过写时复制
（copy-on-write）共享这份数据：只要配置文件没有变化，无论有多少个
worker，它们共享的都是同一份物理内存页。
</simpara>
<simpara>
Yaconf 支持 INI 文件中的 section（节）以及节继承。在非 ZTS 构建下，
它还会在文件变更时自动重新加载；在 ZTS（线程安全）构建下，
配置只在启动时加载一次，变更后需要重启 PHP 才能生效。
</simpara>
<simpara>
从 Yaconf 1.2.0 起，配置目录下的子目录会被递归加载（最多 16 层深），
子目录名作为一级键参与寻址：例如
<literal>Yaconf::get("users.database.master")</literal> 读取的是
<filename>users/</filename> 子目录下 <filename>database.ini</filename>
文件里的 <literal>master</literal> 键。
</simpara>
<simpara>
把敏感配置放在 Web 目录之外，也可以缩小攻击面。如果配置文件放在
Web 根目录下，攻击者就可能拿到它们，比如通过文件泄露漏洞。
而使用 Yaconf，可以把 <filename>.ini</filename> 文件放在只有
root 可读的目录里，例如 <filename>/etc/yaconf</filename>：
PHP-FPM master 进程在服务启动时加载配置，而实际处理 Web 请求的
worker 进程以普通用户身份运行，既不需要、也不会被授予对该目录的
访问权限。
</simpara>
<simpara>
Yaconf 需要 PHP 7.0 及以上版本。
</simpara>
</preface>

&reference.yaconf.setup;
&reference.yaconf.yaconf;

</book>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
36 changes: 36 additions & 0 deletions reference/yaconf/configure.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 9cfadc46e7d5a27ae5cc17430f3aa5fc5dc27a04 Maintainer: laruence Status: ready -->

<section xml:id="yaconf.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.install;

<para>
&pecl.info;
<link xlink:href="&url.pecl.package;yaconf">&url.pecl.package;yaconf</link>
</para>


</section>


<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
140 changes: 140 additions & 0 deletions reference/yaconf/ini.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 3b052562d228be18fa6dce221df7e375469fb7ad Maintainer: laruence Status: ready -->

<section xml:id="yaconf.configuration" xmlns="http://docbook.org/ns/docbook">
&reftitle.runtime;
&extension.runtime;
<para>
<table>
<title>Yaconf &ConfigureOptions;</title>
<tgroup cols="4">
<thead>
<row>
<entry>&Name;</entry>
<entry>&Default;</entry>
<entry>&Changeable;</entry>
<entry>&Changelog;</entry>
</row>
</thead>
<tbody>
<row>
<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.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>
</tbody>
</tgroup>
</table>
</para>

&ini.descriptions.title;

<para>
<variablelist>
<varlistentry xml:id="ini.yaconf.directory">
<term>
<parameter>yaconf.directory</parameter>
<type>string</type>
</term>
<listitem>
<simpara>
存放所有 INI 配置文件的目录。只有扩展名为
<filename>.ini</filename> 的文件会被加载。
子目录会被递归加载（最多 16 层深），每一级子目录都作为一级键
参与寻址：例如放在 <filename>users/</filename> 子目录下的
<filename>database.ini</filename> 文件，通过
<literal>"users.database"</literal> 访问。该特性自 Yaconf 1.2.0
起提供；在此之前，只有直接位于该目录下的文件会被加载。
</simpara>
<simpara>
下面的示例假定在配置的目录中放置了如下
<filename>database.ini</filename>，以及一个存放各功能开关设置的
<filename>features.ini</filename>。
</simpara>
<example>
<title>INI 文件语法</title>
<programlisting role="ini">
<![CDATA[
; database.ini
name=production ; scalar value
version=PHP_VERSION ; PHP constants are resolved
connection_string=${DATABASE_URL} ; environment variables are resolved
options.max_connections=50 ; nested hash key
options.timeout=30

; array entries, both notations are equivalent
replicas.0=replica-1.example.com
replicas[]=replica-2.example.com
]]>
</programlisting>
</example>
<example>
<title>INI section 示例</title>
<programlisting role="ini">
<![CDATA[
; features.ini
[default]
cache_enabled=on
rate_limit=100

; the "premium" section inherits every key from "default" and
; overrides the ones it redefines
[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>
Yaconf 检查已加载的 INI 文件是否发生变更、并重新加载变更文件的时间间隔，
单位为秒（通过比较目录的修改时间来检测变更）。将其设置为
<literal>0</literal> 时，Yaconf 会在每个请求时都进行检查。
</simpara>
<note>
<simpara>
该配置项只在非 ZTS 构建中注册。在 ZTS（线程安全）构建中，
配置仅在启动时加载，不支持自动重新加载；修改后需要重启 PHP
才能生效。
</simpara>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
99 changes: 99 additions & 0 deletions reference/yaconf/setup.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 3b052562d228be18fa6dce221df7e375469fb7ad Maintainer: laruence Status: ready -->

<chapter xml:id="yaconf.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;

<section xml:id="yaconf.requirements">
&reftitle.required;
<para>
Yaconf 需要 PHP 7.0 及以上版本。
</para>
</section>

<section xml:id="yaconf.installation">
&reftitle.install;
<simpara>
Yaconf 有三种安装方式：通过 PECL 安装、通过 PIE 安装，
或者从源码编译。
</simpara>
<para>
&pecl.moved;
</para>
<para>
&pecl.info;
<link xlink:href="&url.pecl.package;yaconf">&url.pecl.package;yaconf</link>.
</para>
<para>
&pecl.windows.download.avail;
</para>
<example>
<title>使用 PECL 安装 Yaconf</title>
<programlisting role="shell">
<![CDATA[
pecl install yaconf
]]>
</programlisting>
</example>
<simpara>
从 Yaconf 1.2.0 起，还可以使用扩展安装器 &link.pie;
（PHP Installer for Extensions）来安装，在命令行中执行：
</simpara>
<example>
<title>使用 PIE 安装 Yaconf</title>
<programlisting role="shell">
<![CDATA[
pie install laruence/yaconf
]]>
</programlisting>
</example>
<simpara>
源码托管在
<link xlink:href="&url.git.hub;laruence/yaconf">GitHub</link>
上。如需从源码编译安装，请在命令行中执行以下命令，
并将路径替换为本地 PHP 安装的实际路径：
</simpara>
<example>
<title>从源码编译 Yaconf</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;

<section xml:id="yaconf.resources">
&reftitle.resources;
<para>

</para>
</section>

</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
33 changes: 33 additions & 0 deletions reference/yaconf/versions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
<?xml version="1.0" encoding="utf-8"?>
<?do-not-translate?>
<!-- EN-Revision: 3b052562d228be18fa6dce221df7e375469fb7ad Maintainer: laruence Status: ready -->

<versions>
<!-- Classes and Methods -->

<function name='yaconf' from='PECL yaconf &gt;= 1.0.0'/>
<function name='yaconf::get' from='PECL yaconf &gt;= 1.0.0'/>
<function name='yaconf::has' from='PECL yaconf &gt;= 1.0.0'/>
<function name='yaconf::__debug_info' from='PECL yaconf &gt;= 1.1.0'/>
</versions>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Loading