View Issue Details

IDProjectCategoryView StatusLast Update
0001952XdebugDocumentationpublic2021-03-03 14:05
ReporterChealer Assigned Toderick  
PriorityhighSeveritytextReproducibilityN/A
Status closedResolutionfixed 
Product Version2.9.8 
Summary0001952: Configuration documentation based on xdebug_info(), which doesn't exist until Xdebug 3
Description

Let me first thank you so much for Xdebug. I have been using it more or less intensely for over a decade, and it is nothing less than the piece PHP is missing to become competitive.

Thank you very much for the work put into version 3. I have not yet had the the occasion to try it, but seeing that it's worked on performance and on simplifying configuration, I am convinced it is a huge progress.

Unfortunately, I am still using Xdebug 2. As I only setup Xdebug once every 2 years or so, I never remember the details and always need to go back to documentation. I did that this morning. I used Ubuntu 18.04, so installing was trivial, but for configuring, I first checked how to ensure Xdebug was loaded. Step 3 of the relevant section ( https://xdebug.org/docs/install#configure-php ) instructed to do so using the xdebug_info() function. I was slightly surprised as I didn't remember that function, but I got over it as I am far from knowing Xdebug well and I haven't set it up in years.

So I added a call in a PHP file, and had a fatal error due to the function being undefined. I was slightly surprised since Debian is supposed to enable installed extensions automatically, but as it was my first time setting up PHP-FPM and using PHP with Docker, so I figured I was missing something.

It would take 1 to 2 hours of increasingly frustrating failures before I finally called phpinfo() instead of xdebug_info() and at last figured out that in fact, Xdebug had been enabled all that time... I simply was trying to call a function which my version didn't include! I then checked the documentation and realized that it only applied to version 3, and that I had missed another version of the documentation which is designed for version 2.

However, looking at how I got there, I didn't do anything wrong, and I'm afraid many could do the same. And unfortunately, that could keep happening for quite a while. To take just Ubuntu as example, there will certainly be many more users installing Xdebug 2 until at least April 2022.
In fact, even those who visit the Xdebug 2 version of that page ( https://2.xdebug.org/docs/install ) will be referred to xdebug_info().

I recommend the following remedies:

  1. Fix the Configure PHP section of https://2.xdebug.org/docs/install
  2. At least one of the following:
    A. Remove the "Install" link from the menu (at least temporarily), so that all visitors have to go through the Documentation page, which mentions version 2 (although with very little prominence)
    B. Add a link from https://xdebug.org/docs/install to the Xdebug 2 equivalent
    C. Modify the current version of the documentation, either indicating that Xdebug 2 lacks xdebug_info(), or instructing to call phpinfo() instead if xdebug_info() does not exist.
TagsNo tags attached.
Operating System
PHP Version7.2.20-7.2.29

Activities

derick

2021-03-03 11:35

administrator   ~0005701

I've updated the docs to remove the xdebug_info reference on the 2.xdebug.org archive site, and use phpinfo instead.

I've also added a warning to the installation setting, repeating that Xdebug 2 is no longer supported: https://2.xdebug.org/docs/install#source

Because Xdebug 2 is no longer supported (https://xdebug.org/docs/compat), I am not going to change the up-to-date information for Xdebug 3 to include references to Xdebug 2.
When I say "no longer supported", I mean that :-)

Chealer

2021-03-03 14:05

reporter   ~0005705

Thank you very much for the quick response Derick

I know it's difficult enough to document one version, and how painful it is to document multiple versions. I understand it is annoying to effectively reduce the quality of the documentation for users of current versions, but it will still take time before even a majority of users transition to version 3. I am perfectly fine with the policy of only supporting Xdebug 3, in the sense of not releasing more Xdebug 2 versions, but dropping support for a version does not mean dropping support for its documentation. If we take just PHP as an example, the oldest version which still has fixes in 7.3, yet documentation still covers at least PHP 5.6.

Xdebug obviously has no GUI, making its documentation critical. As Xdebug does not include documentation, keeping documentation for most of the used versions on the web is crucial.

Even the level of documentation support can be relative. I have no problem with only providing a frozen snapshot of documentation for old versions, but not even making these old versions discoverable is an entirely different stance. If there is a complete resistance to adding any more reference to version 2, I will reiterate my proposal to remove (or temporarily hide) the "Install" link from the menu, so that all visitors have to go through the Documentation page, which strongly recommend.

Issue History

Date Modified Username Field Change
2021-03-02 22:51 Chealer New Issue
2021-03-03 11:35 derick Assigned To => derick
2021-03-03 11:35 derick Status new => closed
2021-03-03 11:35 derick Resolution open => fixed
2021-03-03 11:35 derick Note Added: 0005701
2021-03-03 14:05 Chealer Note Added: 0005705