The PHP manual currently contains documentation for both PHP itself and numerous independently maintained third-party extensions.
While these extensions are maintained outside of php-src, their documentation is maintained within the official PHP documentation repositories and infrastructure. This creates ambiguity regarding ownership and maintenance responsibilities for documentation quality, issue triage, translations, and technical correctness.
This RFC proposes separating third-party extension documentation from the official PHP manual while continuing to use the existing documentation tooling and infrastructure.
For the purposes of this RFC:
php-src repository (e.g., ext/pdo, ext/reflection, ext/curl, ext/mbstring). These remain in the official PHP manual and are out of scope for this RFC.php-src, typically distributed via PECL, PIE or independently, whose documentation is currently hosted in the official PHP manual (e.g., imagick, redis, mongodb, memcached).This RFC proposes moving documentation for independently maintained third-party extensions out of the official PHP manual, while keeping the existing DocBook-based tooling and rendering infrastructure.
Specifically:
php-src.www.php.net/manual/. The specific location is subject to a secondary vote.php-src.
Bundled extensions such as ext/pdo, ext/reflection, and other extensions distributed as part of php-src are explicitly out of scope for this RFC and remain part of the official PHP manual.
The following extensions are currently documented in the official PHP manual but maintained outside php-src. This list is indicative and may be incomplete and will be finalized during implementation:
These extensions were previously bundled with php-src but have since been removed or moved to PECL. As they are no longer part of PHP itself, they fall under the same principle as other third-party extensions and will be migrated alongside them:
Where an extension has no active upstream maintainer, its documentation may be archived with a clear notice rather than handed off, at the discretion of the PHP documentation team.
Including third-party extensions within the official PHP manual creates ambiguity regarding whether an extension is officially part of PHP itself.
Separating third-party extension documentation makes it clearer to users that these extensions are independently maintained ecosystem projects rather than bundled PHP functionality.
Third-party extensions are maintained independently from PHP itself, but their documentation is currently maintained within the official PHP documentation repositories.
This creates unclear expectations regarding:
Separating third-party extension documentation aligns documentation ownership with extension maintainership.
Including third-party extensions in the official documentation repositories increases maintenance and translation burden for the PHP documentation team. Changes often take a long time to land because fact-checking them is difficult without owning the extension, and extension maintainers are not always responsive or may abandon the extension entirely.
Extension maintainers are generally the people most familiar with extension behavior and are therefore better positioned to maintain accurate documentation.
Third-party extension documentation will be hosted in a single monorepo, mirroring the structure of the existing doc-en repository. Each extension occupies its own subdirectory, and the repository uses the same DocBook-based tooling as the official manual.
Commit access may be granted to extension maintainers in addition to the PHP documentation team. Pull requests remain open to anyone, as with doc-en.
The migration is intended to be a lift-and-shift: documentation pages are moved one-to-one to the new location without content changes, restructuring, or rewrites. Once the infrastructure is in place, migrating an individual extension is a low-impact mechanical operation. Any content improvements are left to the respective extension maintainers after migration.
Migration will proceed in two phases:
For each migrated extension:
Many third-party extension pages have accumulated significant user notes (e.g., imagick with 407, memcache with 170, ds with 134).
The suggested approach is to remove notes rather than migrate them. Notes are frequently outdated, unverified, and often contain corrections or code snippets that would be better promoted into the canonical <example> block which are then properly maintained. Migrating notes would also require replicating the notes infrastructure at the new location and transfer a moderation burden to maintainers who have not opted into it.
Only the English (canonical) documentation is migrated. Existing translations in the official PHP manual will not be moved to the new location and will be removed from the official manual as part of the migration. Redirects from the previous translated URLs will point to the new English documentation where technically feasible.
Carrying translations over would require coordinating handoff with each translation team for each extension, and would re-introduce the coupling this RFC seeks to remove.
The intention is to minimize disruption for users by providing redirects from existing documentation URLs where technically feasible.
However, this RFC changes the location and workflow for maintaining third-party extension documentation. Documentation changes for third-party extensions will no longer be made through the official PHP documentation repositories.
Existing non-English translations will be removed; see Translations above for details.
Primary Vote requiring a 2/3 majority to accept the RFC:
Secondary Vote (simple majority, only counted if primary passes). If there's a tie, this will default to “contrib.php.net (subdomain)”:
Secondary Vote (simple majority, only counted if primary passes). If there's a tie, this will default to “Remove notes”:
Keep this updated with features that were discussed on the mail lists.
If there are major changes to the initial proposal, please include a short summary with a date or a link to the mailing list announcement here, as not everyone has access to the wikis' version history.
User Notes section and corresponding secondary vote, recommending removal in favor of promoting valuable content into <example> blocks.