On 03/06/2026 9:35 pm, Joe Watkins wrote:
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
