• Version: 1.1
• Date: 2026-05-27
• Author: Jordi Kroon, jordikroon@me.com
• Status: Under Discussion
• Discussion thread: https://news-web.php.net/php.internals/131042
• Voting thread: TBD

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:

• Bundled extension: An extension whose source is distributed as part of the 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.
• Third-party extension: An extension maintained in a repository outside 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:

• The official PHP manual documents PHP itself and bundled extensions distributed as part of php-src.
• Independently maintained third-party extensions have their documentation hosted separately from the official PHP documentation.
• Third-party extension documentation continues to use the existing PHP documentation tooling and rendering infrastructure.
• Third-party extension documentation is hosted at a dedicated location, separate from www.php.net/manual/. The specific location is subject to a secondary vote.
• Responsibility for maintaining third-party extension documentation belongs to the extension maintainers themselves.
• New third-party extensions requesting documentation hosting use the dedicated third-party location. The official PHP manual no longer accepts documentation for extensions that are not part of php-src.
• Third-party extension documentation is maintained in English as the canonical language. Existing translations in the official manual are not carried over to the new location.
• If a third-party extension's documentation becomes unmaintained, the PHP documentation team may archive it with a clear notice on the previous location.

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:

• apcu + 8 notes
• cmark
• componere + 2 notes
• cubrid & pdo_cubrid
• dio + 10 notes
• ds + 134 notes
• eio
• ev + 95 notes
• event + 19 notes
• expect + 1 note
• fann + 16 notes
• fdf + 29 notes
• gearman + 55 notes
• gender + 2 notes
• geoip + 4 notes
• gmagick + 20 notes
• gnupg + 41 notes
• ibm_db2 & pdo_ibm + 7 & 3 notes
• igbinary + 1 note
• imagick + 407 notes
• inotify + 7 notes
• lua + 12 notes
• luasandbox + 1 note
• lzf
• mailparse + 25 notes
• memcache + 170 notes
• memcached + 90 notes
• mongodb + 66 notes
• mqseries + 1 note
• oauth + 15 notes
• openal + 2 notes
• parallel + 26 notes
• parle + 2 notes
• pdo_informix + 2 notes
• ps + 108 notes
• pthreads + 14 notes
• quickhash
• radius + 11 notes
• rar + 15 notes
• rnp
• rpminfo
• rrd + 10 notes
• runkit7
• scoutapm
• seaslog
• simdjson
• solr + 23 notes
• sqlsrv & pdo_sqlsrv + 23 & 3 notes
• ssdeep + 1 note
• ssh2 + 111 notes
• stats + 42 notes
• stomp + 7 notes
• svm + 7 notes
• svn + 22 notes
• swoole + 3 notes
• sync + 5 notes
• taint + 1 note
• tcpwrap
• trader + 37 notes
• ui + 100 notes
• uopz + 4 notes
• v8js + 9 notes
• varnish + 4 notes
• wincache + 16 notes
• wkhtmltox
• xattr + 2 notes
• xdiff + 4 notes
• xhprof + 7 notes
• xlswriter
• xmldiff + 2 notes
• xpass
• yac + 14 notes
• yaconf
• yaf + 25 notes
• yaml + 8 notes
• yar + 2 notes
• yaz + 11 notes
• zmq + 3 notes
• zookeeper

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:

• ibase (moved to PECL in 7.4)
• mcrypt (removed in 7.2)
• mysql (ext/mysql, removed in 7.0)
• recode (removed in 7.4)
• xmlrpc (moved to PECL in 8.0)

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:

• who maintains documentation quality,
• who reviews documentation changes,
• who triages issues,
• and who keeps documentation synchronized with extension releases.

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:

1. Infrastructure first: the target repository and hosting location are created and configured before any extension is moved.
2. Then per-extension: extensions are migrated one by one by the PHP documentation team. Extension maintainers are not required to perform the migration themselves.

For each migrated extension:

• Documentation sources are moved to the new repository.
• Related open issues are transferred where technically feasible.
• Related pull requests against third-party extension documentation in the official repositories will be closed with a pointer to the new location. Contributors are encouraged to resubmit against the new repository.
• Redirects from the existing manual URLs are configured.

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”:

• Example of a long-open PR: https://github.com/php/doc-en/pull/4669
• Short discussion regarding Third-party extensions: https://github.com/php/doc-en/pull/5583
• Translation status per language: https://doc.php.net/revcheck.php
• Discussion thread: https://news-web.php.net/php.internals/131042

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.

• 2026-06-02: Added User Notes section and corresponding secondary vote, recommending removal in favor of promoting valuable content into <example> blocks.