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

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