Xdebug

.. image:: https://github.com/xdebug/xdebug/actions/workflows/tests.yml/badge.svg :target: https://github.com/xdebug/xdebug/actions/workflows/tests.yml .. image:: https://circleci.com/gh/xdebug/xdebug/tree/master.svg?style=svg :target: https://circleci.com/gh/xdebug/xdebug

.. image:: https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg :target: https://stand-with-ukraine.pp.ua/

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

|Repography logo| / Recent activity |Time period|

|recent-activity_timeline| |recent-activity_prs| |recent-activity_words| |recent-activity_users|

.. |Time period| image:: https://images.repography.com/0/xdebug/xdebug/recent-activity/ef1290ac5bfa674f07dcfa4f915ce6b3_badge.svg :alt: Time period :target: https://repography.com .. |Repography logo| image:: https://images.repography.com/logo.svg :alt: Repography logo :target: https://repography.com .. |recent-activity_timeline| image:: https://images.repography.com/0/xdebug/xdebug/recent-activity/ef1290ac5bfa674f07dcfa4f915ce6b3_timeline.svg :alt: Timeline graph :target: https://github.com/xdebug/xdebug/commits .. |recent-activity_prs| image:: https://images.repography.com/0/xdebug/xdebug/recent-activity/ef1290ac5bfa674f07dcfa4f915ce6b3_prs.svg :alt: Pull request status graph :target: https://github.com/xdebug/xdebug/pulls .. |recent-activity_words| image:: https://images.repography.com/0/xdebug/xdebug/recent-activity/ef1290ac5bfa674f07dcfa4f915ce6b3_words.svg :alt: Trending topics :target: https://github.com/xdebug/xdebug/commits .. |recent-activity_users| image:: https://images.repography.com/0/xdebug/xdebug/recent-activity/ef1290ac5bfa674f07dcfa4f915ce6b3_users.svg :alt: Top contributors :target: https://github.com/xdebug/xdebug/graphs/contributors

Requirements

Xdebug requires a supported version <https://www.php.net/supported-versions.php>_ of PHP. For installation it requires the pie tool, unless your Linux distribution has an Xdebug package (most often: php-xdebug).

Installation

On most Linux distributions you can install Xdebug through their package manager <https://xdebug.org/docs/install#linux>_.

You can also install Xdebug on Linux, macOS, and Windows, with the PIE <https://github.com/php/pie?tab=readme-ov-file#using-pie---what-do-i-need-to-get-started>_ installer through pie install xdebug/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 <https://xdebug.org/docs/remote>_ 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 <https://xdebug.org/docs/remote#clients>_.

The documentation has instructions for each of Xdebug's features: https://xdebug.org/docs/ and a full list of settings <https://xdebug.org/docs/all_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 <https://github.com/xdebug/xdebug/blob/master/CONTRIBUTING.rst>_.

Before you begin to contribute, please reach out first. Either through email (address at the bottom), an issue in the issue tracker <https://bugs.xdebug.org>_ 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 <https://xdebug.org/docs/install#source>_ 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 <https://github.com/xdebug/xdebug/blob/master/LICENSE>, which is based on The PHP License <https://github.com/php/php-src/blob/master/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 <https://xdebug.org/docs>_. 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 <https://stackoverflow.com/questions/tagged/xdebug>_, 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 <http://webchat.freenode.net/?channels=#xdebug>_.

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 — derick@xdebug.org