Setting up a documentation environment
This appendix describes how to check out, build and view the PHP documentation locally.
Viewing results as a php.net mirror isn't a simple process, but it can be done. The following is one route, and it assumes:
- PHP 7.2+, with the following extensions enabled: DOM, libXML2, XMLReader, and SQLite3
- Git version control system is available
- A basic level of shell/terminal usage, or know that shell commands follow a
If you're interested in simply setting up a local PHP mirror (and NOT build the documentation) then please follow the php.net mirroring guidelines and ignore this document.
Checkout the php documentation from Git
Assumptions: A working directory
phpdoc is created and will contain the necessary cloned repositories. This tutorial will reference the directories that repositories are cloned into. Adjust as needed, including paths, especially if you are on Windows. This tutorial will clone at least three repositories:
- doc-en (into the
If setting up a local php.net mirror is desired, the
web-php repository must also be cloned. This is explained in the Set up a local php.net mirror section.
doc-en is cloned into the
en directory below.
$ mkdir phpdoc $ cd phpdoc $ git clone https://github.com/php/doc-en.git en $ git clone https://github.com/php/doc-base.git
Validate the PHP Documentation XML
$ php doc-base/configure.php
configure.php will check and validate the XML according to the Docbook specification. If you receive an error message: resolve the error message and try running the configure.php script again. If you see an ASCII cat, your XML is valid.
Build the documentation
We use PhD to build the documentation. It takes the source that
configure.php generates, and builds
and formats the PHP documentation. PhD offers several formats including HTML (multiple or single page),
PDF, Man, Epub, and others, including PHP which is what we use at php.net.
$ git clone https://github.com/php/phd.git $ php phd/render.php --help
Use PhD to build the documentation
As previously stated, there are multiple formats PhD can build the docs, but the two most commonly used for checking changes are XHTML and PHP. Building the docs into PHP requires a web server to view the pages, whereas XHTML does not. For small changes, building docs into XHTML is likely preferable. An example of a small change is modifying one file.
$ php doc-base/configure.php $ php phd/render.php --docbook doc-base/.manual.xml --package PHP --format xhtml $ open output/php-chunked-xhtml/function.strlen.html
However, if you wish to view the docs in an environment that closely resembles php.net, or wish to host a local mirror, the docs should be built in PHP format.
$ php doc-base/configure.php $ php phd/render.php --docbook doc-base/.manual.xml --package PHP --format php
During the rendering process, PhD creates an
output directory and builds the PHP manual files into a
php-web directory inside of
Note: This builds the php.net version of the documentation, but does not include the necessary files to run php.net. In other words, files like the php.net headers and footers are not built by PhD and are instead stored in a separate git module (web-php).
Set up a local php.net mirror
Clone the php.net sources
$ git clone https://github.com/php/web-php.git
Symlink (or move) the generated PHP documentation to your local php.net sources
$ cd web-php/manual $ rm -rf en $ ln -s ../../output/php-web en
Symlinking can also be done on Windows. Just make sure you run
cmd as Administrator.
$ cd \your\path\to\web-php\manual\ $ rmdir /S en $ mklink /D en \your\path\to\output\web-php
Run a webserver
We are going to use PHP's built-in web server. Please open another terminal instance for this task.
$ cd phpdoc/web-php $ php -S localhost:8080 .router.php
View the new site
Open http://localhost:8080/manual/en/ in your browser.