php/doc-en: the English PHP manual as DocBook XML

The manual as a source tree, not as a website

The repository is titled PHP Documentation and the repository description is simply English PHP documentation. The primary language is recorded as XML, which is the first thing to understand about it: this is not a website repository with a build step bolted on, it is a DocBook source tree from which the website is produced.

The published manual is what most people know, at php.net/docs. This repository is where that text comes from. The top-level layout is the manual's own structure, with directories for `chapters/`, `reference/`, `faq/`, `install/`, `features/`, `language/`, `security/` and `appendices/`, alongside `entities/` for the shared entity definitions, `chmonly/` for the changelog material, and the top-level files that make up the book itself, `manual.xml`, `bookinfo.xml`, `preface.xml`, `contributors.xml` and `docbookcs.xml`. There is also `language-snippets.ent` and a `make_chm_index.html` for the compiled help format.

That layout explains the scale of the project and the shape of any contribution. A change to the manual is a change to an XML file in one of those directories, reviewed by people who know the conventions.

The README itself is short and points elsewhere for the rules. It refers to the contribution guidelines and the README file in the doc-base repository for details on how to contribute to PHP's documentation, and it points at the tutorial on local setup on the documentation website for creating the setup.

The build runs in Docker, with your user id baked in

The build is a Makefile that drives Docker, and the README gives the three-step version: install Docker, rebuild the documentation using `make`, and open output/php-chunked-xhtml/ in your browser.

The interesting detail is in the Makefile rather than the prose. The container is run as the invoking user rather than as root, which is why the makefile captures the current uid and gid at the top:

CURRENT_UID := $(shell id -u)
CURRENT_GID := $(shell id -g)

and passes them to both the image build and the run:

xhtml: .docker/built
	docker run --rm ${PATHS} -w /var/www -u ${CURRENT_UID}:${CURRENT_GID} php/doc-en

Without that, the generated files inside the container would be owned by root on the host, and a documentation writer running an editor on those files would hit permission problems on every save. It is a small thing that shows the project has been used by more than one person.

There is a second detail about the image. The `xhtml` target depends on `.docker/built`, which is a stamp file created after the image is built, so the image is built once and reused. The README explains how to force a rebuild of the Docker image itself, by running `make -B build`, otherwise the Makefile will only build it if it does not already exist.

Two output shapes, chunked XHTML and a web manual

The makefile exposes two build targets and they produce different artefacts.

The default `xhtml` target produces the chunked manual, which is what you open in a browser after a build, in output/php-chunked-xhtml/. The `php` target produces the web version, with the output placed in output/php-web, and the difference is a single environment variable passed into the container:

php: .docker/built
	docker run --rm ${PATHS} -w /var/www -u ${CURRENT_UID}:${CURRENT_GID} \
		-e FORMAT=php php/doc-en

So the same image and the same sources render either way, and the FORMAT variable selects the renderer inside it. The chunked form is the manual as a set of pages with a navigation frame, and the web form is the layout the online manual uses.

That is a good design for a project of this size. The content does not change, only the output shape, and both shapes come from the same container image, so there is no second set of build instructions to keep in step.

The Makefile also declares `.PHONY = *`, which tells make that every target is considered out of date. For a repository where the real inputs are XML files that make cannot see through the container boundary, that is the safe choice, since it prevents make from deciding that a target is up to date when the underlying content has changed.

doc-base and phd get mounted in when they sit next to the tree

The build has an optional dependency on two sibling repositories, and the way it is wired is worth reading closely.

The Makefile starts with the working directory mounted at /var/www/en, and then conditionally adds two more volumes if the sibling directories exist:

PATHS := -v ${PWD}:/var/www/en
ifneq ($(wildcard ../doc-base/LICENSE),)
	PATHS += -v ${PWD}/../doc-base:/var/www/doc-base
endif
ifneq ($(wildcard ../phd/LICENSE),)
	PATHS += -v ${PWD}/../phd:/var/www/phd
endif

The check is for a LICENSE file in the sibling directory, so the presence of the repository is what decides, and the mount is invisible in the result unless you know to look.

The two mounted projects are the ones the documentation pipeline is built from. doc-base is where the contribution guidelines, the README and the pipeline overview live, and the README links the overview of the various repositories that make up PHP's documentation pipeline. phd is the tool that turns DocBook into the HTML and PDF formats.

The practical effect is that a contributor who clones only this repository gets a build that works on the manual alone, and a contributor who has doc-base and phd checked out beside it gets a build that uses them. That is a reasonable arrangement, and it does mean the build behaves differently depending on what happens to be on your disk, which is worth knowing before you conclude that a build is broken.

Thirteen translations follow the English source

The Translations section lists the sibling repositories, and the list is the clearest statement of how the documentation project is organised.

Alongside English there are Brazilian Portuguese in doc-pt_br, Simplified Chinese in doc-zh, French in doc-fr, German in doc-de, Italian in doc-it, Japanese in doc-ja, Polish in doc-pl, Romanian in doc-ro, Russian in doc-ru, Spanish in doc-es, Turkish in doc-tr and Ukrainian in doc-uk. Thirteen languages in total, each in its own repository rather than as branches or directories of this one.

The separate-repository arrangement is the point. Each translation can have its own maintainers, its own pace and its own tooling, and the English repository stays the single source of truth for the content. The cost is that a change to the structure of the manual has to be reflected across all thirteen, and the README here does not explain how the translation repositories are kept in step with it.

The documentation pipeline overview linked at the end of the README is where that question is answered, and it is the document to read if you are thinking about contributing to the manual or to a translation rather than just reading it.

The XML layout follows the manual's own table of contents

The top-level entries describe both the content and the conventions, and a few of them are worth calling out for anyone who wants to contribute.

`CODEOWNERS` is at the root, which means the repository treats review as something to be assigned rather than requested. `.gitleaks.toml` is also there, so secrets are scanned for, which is a sensible thing in a repository that carries example code and configuration fragments from a wide range of extension projects.

The `.docker` directory holds the Dockerfile the makefile builds, and `.devcontainer` holds a development container definition, which is how you get a working environment without assembling the toolchain by hand. The README points at a local setup tutorial on the documentation website for the same purpose.

The remaining root files are the book metadata. `bookinfo.xml` carries the title and publication data, `preface.xml` the front matter, `contributors.xml` the list of people who wrote the manual, and `docbookcs.xml` the character set declaration that makes a non-ASCII manual build correctly. `language-snippets.ent` holds shared snippets, and `make_chm_index.html` is the index for the compiled help output.

Put together, the repository is a DocBook project with a Docker-based, containerised build, a translation pipeline and a contribution process that lives in doc-base rather than here. The one thing the README does not tell you is how to submit a change, and that is deliberate, because the answer is in the guidelines it links three times.

Editorial conclusion

php/doc-en fits a PHP developer or writer who wants to read the manual in source form, patch a page, or understand how the official documentation is produced and translated. It is the wrong tool if you need a searchable API reference, since the published manual at php.net/docs is the artefact meant for that. Verify first which doc-base and phd repositories you want mounted, since the build silently changes behaviour when they sit next to the tree, and read the contribution guidelines in php/doc-base before opening a pull request against the manual.

Frequently asked questions

Official sources

1. Issues
2. php/doc-en on GitHub
3. README