Xdebug — Step Debugger and Debugging Aid for PHP

Last update: May 25, 2022

Xdebug

https://ci.appveyor.com/api/projects/status/glp9xfsmt1p25nkn?svg=true https://circleci.com/gh/xdebug/xdebug/tree/master.svg?style=svg

Xdebug is a debugging tool for PHP. It provides step-debugging and a whole range of development aids, such as stack traces, a code profiler, features to dump the full execution of your script to a file, and more.

Requirements

Xdebug requires a supported version of PHP. For installation it requires the pecl tool (available through the php-pear package), unless your Linux distribution has an Xdebug package (php-xdebug).

Installation

On most Linux distributions you can install Xdebug through its package manager. You can also compile from source with the pecl tool through pecl install xdebug. The latter also works for MacOS as long as PHP is installed with Homebrew.

On Windows, you need to download a binary. Use the Wizard.

Unless you have installed Xdebug with a package manager on Linux, you also need to add the following line to your php.ini file, or create a new Xdebug specific ini file xdebug.ini in the conf.d directory. In either case, it needs the following line added:

zend_extension=xdebug

For more extensive installation instructions, see the documentation at https://xdebug.org/docs/install

Configuration

Most features in Xdebug have to be opted in into. Each feature has a specific opt-in. For example to use the step debugger you need to set xdebug.remote_enable=1 in your configuration file. The step debugger requires an IDE (client), of which there are many available.

The documentation has instructions for each of Xdebug's features: https://xdebug.org/docs/ and a full list of settings is also available there.

Contributing

Xdebug is written in C, and extensive knowledge of PHP's internals is necessary to be able to contribute. Contributing guidance is available separately.

Before you begin to contribute, please reach out first. Either through email (address at the bottom), an issue in the issue tracker or preferably through IRC on Freenode's #xdebug channel.

Testing

If you are familiar with compiling PHP extension from source, have a local checkout of Xdebug's GitHub repository, and have compiled Xdebug in that directory following the instructions under installation you can run Xdebug's tests by running:

php run-xdebug-tests.php

The test framework requires that the PHP binary on the path has Xdebug loaded, with remote debugging enabled through xdebug.mode=debug. It is possible to skip remote debugging tests by exporting the SKIP_DBGP_TESTS=1 environment variable.

The SKIP_UNPARALLEL_TESTS=1 can be used to skip tests that can not run in parallel environments, and the SKIP_SLOW_TESTS=1 environment variable to skip slow tests. The OPCACHE environment variable can either be yes or no and controls whether the test framework enables or disables OpCache.

Licensing

Xdebug is released under The Xdebug License, which is based on The PHP License. It is an Open Source license (though not explicitly endorsed by the Open Source Initiative).

Further Reading

Xdebug has extensive documentation on its website. There are over a hundred settings and many functions documented. Please have a look through the wealth of information that Xdebug can provide to make your every day development with PHP easier.

Support

For questions regarding Xdebug, please use StackOverflow, and tag your question with xdebug.

You can also find ad-hoc and sporadic support on IRC: freenode/#xdebug. You can do that with your favourite client, or by using their webchat.

If you think that you encountered a bug, please file a detailed bug report at https://bugs.xdebug.org. You are required to create an account, this is so that you can be contacted for additional information and to keep out spam.

Derick Rethans — [email protected]

GitHub

https://github.com/xdebug/xdebug
Comments
  • 1. Implemented issue #998: Added support for IPv6

    • Rewrote the xdebug_create_socket function so that it also supports creating sockets for IPv6 addresses.
    • Wrote a couple of tests that test both IPv4 and IPv6 connectivity.
    • Added some functions to the DebugClient (some refactoring to make it more extendable).
    • Created a DebugClientIPv6 class that extends from DebugClient. This communicates with Xdebug over IPv6.

    Known potential problems

    • Haven't been tested on Windows.
    • The DebugClientIPv6::isSupported() function isn't tested, so the SKIP for the test could be ignored on a machine that doesn't support IPv6.
    Reviewed by vanhanit at 2013-11-08 08:20
  • 2. VC14 fixes, cherry pick them

    @derickr Pick whatever you like of these fixes. I am not sure if tey are all correct, but they fixed compiling with VC14. php_xdebug.dll is still crashing, but given the failed tests (on Centos 6 as well) this does not surprise me. Moreover, with xdebug.so I also experienced segfaults on Centos.

    You have a long way to go. Good luck with that.

    Reviewed by Jan-E at 2015-08-29 20:33
  • 3. Added compatibility with other extensions modifying zend_error_cb

    Since Xdebug doesn't call the previously defined error callback but replaces it, find a way to make it coexist with other extensions that replaces the error callback at RINIT, like APM.

    Reviewed by patrickallaert at 2012-04-30 22:22
  • 4. Improve profiler timing on Windows/x86 using RDTSC

    This PR further improves https://github.com/xdebug/xdebug/pull/611. The simplest php functions (is_int, count, ...) take about 20 ns per call, but the best Windows timer has resolution of 100 ns [1] which implies that this timer source is short to simple php functions. When a script/project under test contain a lot of calls of simple php functions, the xdebug profiler output is quite ambiguous (some calls are recorded with 10 ns duration (minimal time step) and some with 100 ns (minimal timer step)).

    This PR solves this issue by using RDTSC as a clock source, which has resolution of about 0.25 ns and reading it is fast, it takes about 6 ns per call. On modern CPUs (Nehalen or newer), it is incremented at constant rate

    However, there is no way to detect the RDTSC speed, therefore it needs a short calibration (2 ms) and this feature ~must by enabled explictly by xdebug.profiler_tsc_as_clock php ini option~ is enabled by default on Windows but only for profile mode. As php process takes about 10 ms to startup on Windows, I belive the calibration delay is acceptable against much more accurate results.

    [1] https://stackoverflow.com/questions/63205226/better-than-100ns-resolution-timers-in-windows

    Reviewed by mvorisek at 2020-08-22 15:31
  • 5. fix a use after free case

    add_name_attribute_or_element implicitly frees full_name but xdebug_var_export_xml_node passes it over to xdebug_array_element_export_xml_node which attempts to read it

    Reviewed by QwertyZW at 2017-04-29 03:52
  • 6. Fix for #416

    This is the fix for #416, which was submitted in 2009 and 2010. It fixes the trace output of the return value in the computerized format (which was missing).

    Reviewed by wimg at 2011-10-19 08:57
  • 7. Fixed issue #1016: Support for pause-execution

    Reviewed by robberphex at 2019-06-10 10:13
  • 8. Fix bug #973: configuration option to control case-sensitivity during filename comparison.

    This commit basically takes the approach to filename comparison used under Win32 (use of "strncasecmp()" instead of "memcmp()") and makes it available on other systems, controlled by a configuration option ("xdebug.case_sensitive_fs"). The default value is 1, which causes the old, case-sensitive behavior. The Win32 code is left untouched.

    This addresses bug #973 ("Breakpoints not triggered on case-insensitive file systems in files autoloaded by spl_autoload") by allowing a developer to change the behavior of xdebug to match the behavior of the filesystem.

    The main thing that's not included is a test, which I wasn't sure how to implement.

    Reviewed by outis at 2014-05-26 01:10
  • 9. Use a flat array for line coverage. (take 2)

    I've rebased and done some extra cleanup (amazing what 6 months and fresh eyes will do). I also ran benchmarks again, this time with public code!

    Using PHP 5.3.10 x86_64 compiled on OSX 10.6.8, run on a 3.2GHz i3 with 8GB 1333MHz RAM.

    Each timing is the mean of 10 runs of PHPUnit 3.6 (sebastianbergmann/[email protected]). Before each run of 10, I ran it 3 times in a row and threw out those results.

    for x in {1..10}; do time ./phpunit.php 2>&1 >/dev/null; done
    

    Before (derickr:master derickr/[email protected]): real avg 18.414 s user avg 15.76 s sys avg 2.3133 s

    After (taavi:coverage_line_array2 taavi/[email protected]): real avg 17.666 s (4% improvement over before) user avg 15.0101 s (5% improvement over before) sys avg 2.2652 s (2% improvement over before)

    I suspect it also reduces memory usage (given the cost of the hash tables and linked list entries vs 1-byte-per-line-in-a-file) and almost certainly reduces memory fragmentation (one alloc, and probably a few reallocs per file vs alloc-per-line).

    Thanks!

    Reviewed by taavi at 2012-02-09 19:34
  • 10. Fixed issue #1898: API for querying the active mode(s)

    Although it is possible to obtain the mode value in userland, it is quite cumbersome and possibly brittle to do so. This is fixed with the addition of an xdebug_mode() function:

    xdebug_mode(?string $mode = null) : mixed

    Returns the enabled xdebug modes as a comma-separated string, or if the $mode parameter is supplied, whether the named mode(s) are set.

    For example, using xdebug.mode=debug,develop,coverage.

    var_dump(xdebug_mode());                  // string(22) "develop,coverage,debug"
    var_dump(xdebug_mode('off'));             // bool(false)
    var_dump(xdebug_mode('debug,coverage'));  // bool(true)
    var_dump(xdebug_mode('trace,debug'));     // bool(false)
    
    Reviewed by johnstevenson at 2021-03-21 20:18
  • 11. Trying to fix IPv6 test for Travis

    Rewrote the isSupported function to use stream_socket_server and to also return the error string and number in case of errors so that can be logged in the skip statement in the tests.

    Reviewed by vanhanit at 2018-02-08 16:53
  • 12. Fix for removal of JMPZNZ opcode in PHP 8.2

    JMPZNZ opcode has been removed in PHP 8.2. So this PR limits the handling of the JMPZNZ opcode to lower versions.

    Ref: https://github.com/php/php-src/pull/7857

    Edit: This PR also adds PHP 8.2 to the GitHub Actions workflow.

    Reviewed by shivammathur at 2022-01-11 03:38
  • 13. Fixed bug #1732: Implement flamegraph cost and memory tracing output

    https://github.com/pounard/xtrace2fg is a PHP tool that converts computerized xdebug trace output to https://github.com/brendangregg/FlameGraph suitable input for generating flamegraph.

    As suggested in https://github.com/pounard/xtrace2fg/issues/1 by @derickr I tried to implement it directly into xdebug.

    Please note that the memory support is probably buggy, it will show memory cost of each function when they allocate memory, but will fallback to 0 for functions that free memory, for the simple reason that flamegraph tool was probably not meant to be used this way and will cause error with negative values.

    Because there is 2 different modes, I added 2 different trace handlers, 3 will write cost (time) in output file, 4 will write memory instead.

    Please, be kind with me, I didn't write C for something like more than 15 years, last time being a student, there's some high probability I felt in C pitfalls and traps.

    In order to have a meaningful output trace file, it's best to use 'self' function cost (no matter it's time or memory) instead of 'inclusive' values (including children own cost). If we return a trace using inclusive cost, it looks marvellously flat, sadly it doesn't yield any meaning, excepted if you want to dynamically draw a red pine forest for your children using your code :)

    In order to compute 'self' cost, when children function exists, it increments a value in a linked list which carry one item per function_nr (functions being uniquely identified, we can find the calling function_nr within the stack easily). This linked list always prepend new items, instead of appending it, it makes both the increment and delete operations faster in the common case since that we will always attempt to access one of the most recently appended items (the parent).

    My previous attempt was wrong, in order to compute 'self' cost, it now implements a stack in which functions are push on enter, their inclusive costs are increment into the parent on exit, then the stack item is removed on function exit. The need for reading xdebug own stack is therefore eliminated. At the same time, since we need to keep the absolute function path in stack as a string such as {main};some_func;other_called_by_some_func we store that information in the stack item as well so we don't need to traverse it when writing into the trace file. This solution should perform better.

    Since stack items are freed once we return from a function, it will never grow bigger than the current stack depth, which should keep a low memory footprint, but with the new fibers API, I'm not sure how all this will behave, this probably needs a careful review.

    I think the custom linked list here fits well with the need and I do not expect it to be a performance hog, I hope. Please tell me if the solution seems OK.

    Just as a note, here be dragons, because I'm not expert in C, and I had to play with xdfree() and xdmalloc(), it's tested, but use-after-free or memory leaks are still possible.

    Reviewed by pounard at 2021-07-22 14:45
  • 14. XDEBUG_FILE in cookie

    Add new format to xdebug.trace_output_name to allow set the filename from $_COOKIE "XDEBUG_FILE"

    %K filename (from $_COOKIE if set) trace.%K trace.filename_in_set_in_the_XDEBUG_FILE_cookie.xt

    Reviewed by MoleDJ at 2015-03-16 10:41
php-xdebug

PHP-Xdebug Useage 修改/ConfigurationFile/php/php.ini

Jan 30, 2022
Restart a CLI process without loading the xdebug extension.

composer/xdebug-handler Restart a CLI process without loading the Xdebug extension, unless xdebug.mode=off. Originally written as part of composer/com

May 18, 2022
The Interactive PHP Debugger

The interactive PHP debugger Implemented as a SAPI module, phpdbg can exert complete control over the environment without impacting the functionality

Apr 26, 2022
Dontbug is a reverse debugger for PHP
Dontbug is a reverse debugger for PHP

Dontbug Debugger Dontbug is a reverse debugger (aka time travel debugger) for PHP. It allows you to record the execution of PHP scripts (in command li

May 8, 2022
Php Debugger to run in terminal to debug your code easily.
Php Debugger to run in terminal to debug your code easily.

What is Dephpugger? Dephpugger (read depugger) is an open source lib to make a debug in php direct in terminal, without necessary configure an IDE. Th

Jan 12, 2022
Php Debugger to run in terminal to debug your code easily.
Php Debugger to run in terminal to debug your code easily.

What is Dephpugger? Dephpugger (read depugger) is an open source library that allows a developer to debug in php direct in terminal, without necessary

May 20, 2022
A Laravel Package to integrate Nette Tracy Debugger
A Laravel Package to integrate Nette Tracy Debugger

Nette Tracy for Laravel 5 Better Laravel Exception Handler Features Visualization of errors and exceptions Debugger Bar (ajax support @v1.5.6) Excepti

May 3, 2022
Yet Another Swoole Debugger
Yet Another Swoole Debugger

English | 中文 yasd Yet Another Swoole Debugger. document How to use it build You'll need to install the Boost library first. macOS: brew install boost

May 25, 2022
Slim Framework Tracy Debugger Bar
 Slim Framework Tracy Debugger Bar

Slim Framework Tracy Debugger Bar configure it by mouse now in package: Panel Description Slim Framework - Slim Environment RAW data Slim Container RA

Feb 26, 2022
Kint - a powerful and modern PHP debugging tool.
Kint - a powerful and modern PHP debugging tool.

Kint - debugging helper for PHP developers What am I looking at? At first glance Kint is just a pretty replacement for var_dump(), print_r() and debug

May 14, 2022
Buggregator is a beautiful, lightweight web server built on Laravel and VueJs that helps debugging your app.
Buggregator is a beautiful, lightweight web server built on Laravel and VueJs that helps debugging your app.

A server for debugging more than just Laravel applications. Buggregator is a beautiful, lightweight web server built on Laravel and VueJs that helps d

May 16, 2022
A collection of helper methods for testing and debugging API endpoints.

Laravel API Test Helpers This is a collection of helper methods for testing and debugging API endpoints. Installation You can install the package via

Apr 16, 2022
The ultimate debugging and development tool for ProcessWire
The ultimate debugging and development tool for ProcessWire

Tracy Debugger for ProcessWire The ultimate “swiss army knife” debugging and development tool for the ProcessWire CMF/CMS Integrates and extends Nette

Apr 14, 2022
Sage - Insightful PHP debugging assistant ☯
 Sage - Insightful PHP debugging assistant ☯

Sage - Insightful PHP debugging assistant ☯ At first glance Sage is just a pretty replacement for var_dump() and debug_backtrace(). However, it's much

May 19, 2022
WordPress debugging made simple.
WordPress debugging made simple.

Loginator Debugging WordPress can sometimes be a pain, our goal is to make it easy, which is why Loginator was built with this in mind. From creating

Feb 12, 2022
This package connects a Laravel Octance application with Tideways for PHP Monitoring, Profiling and Exception Tracking.

Tideways Middleware for Laravel Octane This package connects a Laravel Octance application with Tideways for PHP Monitoring, Profiling and Exception T

Jan 6, 2022
Handle PHP errors, dump variables, execute PHP code remotely in Google Chrome

PHP Console server library PHP Console allows you to handle PHP errors & exceptions, dump variables, execute PHP code remotely and many other things u

May 19, 2022
PHP APM (Alternative PHP Monitor)

APM (Alternative PHP Monitor) APM (Alternative PHP Monitor) is a monitoring extension enabling native Application Performance Management (APM) for PHP

May 19, 2022
Zipkin PHP is the official PHP Tracer implementation for Zipkin

Zipkin PHP is the official PHP Tracer implementation for Zipkin, supported by the OpenZipkin community. Installation composer require openz

May 14, 2022