If you find Xdebug useful, please consider supporting the project.

Reporting Bugs

Bugs

If you think that you found a bug in Xdebug, please file a bugreport at the Bug Tracking page. You will need to register because this prevents abuse by spammers and other abusing parties. Try to give as much possible information to reproduce the bug, this will greatly help in fixing them. For some hints on what information is useful, see the following sections. Versions before 3.1 are not supported.

Required Information

Every bug report should be created stating out exactly:

  1. What you expected to happen.
  2. What happened instead.
  3. How I can reproduce the problem.

To prevent endless back-and-forwards, please always provide the following information:

  1. A short and self-contained script that exhibits the issue.

    Short means about 10-20 lines maximum, and self-contained means that it can not not depend on any other libraries, or databases.

    If you really can't make a short script after trying for several hours ;-), then please prepare something that I can: clone from GitHub, use something like composer to install dependencies, and then can run. The script can still not have dependencies on things like databases, as I won't have them installed. Please contact me first if you are not sure.

  2. The exact version of Xdebug.

    For example: 2.6.1.

  3. The PHP version (or version range).

    This can be selected in the bug report. If you are using a development version of PHP, please use the one with the -dev prefix for that version, for example: 7.4-dev.

  4. The output of php -v on the CLI: 

    derick@gargleblaster:~$ php -v
PHP 7.2.14 (cli) (built: Jan 24 2019 11:47:11) ( NTS DEBUG )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.2.0, Copyright (c) 1998-2018 Zend Technologies
    with Zend OPcache v7.2.14, Copyright (c) 1999-2018, by Zend Technologies
    with Xdebug v2.7.0beta2-dev, Copyright (c) 2002-2018, by Derick Rethans

    Or otherwise the information next to the "zend® engine" logo in the output of phpinfo(); :

  5. Information about the Operating System, and its version.

    For example: Debian Linux 9.2, OSX 10.10 using MAMP 5.2. Just "Linux" or "Windows" is often not enough information.

Please do not include the full output of phpinfo(); or add all configuration settings. If you think that Xdebug's ini settings can have some effect on the bug, please provide only these configuration settings.

In addition to the above information, I might need some more information depending on what type of bug that you encountered. There is different information useful for Step Debugger Bugs and Crash Bugs. If you are unsure as to what is useful, feel free to only provide information from the Required Information section from above. In which case I will then point you to the right section on this page for further information if necessary.

Step Debugger Bugs

To make it possible for me to find and fix bugs for the remote debugging feature, I need several bits of information. Without this information, I can not fix your bug. The information that is required are:

  1. The items needed for every bug report (script, Xdebug version, PHP version, distribution, etc, see above).
  2. A remote debugging log.

The debugging log contains all the interactions between Xdebug and an IDE and is vital to track down where the error occurs, and due to which protocol command.

You can make a remote debugging log by using the xdebug.log php.ini setting. I suggest you set its value to something in the /tmp directory (or your operating system's equivalent). I have it set as follows: xdebug.log=/tmp/xdebug.log. Make sure that the user that runs the script (yourself for CLI, or your web server's user ID if you're debugging through a web server) can write to the file that you have specified.

With the short script prepared, and the remote logging enabled, now step through your code in the IDE (or do whatever you need to do to reproduce it). When you are done, add both the script as well as the remote debugging log to the bug report at bugs.xdebug.org.

The contents of the log should start with something like: 

[3020307] Log opened at 2020-10-29 03:20:25.076271
[3020307] [Step Debug] INFO: Connecting to configured address/port: 127.0.0.1:43425.
[3020307] [Step Debug] INFO: Connected to debugging client: 127.0.0.1:43425 (through xdebug.client_host/xdebug.client_port). :-)
[3020307] [Step Debug] -> <init
    xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug"
    fileuri="file:///home/httpd/www.xdebug.org/html/router.php"
    language="PHP" xdebug:language_version="7.4.11-dev"
    protocol_version="1.0" appid="2693358" idekey="XDEBUG_ECLIPSE">
        <engine version="3.0.0-dev"><![CDATA[Xdebug]]></engine>
        <author><![CDATA[Derick Rethans]]></author>
        <url><![CDATA[https://xdebug.org]]></url>
        <copyright><![CDATA[Copyright (c) 2002-2020 by Derick Rethans]]></copyright>
</init>

Crash Bugs

To make it a easier, and sometimes even possible, to find and fix crash bugs, I need the standard required information (script, Xdebug version, PHP version, distribution, etc, see above) and some additional information.

It is always a lot easier to reproduce bugs from the command line (CLI), and not through a web browser and web server. The first thing to try is see whether your script also crashes when run with the PHP CLI. On the shell, do the following steps: 

export USE_ZEND_ALLOC=0
export ZEND_DONT_UNLOAD_MODULES=1
php your-script.php

If this still crashes (you'll see something like "Segmentation Fault" or "Bus Error" mentioned), then this is very useful. In order to extract more information, and when you are on Linux or OSX, please install the gdb (not lldb) and valgrind tools.

To have the best chance to fix crash bugs, I need the following information:

  1. The items needed for every bug report (script, Xdebug version, PHP version, distribution, etc, see above).
  2. A GDB backtrace. See below on how to make one.
  3. A memory trace created by Valgrind. See below on how to make one.

Creating a GDB Backtrace

GDB is a tool for debugging C applications, and provides information about the state of a process when it crashes (or stops at a breakpoint). A state is recorded in a backtrace, which we will be creating here.

In the same shell as above, run your script as follows: 

gdb --args php your-script.php

You get a GDB prompt, on which you need to type: 

run

When the script then crashes, you get back to the GDB prompt, where you then can run: 

bt full

That produces a lot of information, that you can then attach as a file to the bug report.

Creating a Valgrind Trace

Valgrind is a tool that shows issues with accessing memory when a program is running. For example using memory that has been freed, or has not been initialised yet. There is an article about Valgrind on Derick's blog.

In the same shell as above (with the two exports), run your script as follows: 

valgrind php your-script.php >/tmp/valgrind.log 2>&1

After the command returns back to the prompt, there should be a file /tmp/valgrind.log with a lot of information. Please add this also as a file to the bug report.