Xdebug — Step Debugger and Debugging Aid for PHP

Overview

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]

Comments
  • Implemented issue #998: Added support for IPv6

    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.
    opened by vanhanit 48
  • VC14 fixes, cherry pick them

    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.

    opened by Jan-E 18
  • Improve profiler timing on Windows/x86 using RDTSC

    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

    opened by mvorisek 12
  • Added compatibility with other extensions modifying zend_error_cb

    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.

    opened by patrickallaert 12
  • Fixed bug #1732: Implement flamegraph cost and memory tracing output

    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.

    opened by pounard 11
  • fix a use after free case

    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

    opened by QwertyZW 10
  • Fix for #416

    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).

    opened by wimg 9
  • Fixed issue #1016: Support for pause-execution

    Fixed issue #1016: Support for pause-execution

    opened by robberphex 8
  • Fix bug #973: configuration option to control case-sensitivity during filename comparison.

    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.

    opened by outis 8
  • Use a flat array for line coverage. (take 2)

    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/phpunit@5d0ff52bdff9afd479e38fdc880adce453ce88e5). 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/xdebug@004b99c8a8ad3b2a1986c931a1585e9d71a4b39a): real avg 18.414 s user avg 15.76 s sys avg 2.3133 s

    After (taavi:coverage_line_array2 taavi/xdebug@cae8255ea43b9bc2087256968d20e221fa0863fb): 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!

    opened by taavi 8
  • Fixed issue #1898: API for querying the active mode(s)

    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)
    
    opened by johnstevenson 7
  • XDEBUG_FILE in cookie

    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

    opened by MoleDJ 8
php-xdebug

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

xiaoliang 3 Jun 29, 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

Composer 2.4k Dec 30, 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

Joe Watkins 841 Oct 9, 2022
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

Sidharth Kshatriya 709 Dec 30, 2022
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

Renato Cassino 190 Dec 3, 2022
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

Renato Cassino 190 Dec 3, 2022
Simple php debugger

Debugger Description Simple debugger for php Requirements PHP 5.5+ to 8.0 Usage new \Debugger\Debugger( true, // work mode [false - disable, 'FILE' -

null 0 Aug 10, 2022
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

Recca Tsai 383 Dec 6, 2022
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

Swoole Project 319 Dec 25, 2022
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

null 72 Aug 29, 2022
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

null 2.7k Dec 25, 2022
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

Buggregator 311 Jan 4, 2023
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

Stephen Jude 49 Jul 26, 2022
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

Adrian Jones 80 Oct 5, 2022
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

null 27 Dec 26, 2022
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

Poly Plugins 2 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

Tideways 7 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

Sergey 1.4k Dec 25, 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

Patrick Allaert 310 Dec 4, 2022