Hello,
I've opened an RFC to separate third-party extension documentation
(imagick, redis, mongodb, etc) from the official PHP manual, while
keeping the existing DocBook tooling and infrastructure.
Bundled extensions (pdo, curl, etc) are out of scope and stay in the
official PHP manual.
https://wiki.php.net/rfc/third_party_ext_documentation
--
Regards,
Jordi Kroon
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.
Only the English (canonical) documentation is migrated.
...
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.
I don't understand what the problem with translations. What is so special
about english that it can be lift-and-shifted, but other languages cannot?
What specific coordination is required from the translation team?
I don't understand what the problem with translations. What is so
special about english that it can be lift-and-shifted, but other
languages cannot? What specific coordination is required from the
translation team?
Translations could be lift-and-shifted the same way English can. The
asymmetry is about responsibility after migration, not the migration
itself.
A few concrete points:
- Translations track the English version via revision hashes, so they
depend on the English source. English is canonical; while the other
languages are downstream of it. - A majority of translations have less than 50% coverage
(https://doc.php.net/revcheck.php). - The whole point of the RFC is to hand documentation responsibility
to the extension maintainers. That works for English because English
is the de facto language. It does not work for the other languages.
We can't reasonably assume an extension maintainer is fluent in
German, French, Japanese, etc. - Structurally, carrying translations over would mean one contrib
repository per language, mirroring the current doc-en / doc-de /
doc-fr / doc-ja / etc. So the overhead the RFC is trying to
reduce would be reproduced in the new location. - It is already difficult to keep a single language in sync with
extension releases. Asking extension maintainers to keep N languages
in sync. Languages that the extension maintainer can't read or
understand. Thus a language the extension maintainer can't verify
the contents of.
--
Regards,
Jordi Kroon
Hello,
I've opened an RFC to separate third-party extension documentation
(imagick, redis, mongodb, etc) from the official PHP manual, while
keeping the existing DocBook tooling and infrastructure.Bundled extensions (pdo, curl, etc) are out of scope and stay in the
official PHP manual.
I'm fully in support of this RFC.
Having maintained the docs for multiple years, the burden and frustration both for end users and doc maintainers to try and find who the maintainer (or even just the location of the sources) of an extension to be able to get clarifications usually results in long wait times, or never receiving a response.
This means that the high standards we try to have for the PHP documentation are not evenly applied, nor can they, as the expertise doesn't exist within the core doc and php-src team.
Moreover, it has been tradition to just remove unmaintained extensions from the doc sources after an archive has been made.
Best regards,
Gina P. Banyard
Hello,
I've opened an RFC to separate third-party extension documentation
(imagick, redis, mongodb, etc) from the official PHP manual, while
keeping the existing DocBook tooling and infrastructure.Bundled extensions (pdo, curl, etc) are out of scope and stay in the
official PHP manual.https://wiki.php.net/rfc/third_party_ext_documentation
--
Regards,Jordi Kroon
I support this. Having first-party extensions and seemingly abandoned third party extensions in the same list has always struck me as very misleading. Just the benefit for documentation readers alone makes it worth it, IMO.
Question: What about comments on any of the to-be-moved pages? My vote would be to just nuke them from orbit in the process, as manual comments have about a 1% "usefulness" rate. In fact I'd be completely on board with not enabling comments on the contrib-docs built at all and making it strictly readonly, with links to GitHub if someone is in a contributing mood.
--Larry Garfield
Hello,
I've opened an RFC to separate third-party extension documentation
(imagick, redis, mongodb, etc) from the official PHP manual, while
keeping the existing DocBook tooling and infrastructure.Bundled extensions (pdo, curl, etc) are out of scope and stay in the
official PHP manual.https://wiki.php.net/rfc/third_party_ext_documentation
--
Regards,Jordi Kroon
I support this. Having first-party extensions and seemingly abandoned third party extensions in the same list has always struck me as very misleading. Just the benefit for documentation readers alone makes it worth it, IMO.
Question: What about comments on any of the to-be-moved pages? My vote would be to just nuke them from orbit in the process, as manual comments have about a 1% "usefulness" rate. In fact I'd be completely on board with not enabling comments on the contrib-docs built at all and making it strictly readonly, with links to GitHub if someone is in a contributing mood.
--Larry Garfield
In my opinion, having comments on a language documentation site is an
outdated practice. If there is an issue or something is missing from
the documentation, then a GH issue should be raised. If someone wants
to share a code snippet with either an additional use case or some
polyfill, there are better places to post it, e.g. Stack Overflow.
Regarding the move, I would advise that we first archive all abandoned
extensions and then only move the still-maintained third-party
extensions.
Question: What about comments on any of the to-be-moved pages? My vote would be to just nuke them from orbit in the process, as manual comments have about a 1% "usefulness" rate. In fact I'd be completely on board with not enabling comments on the contrib-docs built at all and making it strictly readonly, with links to GitHub if someone is in a contributing mood.
Thank you for raising this. It's an important point that wasn't
initially covered.
I agree; I am also in favor of removing the notes altogether. In
practice, notes tend to be outdated, unverified, or contain workarounds
that really belong in the canonical documentation as proper <example>
blocks maintained by the extension authors themselves.
That said, it is worth noting that a few extensions do rely heavily on
notes, with Imagick taking the lead at around 407 note references. This
was counted using the resource below, so please keep in mind that this
is intended as a rough estimate rather than a fully accurate figure:
https://main.php.net/fetch/user-notes-rss.php?limit=1000§ion=imagick
Since this does have an impact, I have reflected it in the RFC and added
a secondary (simple-majority) vote, allowing the community to choose
between migrating the notes or removing them for third-party extensions.
--
Regards,
Jordi Kroon
Hello Jordi,
[..]
I've opened an RFC to separate third-party extension documentation
(imagick, redis, mongodb, etc) from the official PHP manual, while
keeping the existing DocBook tooling and infrastructure.
[..]
While I do not have RFC voting power, I wanted to let you know that,
as a current co-maintainer of ext-parallel, I do support your RFC.
/Florian
Including third-party extensions within the official PHP manual creates
ambiguity regarding whether an extension is officially part of PHP itself.
AFAIK, every third party extension includes configuration and installation
instructions that make clear whether the extension is part of php-src or
not; can you point at an example of this confusion in the real world ?
This creates unclear expectations regarding:
If the third-party extension maintainer went through the effort of
generating documentation in an antiquated awkward format, they might expect
typos not to require their input. However, I don't think any extension
maintainer expects documentation maintainers to track API changes; they
handle that themselves for the most part. It's my impression this is well
understood among active maintainers.
There are probably sections of the documentation likely contains sections
for genuinely abandoned extensions and we should have a mechanism to
address this.
This idea as proposed is -1 from me, it seems to create an undue burden (on
top of the format's inherent burden) for third-party maintainers.
Cheers
Joe
On Wed, 3 Jun 2026 at 09:44, Florian Engelhardt florian@engelhardt.tc
wrote:
Hello Jordi,
[..]
I've opened an RFC to separate third-party extension documentation
(imagick, redis, mongodb, etc) from the official PHP manual, while
keeping the existing DocBook tooling and infrastructure.
[..]While I do not have RFC voting power, I wanted to let you know that,
as a current co-maintainer of ext-parallel, I do support your RFC./Florian
AFAIK, every third party extension includes configuration and
installation instructions that make clear whether the extension is part
of php-src or not; can you point at an example of this confusion in the
real world ?
The role of PECL (or PIE) may not be known for (new) users. Thus having
those kind of extensions in the official documentation gives the false
assumption that these functions or classes as in fact available.
While this distinction is usually documented in the installation section
of each extension, that is often not the first page users arrive at. In
practice, many users land directly on a function or class page from a
search engine, copied snippet, StackOverflow answer, or any other source.
For example, intl is bundled with php-src and still has a dedicated
installation guide in the manual. So the mere existence of installation
instructions is not, by itself, a reliable indicator to users that an
extension is external to php-src. From a reader’s perspective, bundled
and non-bundled extensions can appear structurally identical within the
documentation.
If the third-party extension maintainer went through the effort of
generating documentation in an antiquated awkward format, they might
expect typos not to require their input. However, I don't think any
extension maintainer expects documentation maintainers to track API
changes; they handle that themselves for the most part. It's my
impression this is well understood among active maintainers.
I agree that active maintainers generally understand where
responsibilities lie today. My concern is more about the expectations
created for readers and contributors outside that group.
From the outside, all extensions documented under the official PHP
Documentation appear equally "official". Readers reasonably assume a
similar level of maintenance and review continuity across the manual,
even when that may no longer be true for some third-party extensions.
There are probably sections of the documentation likely contains
sections for genuinely abandoned extensions and we should have a
mechanism to address this.
At the moment, it is difficult to tell whether:
- the extension itself is still actively maintained,
- the documentation reflects current releases,
- or anyone is still reviewing and resolving documentation issues.
As a result, documentation issues can remain open indefinitely without
readers having a clear indication of the maintenance status or
reliability of the documentation they are reading.
This idea as proposed is -1 from me, it seems to create an undue burden
(on top of the format's inherent burden) for third-party maintainers.
The primary issue the RFC tries to address is not maintainer confusion,
but the expectations created for readers by hosting third-party
extension documentation inside the official PHP manual.
By being part of the official PHP documentation, third-party extensions
appear to have the same level of oversight, maintenance, and reliability
as bundled PHP functionality, even when the way they are maintained may
differ significantly in practice.
Separating third-party extension documentation also allows those
projects to evolve documentation independently, without inheriting the
same expectations of maintenance and review as bundled PHP
functionality. This in turn reduces the need to strictly adhere to the
full PHP documentation format and style requirements, making it easier
for extension documentation to be updated and maintained.
From the perspective of extension maintainers, the practical change
would be minimal: documentation would simply live in a separate
repository with relaxed format and style requirements.
--
Regards,
Jordi Kroon