php手册
In this two-part article series, we’ll be covering how to contribute to the PHP project. This will hopefully clarify what steps need to be taken for those looking to become more involved with PHP.
在这个由两部分组成的文章系列中，我们将介绍如何为PHP项目做出贡献。 希望这将澄清那些希望更多地参与PHP的人们需要采取的步骤。
This first part will be covering how to contribute to PHP’s documentation, including how to request a php.net Account and what to do once an account has been granted.
第一部分将介绍如何为PHP的文档做出贡献，包括如何请求php.net帐户以及在授予帐户后如何进行操作。
Why should you consider contributing to PHP?
为什么要考虑为PHP做出贡献？
PHP is an open source project that relies upon the willingness of its community to invest their time into the project. The more people become involved, the more the community at large stands to benefit. Whether it’s improving the documentation around the language or contributing bug fixes or features to the core, the cumulative efforts of every developer quickly add up.
PHP是一个开源项目，它依赖于其社区愿意将时间投入到该项目中。 参与的人越多，整个社区将从中受益越多。 无论是改进有关该语言的文档，还是为核心提供错误修复或功能，每个开发人员的累加工作都会Swift加起来。
Becoming more involved with PHP will also help to take your knowledge of the language to the next level. Contributing to the documentation will give you a more thorough knowledge of the language, and contributing to the core will keep you up to date with any changes that are happening to it. Becoming a contributor will also enable you to ultimately request a php.net account, which will put you in a position to help decide what direction the language is heading in. It is therefore definitely a worthwhile thing to do, if you enjoy working with PHP.
越来越多地参与PHP也将有助于使您对该语言的了解达到更高的水平。 撰写文档将使您对语言有更全面的了解，而撰写核心则将使您随时了解最新的变化。 成为贡献者还可以使您最终请求一个php.net帐户，该帐户将使您能够确定语言的发展方向。因此，如果您喜欢使用PHP，那么这绝对是一个值得做的事情。
The documentation is maintained in the DocBook XML format. Generally speaking, little knowledge of this format is required to be able to contribute to PHP’s documentation. It’s easy to pick up, so you can simply follow along with the XML syntax used in other files of the documentation.
该文档以DocBook XML格式维护。 一般来说，对这种格式的了解很少，就能对PHP的文档做出贡献。 它很容易提取，因此您可以简单地遵循文档其他文件中使用的XML语法。
The folder structure for the documentation looks as follows:
该文档的文件夹结构如下所示：
The doc-base folder contains some tools for converting the XML-based documentation into other formats. You probably don’t need to concern yourself much with this folder, except when creating custom entities (typically used when adding external links to the docs).
doc-base文件夹包含一些工具，用于将基于XML的文档转换为其他格式。 除了创建自定义实体(通常在将外部链接添加到文档时使用)以外，您可能不需要太在意此文件夹。
The en folder is specific to the English documentation (other translations will follow their respective two letter country code names). This folder is the one you’ll predominantly be working in. The reference folder contains directories that each pertain to an extension. Each extension folder follows the convention of either having a functions folder (for procedural extensions) or folders named after the extension’s classes (for object-oriented extensions). Each extension folder also contains a few other files, including a book.xml file for the extension’s landing page and a versions.xml file for holding versioning information for when each function was introduced.
en文件夹特定于英语文档(其他翻译将使用其各自的两个字母的国家/地区代码名称)。 该文件夹是您主要使用的文件夹。 参考文件夹包含每个与扩展有关的目录。 每个扩展文件夹都遵循以下约定：具有一个功能文件夹(对于过程扩展)或以该扩展的类命名的文件夹(对于面向对象的扩展)。 每个扩展文件夹还包含一些其他文件，包括扩展的登录页面的book.xml文件和用于保存引入每个功能时的版本信息的versions.xml文件。
For more information on the documentation structure, see the Files structure section of the Manual sources structure page.
有关文档结构的更多信息，请参见“ 手动来源”结构页面的“ 文件”结构部分。
Also, while an on-going effort is being made to transition the documentation to Git, it is currently maintained using SVN. This means that you’ll need to install SVN and have a basic familiarity with it if you want to set the docs up locally (as seen later).
另外，尽管正在努力将文档过渡到Git，但目前仍使用SVN对其进行维护。 这意味着，如果您想在本地设置文档，则需要安装SVN并对其有基本的了解(如下所述)。
If you’re a first-time contributor, then you’ll want to start off by using the online documentation editor. This provides a user interface to enable anyone to log in (using OAuth) and to submit simple patches to the documentation. It’s generally best to log in with the same account each time, so that your contributions remain under a single name only (making it easier to track them if you decide to apply for a php.net account later).
如果您是初次撰稿人，那么您将希望使用在线文档编辑器开始 。 这提供了一个用户界面，使任何人都可以登录(使用OAuth)并向文档提交简单的补丁程序。 通常最好每次都使用相同的帐户登录，这样您的贡献就只能使用一个名字(如果您以后决定申请php.net帐户，则可以更轻松地跟踪他们)。
The online editor is almost always the starting point for new documentation contributors. By demonstrating the ability to submit patches and have them subsequently accepted, it shows competence and willingness to contribute.
在线编辑器几乎总是新文档贡献者的起点。 通过展示提交补丁并随后接受补丁的能力，它表明了能力和贡献的意愿。
As a first-time contributor, you’ll want to also familiarize yourself with the style guidelines of the documentation before submitting any patches.
作为首次贡献者，您还需要在提交任何补丁之前熟悉文档的样式指南 。
Let’s resolve bug #71716 from bugs.php.net. The report says that one of the demonstrative examples is incorrect, where the MongoDB Client class is namespaced incorrectly.
让我们从bugs.php.net解决bug＃ 71716 。 该报告说，其中一个示范示例是不正确的，其中MongoDB Client类的名称空间不正确。
After verifying this (by running the connection script locally), we can fix this using the online editor:
验证了这一点之后(通过在本地运行连接脚本)，我们可以使用在线编辑器解决此问题：
For more information on how to use the online editor, see the wiki editor’s Getting Started page.
有关如何使用在线编辑器的更多信息，请参见Wiki编辑器的“入门”页面 。
The online editor, however, isn’t the nicest of ways to contribute to the documentation and it is also very limited in what it can do. It should therefore only be used for minor edits and serve as a first stepping stone to getting involved in the documentation side of the project.
但是，在线编辑器并不是贡献文档的最好方法，而且它的功能也非常有限。 因此，仅应将其用于较小的编辑，并作为参与项目文档方面的第一步。
If you would like to do anything outside of the editor’s capabilities (such as documenting a function or extension from scratch), or you are becoming a frequent contributor to the docs, then you’ll want to set up the docs locally and request a php.net account.
如果您想执行编辑器功能之外的任何事情(例如从头开始记录功能或扩展名)，或者您正成为文档的经常撰稿人，那么您将需要在本地设置文档并请求php .net帐户。
Setting up the PHP docs locally on your computer is a one-time inconvenience. It can be done with the following steps:
在计算机上本地设置PHP文档是一种不便。 可以通过以下步骤完成：
Create a docs directory. This will be used to hold the docs and docs-related stuff in one place:
创建一个docs目录 。 这将用于将docs和与docs相关的东西放在一个地方：
mkdir phpdocs cd phpdocsThe rest of the steps all assume you are in the phpdocs directory, unless stated otherwise.
除非另有说明，否则其余所有步骤均假定您位于phpdocs目录中。
Clone the docs. Use SVN to pull down a copy of the repo. In our case, we are looking to get the English manual, and so we specify the doc-en module (at the end):
克隆文档 。 使用SVN下拉存储库的副本。 在本例中，我们希望获得英文手册，因此我们指定了doc-en模块(最后)：
svn checkout https : / / svn . php . net / repository / phpdoc / modules / doc - enClone PhD. PhD is a tool that renders the DocBook XML format into different output formats.
克隆博士 。 PhD是一种将DocBook XML格式呈现为不同输出格式的工具。
git clone http : / / git . php . net / repository / phd . gitClone the php.net website. This will be used to view the documentation locally, so that you can see the changes as they would appear on the website before pushing them.
克隆php.net网站 。 这将用于在本地查看文档，以便您可以像在网站上一样看到更改之前将其推送。
git clone http : / / git . php . net / repository / web / php . git web - php rm - fR web - php / manual / en ln - s rendered - docs / php - web web - php / manual / enWe need to remove the dummy docs located in web-php/manual/en, and then set up a symbolic link to here from the generated documentation files (generated via PhD) at rendered-docs/php-web.
我们需要删除位于web-php / manual / en中的虚拟文档，然后从render-docs / php-web的生成文档文件(通过PhD生成)中建立指向此处的符号链接。
Setup SVN Keywords. The DocBook files all have a <!-- $Revision: 338832 $ --> comment near the top of the file. We need to configure SVN to automatically update this value whenever a file changes by configuring its automatic properties. To do this, simply add the following line to ~/.subversion/config (the automatic properties part is somewhere near the end):
设置SVN关键字 。 DocBook文件的文件顶部附近都有一个<!-- $Revision: 338832 $ -->注释。 我们需要配置SVN以通过配置文件的自动属性来在文件更改时自动更新此值。 为此，只需~/.subversion/config添加到~/.subversion/config (自动属性部分在末尾附近)：
*.xml = svn:eol-style=native;svn:keywords=Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URLThe revision ID tracks file changes, which is used by docs translators to see which files need to be updated.
修订ID跟踪文件更改，文档翻译人员使用此修订来查看需要更新的文件。
Add workflow file. This is optional, but you’ll find it very useful to have the commands to validate, build, and view the docs locally at hand. Paste the following into a file called ref:
添加工作流文件 。 这是可选的，但您会发现手边有一些命令来验证，构建和查看文档非常有用。 将以下内容粘贴到名为ref的文件中：
# Validate the DocBook XML php ~ / phpdocs / doc - en / doc - base / configure . php # Build the docs php ~ / phpdocs / phd / render . php -- docbook ~ / phpdocs / doc - en / doc - base / . manual . xml -- package PHP -- format php -- output ~ / phpdocs / rendered - docs # Run the php.net website locally cd ~ / phpdocs / web - php php - S 0.0 . 0 . 0 : 4000The above assumes that your phpdocs folder is located in your home directory – if not, then update the paths accordingly.
上面的假设您的phpdocs文件夹位于您的主目录中-如果没有，则相应地更新路径。
And now you’re all set up!
现在，您已经完成所有设置！
With everything set up, it’s time to take a look at the workflow for contributing to the docs locally. For this, let’s resolve bug #71866.
完成所有设置后，是时候看看在本地为文档做出贡献的工作流程了。 为此，让我们解决错误＃71866 。
We start by making sure the versioned repos are all up-to-date. This means performing an svn up in doc-en/en and doc-en/doc-base, and a git pull in web-php and phd (typically, you’ll find that only the first repo, doc-en/en, needs to be updated).
我们首先要确保版本库是最新的。 这意味着在doc-en / en和doc-en / doc-base中执行svn up ，并在web-php和phd中进行git pull (通常，您会发现只有第一个存储库doc-en / en ，需要更新)。
Next, we open up the doc-en/en/reference/mbstring/functions/mb-detect-order.xml file and rectify the function’s return value description as per the bug report information:
接下来，我们打开doc-en/en/reference/mbstring/functions/mb-detect-order.xml文件，并根据错误报告信息纠正函数的返回值描述：
< refsect1 role = " returnvalues " > &reftitle.returnvalues; < para > - &return.success; + When setting the encoding detection order, &true; is returned on success or &false; on failure. + </ para > + < para > + When getting the encoding detection order, an ordered array of the encodings is returned. </ para > </ refsect1 >We then ensure that we haven’t broken the docs builds by running the docs validator:
然后，我们通过运行文档验证器确保未破坏文档构建：
php ~ / phpdocs / doc - en / doc - base / configure . phpThe docs should validate successfully, and as a result, we should see a picture of a nice ASCII cat.
文档应该成功验证，结果，我们应该看到一张漂亮的ASCII猫的图片。
Now, we can either view the changes locally or commit them. Typically, you will just want to commit the changes (unless you’ve made any drastic changes to confirm that they look fine), but we’ll do it this time for didactic reasons.
现在，我们可以在本地查看更改或提交更改。 通常，您只想提交更改(除非您进行了任何大刀阔斧的更改以确认它们看起来还不错)，但是出于教学原因，我们这次将这样做。
We build the documentation by running the PhD tool:
我们通过运行PhD工具来构建文档：
php ~ / phpdocs / phd / render . php -- docbook ~ / php - docs / doc - en / doc - base / . manual . xml -- package PHP -- format php -- output ~ / php - docs / rendered - docsSometimes this stage fails for me the first time because PHP runs out of memory – just simply re-run the command and it should build fine.
有时候，这个阶段对我来说第一次失败，因为PHP内存不足-只需简单地重新运行命令，它就可以正常运行。
Then change into the php.net website’s directory to start the local PHP server:
然后转到php.net网站的目录以启动本地PHP服务器：
cd ~ / phpdocs / web - php php - S 0.0 . 0 . 0 : 4000Visiting the localhost (on port 4000) and browsing to the mb_detect_order() function, we can see the changes made:
访问本地主机(在端口4000上)并浏览到mb_detect_order()函数，我们可以看到所做的更改：
Now that the changes have been made and we’re happy with them, we can commit them. The following parts assume that you have a php.net account. If that’s not the case, then you need not concern yourself with the rest of this section just yet (instead, you may wish to request a php.net account (see below).
现在已经进行了更改，我们对它们感到满意，我们可以提交它们。 以下部分假定您拥有一个php.net帐户。 如果不是这种情况，那么您就不必担心本节的其余部分(相反，您可能希望请求一个php.net帐户(请参见下文)。
cd ~/phpdocs/doc-en/en svn ci -m "Resolve doc bug #71866" reference/mbstring/functions/mb-detect-order.xmlThe commit message references the doc bug so that an automated comment on our behalf can be made on the bug report we’re resolving. You also won’t be able to view your changes right away on php.net, but they should propagate to the servers within a few hours typically. We can then visit bug #71866, and, assuming we’re logged into our php.net account, navigate to the “Developer” tab and close the bug report.
提交消息引用了文档错误，因此可以代表我们在我们要解决的错误报告中进行自动注释。 您也将无法立即在php.net上查看您的更改，但是这些更改通常应在几个小时内传播到服务器。 然后，我们可以访问错误＃71866 ，并假设我们已登录php.net帐户，请导航至“开发人员”标签并关闭错误报告。
That’s the basic workflow of resolving documentation bugs. Quick and easy!
这是解决文档错误的基本工作流程。 快捷方便！
Having set the docs up locally and seen the general workflow, you may then want to consider requesting a php.net account with docs karma. (Karma gives contributors differing privileges for various parts of the PHP project. In order to contribute directly to the documentation, docs karma is required on your php.net account.)
在本地设置文档并查看常规工作流程后，您可能想要考虑使用docs karma请求php.net帐户。 (业力为贡献者提供了对PHP项目各个部分的不同特权。为了直接对文档做出贡献，您的php.net帐户需要docs业力。)
There are no concrete prerequisites that must be met prior to requesting a php.net docs account. Generally, though, accounts will only be granted to those who are looking to actively contribute to and maintain the documentation. Past contributions and current efforts are therefore looked at as evidence of competence and willingness to contribute when requesting an account.
要求php.net docs帐户之前，没有必须满足的具体先决条件。 通常，尽管如此，帐户只会授予希望积极贡献和维护文档的人员。 因此，过去的捐助和当前的努力被视为证明有能力和愿意在提出账户时作出贡献的证据。
To request an account, visit the account request page and read it carefully. Then, fill out the form, submit it, and then email the PHP docs mailing list (phpdoc@lists.php.net) stating why you would like karma, what your wiki account username is, and reference any past contributions you’ve made to the project. If your request is successful, then you’ll be granted a @php.net account.
要请求帐户，请访问帐户请求页面并仔细阅读。 然后，填写表格，提交，然后通过电子邮件发送到PHP docs邮件列表(phpdoc@lists.php.net)，说明您为什么想要业力，您的Wiki帐户用户名是什么，并参考您过去所做的任何贡献到项目。 如果您的请求成功，那么您将被授予@ php.net帐户。
Aside from fixing the numerous filed bug reports on the documentation, there are other areas of the manual that could be worked on too, including:
除了修复文档中大量已提交的错误报告外 ，手册的其他领域也可以进行处理，包括：
Translating the documentation
翻译文档
Expanding upon the partially documented material (typically by adding examples) – the reflection extension is a prime example of this. 扩展部分记录的材料(通常通过添加示例)–反射扩展是此的主要示例。Documenting the undocumented – this will involve digging into the PHP source code using the lxr tool
记录未记录的文档–这将涉及使用lxr工具深入研究PHP源代码
General page tidy-ups – rephrasing parts (such as removing any “you”s), removing PHP 4-related material, merging useful comments into the manual itself, etc. 常规页面整理–更改部分内容(例如删除任何“ you”)，删除PHP 4相关材料，将有用的注释合并到手册本身等。The following are some tips on contributing, some based on my experience, and others simply reiterating from above because they are important:
以下是一些有关贡献的技巧，一些基于我的经验，而其他一些则因其重要而从上面反复重申：
Follow the style guidelines. Please make sure you’re following the style guidelines, and when contributing, try to rectify documentation that doesn’t follow it. I generally perform at least a quick search for “I ” and “you” in the file I’m working on.
遵循样式准则 。 请确保您遵循样式指南 ，并且在贡献样式时，请尝试纠正不遵循样式指南的文档。 通常，我通常至少在要处理的文件中快速搜索“ I”和“您”。
Check tangential things. This generally refers to resolving bug reports – don’t just fix the bug, check that related things aren’t affected too. This helps to ensure that bugs are properly resolved. For example, whilst bug #71638 only referenced the stream_filter_append function, its counterpart stream_filter_prepend also needed to be rectified.
检查切线的东西 。 这通常是指解决错误报告–不仅要修正错误，还要检查相关内容是否也没有受到影响。 这有助于确保错误得到正确解决。 例如，尽管错误＃71638仅引用了stream_filter_append函数，但其对应的stream_filter_prepend也需要纠正 。
Be terse. This applies to both writing and code examples. Poorly worded documentation and convoluted code examples make things more difficult to understand. Keep things short and simple.
简洁一点 。 这适用于编写示例和代码示例。 措辞不佳的文档和繁琐的代码示例使事情变得更难以理解。 让事情简短明了。
Separate example code from its output. Make sure the output of examples is not put with the examples themselves. This convention helps to keep the example clean and clearly shows its output. For example, when cleaning up the token_get_all function page, I had to move a commented dump of a variable and an explanation out of the example.
将示例代码与其输出分开 。 确保示例的输出未与示例本身放在一起。 此约定有助于使示例保持简洁并清楚地显示其输出。 例如，当清理token_get_all函数页面时，我不得不将注释的转储变量和解释移到示例之外 。
Check the page order. Ensure that the order of content on the page is correct. This creates consistency in the manual, which enables developers to reference it easier. Again, looking at the cleaning up of the token_get_all function, we can see that the changelog section was initially at the bottom of the page, when it should have been above the examples section.
检查页面顺序 。 确保页面上内容的顺序正确。 这在手册中建立了一致性，使开发人员可以更轻松地引用它。 再次，看一下token_get_all函数的清理 ，我们可以看到changelog部分最初位于页面底部，而本来应该位于examples部分之上。
Remove references to PHP 4. PHP 4 is long gone, and references to it are not only irrelevant now, but they convolute the documentation. Look out for any mentions of PHP 4 (I usually perform a quick grep for it in the file I’m working on) and remove any mentions of it.
删除对PHP 4的引用 。 PHP 4早已一去不复返了，对它的引用不仅不再相关，而且使文档复杂化。 留意任何有关PHP 4的提及(我通常会在正在处理的文件中对其进行快速grep删除)，并删除所有提及的内容。
Properly version files. When creating a new file in the documentation, ensure that its revision id is set to nothing:
正确版本文件 。 在文档中创建新文件时，请确保其修订ID设置为none：
<!-- $Revision$ -->(Example.)
( 示例 。)
Other than when creating new files or translating the documentation, you will not need to worry about the revision ID.
除了创建新文件或翻译文档时，您无需担心版本ID。
If you’re unsure about something, start by checking out the docs FAQ. If that doesn’t help, then simply send an email to the php-docs mailing list for support.
如果不确定某件事，请先查看docs FAQ 。 如果这样做没有帮助，则只需将电子邮件发送到php-docs邮件列表以寻求支持。
And just to reiterate, please check that the documentation build passes before committing any changes to the manual!
重申一下，在对手册进行任何更改之前，请检查文档版本是否通过！
We’ve seen two workflows in this article when contributing to PHP’s documentation. The first was using the online editor to resolve bug #71716, and the second was using a local setup of the docs to resolve bug #71866. I hope this has served as a clear and pragmatic introduction on how to contribute to PHP’s documentation.
在编写PHP文档时，我们已经在本文中看到了两个工作流程。 第一个是使用在线编辑器来解决bug＃71716 ，第二个是使用文档的本地设置来解决bug＃71866 。 我希望本文对如何为PHP文档做出贡献提供了清晰而务实的介绍。
In part 2 of this series, I will be showing you how to get involved with PHP’s internals. This will involve looking at how to fix bugs in the core by taking a pragmatic approach again.
在本系列的第2部分中，我将向您展示如何参与PHP的内部。 这将涉及再次采取务实的方法来研究如何修复内核中的错误。
翻译自: https://www.sitepoint.com/how-to-contribute-to-phps-documentation/
php手册
相关资源：PHP完全自学手册