You can easily contribute to the PHP documentation by either reporting a bug or by fixing one by submitting a pull request. As all the repositories are hosted on GitHub, you will need a GitHub account to do either of these.
If you have found a bug on any of the PHP documentation pages, you can file a bug report by doing the following:
- click the "Report a Bug" link in the "Improve This Page" section on the bottom of the page
- log into GitHub
- add a short description of the bug in the title textbox
- add all necessary details to the description textarea
- click the "Submit new issue" button to file your bug report
There are two ways to make changes to the documentation:
- make minor changes by editing files on GitHub
- make more complex changes and validate/build the documentation locally on your computer
To make trivial changes (typos, shorter wording changes or adding/removing short segments) all one needs is a web-browser and a GitHub account and doing the following:
- click the "Submit a Pull Request" link in the "Improve This Page" section on the bottom of the documentation page
- log into GitHub
- fork the repository (if you have not forked it already)
- make changes
- click the "Commit changes" button
- add a commit message (short description of the change) into the "Commit message" textbox
- write a longer description in the "Extended description" textarea, if needed
- click the "Propose changes" button
- review your changes and click "Create pull request" button
The repository will run a few basic checks on the changes (e.g. whether the XML markup is valid, whether trailing whitespaces are stripped, etc.) and your PR is ready to be discussed with and merged by the maintainers.
To build and view the documentation after making more extensive changes (e.g. adding entire sections or files), you will need to clone some of the tooling (doc-base, phd and possibly web-php) in addition to the language repository you want to make the changes to. You need to validate the changes and you can (but do not have to) render the documentation before you open a PR.
If you'd like to know more about what each repository is and/or how PHP's documentation is built please refer to this overview.
Following this guide to make changes to and build the documentation has the following dependencies:
- PHP 8.0+ with the DOM, libXML2, XMLReader and SQLite3 extensions
- Git
- an IDE or a text editor
To start working on the English documentation, you need to fork it on Github and clone it, doc-base (for validating the XML files) and PhD (for rendering the files).
git clone https://github.com/<your_github_username>/<your_fork> en
git clone https://github.com/php/doc-base
git clone https://github.com/php/phd
cd en
git remote add upstream https://github.com/php/doc-en
where <your_github_username>
and <your_fork>
needs to be replaced by
your GitHub username and the name of your for of the English documentation respectively.
Please note that the English documentation has to be cloned into the en
directory.
To clone any of the translations, replace doc-en en
at the end of the first line
with the translation you would like to clone
(e.g. doc-pt_br
for the Brazilian documentation).
As an example, the following shows how to set up the Brazilian documentation:
git clone https://github.com/<your_github_username>/doc-pt_br
git clone https://github.com/php/doc-base
git clone https://github.com/php/phd
cd doc-pt_br
git remote add upstream https://github.com/php/doc-pt_br
where <your_github_username>
needs to be replaced by your GitHub username.
List of languages/repositories
If you would like to setup a local mirror of the documentation or you would just like to see how your changes will look like online:
git clone https://github.com/php/web-php
cd web-php/manual
rm -rf en
ln -s ../../output/php-web en
where ../../output/php-web
is the directory the PhD generated .php files are saved at,
relative to the web-php/manual
directory.
On Windows:
git clone https://github.com/php/web-php
cd \your\path\to\web-php\manual\
rmdir /S en
mklink /D en \your\path\to\output\web-php
where \your\path\to\output\web-php
is the directory the PhD generated .php files are saved at,
relative to the \your\path\to\web-php\manual\
directory.
You can view the documentation by using any web server but one of the simplest ways is to use PHP's built-in web server:
cd web-php
php -S localhost:8080 .router.php
where web-php
is the directory web-php has been cloned into.
The manual is now available from http://localhost:8080/manual/en/ in your browser.
Make your changes keeping in mind the style guidelines.
To validate the English documentation (located in the directory en
), run
php doc-base/configure.php
To validate any other documentation, run
php doc-base/configure.php --with-lang=doc-lang
where doc-lang
is the name of your language's repository
and the corresponding directory (eg. doc-de
for German).
Please note that all validation errors have to be corrected before opening a PR.
To render the documentation in xhtml format (can be viewed without a web server), run
php phd/render.php --docbook doc-base/.manual.xml --package PHP --format xhtml
To render the documentation in php format (needs a web server and web-php), run
php phd/render.php --docbook doc-base/.manual.xml --package PHP --format php
- commit your changes
- push to your fork
- open a PR in the appropriate language repository
Once you open a PR, the documentation repository will run a few basic checks on the changes (e.g. whether the XML markup is valid, whether trailing whitespaces are stripped, etc.) and your PR is ready to be discussed with and merged by the maintainers.
For additional information on contributing to the documentation refer to:
- the Adding new documentation section of the "Editing manual sources" page
- the Files structure section of the "Manual sources structure" page
- the Translating documentation page
- the Style guidelines page
- the FAQ page
- the Why we care about whitespace page
- doc-base's README