The Fate of the Legacy PHP Documentation

December 10th, 2020

As you may or may not know, in September 2020, the PHP Documentation Group has retired the manual for end-of-life PHP versions from the php.net site.

TL;DR: The legacy PHP documentation now lives at this address: php-legacy-docs.zend.com. Myself, Zend and legacy enthusiasts will take care of fixing any inaccuracies through this GitHub repository.

Why Not Just Upgrade Your PHP?

Ideally, I'd love to see everyone running the latest version of PHP! But to achieve this, someone has to read the old docs to ensure the application's compatibility with the new PHP version.

I have just migrated my 20th application this year, where I fixed 4 million lines of PHP 5 code to make them compatible with the latest version. I refer to old documentation almost daily in order to understand the PHP 5 vs current behavior. Other people have voiced a similar opinion. Imagine spending hours searching for solutions only to click on a broken link, then having to dig through tarballs.

Why Were the Legacy Docs Removed?

Here are some reasons provided by the maintainers of the current documentation:

Because everything is on one page, maintaining accurate docs for all versions is rather impractical.

I concur. Currently, documentation pages may have:

• A changelog for a feature's behavior evolution.
• Loaded paragraphs explaining how an argument works, with various exceptions depending on the PHP version range.
• Deprecation notices.

We could spend our time on more productive things.

The current documentation team is rather tiny. They can barely keep up with the new releases. Asking them to maintain legacy versions and figuring out how to explain all of that clearly on one page is exacting.

Removing docs alleviates the burden on translations.

At the time of writing, the documentation is available in 10 different languages, so take the points from the previous arguments and increase the effort tenfold.

Agreeing on the Solution

On the mailing list, we discussed various solutions. I set out with these goals in mind:

• Retain legacy documentation in an easily browsable format.
• Require no ongoing effort from the current documentation team.

Additionally, during the discussion, it became apparent that the current team does not wish to be bothered with bug reports about inaccuracies in the legacy docs. What we needed was a "legacy docs team" which would take away that burden completely off their shoulders.

After toying with various ideas, the following proposal seemed to yield consensus:

So if someone wants to take ownership of that project they are free to do it and we can possibly sort out some way to link to it from the official docs with a disclaimer that doc bugs about the legacy docs should be redirect to that specific team.

I went and did just that.

Implementing the Solution

I put on my diplomacy hat and convinced Zend, one of my current clients, to support this initiative. To my delight, they agreed to dedicate both hosting resources and development time for maintaining the legacy docs. I went ahead and published them, which wasn't as trivial as some might think. I had to:

• Make a plan. How will people contribute? To what extent will the legacy docs be edited? How will all that play with the current docs? What's the best way to display them?
• Clean up ~25,000 HTML files from the tarballs.
• Create an open source project, with all the fun stuff like licensing, attribution of the derivative work and instructions for contributors. I also had to ensure continuity in case I got hit by a car tomorrow.
• Create and deploy a website that pulls and displays the legacy docs from the public repository.
• Check whether a page exists in other legacy versions to display a link.
• Check whether a page exists in other current versions to display a link to php.net.
• Create a patch on the php.net site that would offer a legacy alternative in case of a 404 in the manual. It checks whether the legacy page exists to link to that page directly. The patch will hopefully be merged soon.

Now I just need to get the search working and we're in good shape. I expect to dedicate time each week to the maintenance of the legacy docs and hopefully build a community around them.

Previous: If We Asked Athletes the Questions That We Ask Developers Next: Code is Cheap, Knowledge is Expensive