PHP: rfc:third_party_ext_documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Separation of Third-Party Extension Documentation ======
  * Version: 0.9
  * Date: 2026-05-27
  * Author: Jordi Kroon, jordikroon@me.com
  * Status: Draft
  * Implementation: TBD
  * Discussion thread: https://news-web.php.net/php.internals/…
  * Voting thread: TBD

===== Introduction =====

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.

====== Definitions ======

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'', ''xdebug'', ''memcached'').

===== Proposal =====
Accept a policy to separate documentation for independently maintained third-party extensions from the official PHP manual.

To summarize the policy from a high-level perspective, the policy specifies:
  * That the official PHP manual documents PHP itself and bundled extensions distributed as part of ''php-src''.
  * That independently maintained third-party extensions should maintain their documentation separately from the official PHP manual repositories.
  * That third-party extension documentation may continue to use the existing PHP documentation tooling and rendering infrastructure.
  * That third-party extension documentation will be hosted at a dedicated location, separate from ''www.php.net/manual/''. The specific location is subject to a secondary vote.
  * That responsibility for maintaining third-party extension documentation belongs to the extension maintainers themselves.
  * That third-party extension documentation will be maintained in English as the canonical language. Translations are at the discretion of individual extension maintainers and are not the responsibility of the PHP documentation team.
  * That if a third-party extension's documentation becomes unmaintained, the PHP documentation team reserves the right to 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.

==== Extensions Affected ====

The following extensions are currently documented in the official PHP manual but maintained outside ''php-src''. This list is indicative and will be finalized during implementation:

==== Extensions Affected ====

The following extensions are currently documented in the official PHP manual 
but maintained outside ''php-src''. This list is indicative and will be 
finalized during implementation.

=== Third-party extensions ===

  * apcu
  * cmark
  * componere
  * cubrid / pdo_cubrid
  * dio
  * ds
  * eio
  * ev
  * event
  * expect
  * fann
  * fdf
  * gearman
  * gender
  * geoip
  * gmagick
  * gnupg
  * ibm_db2 / pdo_ibm
  * igbinary
  * imagick
  * inotify
  * lua
  * luasandbox
  * lzf
  * mailparse
  * memcache
  * memcached
  * mongodb
  * mqseries
  * oauth
  * openal
  * parallel
  * parle
  * pdo_informix
  * ps
  * pthreads
  * quickhash
  * radius
  * rar
  * rnp
  * rpminfo
  * rrd
  * runkit7
  * scoutapm
  * seaslog
  * simdjson
  * solr
  * sqlsrv / pdo_sqlsrv
  * ssdeep
  * ssh2
  * stats
  * stomp
  * svm
  * svn
  * swoole
  * sync
  * taint
  * tcpwrap
  * trader
  * ui
  * uopz
  * v8js
  * varnish
  * wincache
  * wkhtmltox
  * xattr
  * xdiff
  * xhprof
  * xlswriter
  * xmldiff
  * xpass
  * yac
  * yaconf
  * yaf
  * yaml
  * yar
  * yaz
  * zmq
  * zookeeper

=== Extensions removed from php-src but still documented ===

These extensions were previously bundled but have since been removed or moved 
to PECL. Their documentation will be migrated together with the active 
third-party extensions, unless decided to archive 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)

===== Motivation =====
==== Clear Separation Between PHP and Third-Party Extensions ====

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.

==== Responsibility Alignment ====
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.

==== Documentation Maintenance Burden ====
Including third-party extensions in the official documentation repositories increases maintenance and translation burden for the PHP documentation team. 
Changes often take long 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.

===== Backward Compatibility =====
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.

===== Migration Path =====

Migration will proceed in two phases:

  - **Infrastructure first**: the target repository and hosting location are created and configured before any extension is moved.
  - **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 and pull requests are transferred where technically feasible.
  * Redirects from the existing manual URLs are configured.

===== Voting Choices =====

Primary Vote requiring a 2/3 majority to accept the RFC:

<doodle title="Move third-party extension documentation out of the official PHP manual?" voteType="single" closed="true" closeon="2026-01-01T15:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

Secondary Vote (simple majority, only counted if primary passes):
<doodle title="Where should third-party documentation be hosted?" 
        voteType="single" ...>
   * contrib.php.net (subdomain)
   * www.php.net/manual/extensions/ (subpath)
</doodle>

===== Patches and Tests =====
Links to proof of concept PR.

If there is no patch, make it clear who will create a patch, or whether a volunteer to help with implementation is needed.

===== Implementation =====
After the RFC is implemented, this section should contain:
  - the version(s) it was merged into
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature

===== References =====
Links to external references, discussions, or RFCs.

===== Rejected Features =====
Keep this updated with features that were discussed on the mail lists.

===== Changelog =====
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.
Page Tools
