• Xdebug Clients
• Xdebug Cli

Enables Xdebug's profiler which creates files in the profile output directory. Those files can be read by KCacheGrind to visualize your data. This setting can not be set in your script with iniset. If you want to selectively enable the profiler, please set xdebug.profilerenabletrigger to 1 instead of using this setting. XDebug and Zend Debugger PHP CLI debugging helper console command with PhpStorm, NetBeans support - dbalabka/phpdebug-cli.

The command line debug client allows you to debug PHP scripts without having to set up an IDE. Drupal Console is not necessary for getting XDebug to work, but it offers many code introspection tools that are very useful for Drupal debugging in general. Finally, set `phpxdebugdefaultenable` to `1` and `phpxdebugclidisable` to `no`. These last two settings are very important for being able to. Xdebug's step debugger allows you to interactively walk through your code to debug control flow and examine data structures.

Xdebug provides an interface for debugger clients that interact with running PHP scripts. This section explains how to set-up PHP and Xdebug to allow this, and introduces a few clients.

Xdebug Clients

Introduction

Xdebug's (remote) debugger allows you to examine data structure,interactively walk through your and debug your code. The protocol that is beingused is open, and is called DBGp. This protocol isimplemented in Xdebug 2, and replaces an older GDB-like protocol that is nolonger supported.

Clients

There are many client implementations (both free and commercial). There are allthird party tools, so please refer to the original authors for support:

• Eclipse plugin (IDE).
• KDevelop (IDE: Linux (KDE); Open Source).
• ActiveState's Komodo (IDE: Windows, Linux, Mac; Commercial).
• NetBeans (IDE: Windows, Linux, Mac OS X and Solaris).
• Notepad++plugin (Editor: Windows).
• Devsense's PHP Tools for Visual Studio (MS Visual Studio Plugin; Commercial).
• JetBrain's PhpStorm (IDE; Commercial).
• pugdebug (Standalone client for Linux, Windows and Mac OS X; Open Source).
• SublimeTextXdebug (Plugin for Sublime Text 2 and 3, Open Source).
• VIM plugin (Editor Plugin).

The simple command line client dbgpClient for debugging isavailable on the download page.

Starting The Debugger

In order to enable Xdebug's debugger you need to make some configurationsettings in php.ini. These settings are xdebug.remote_enable to enable thedebugger, xdebug.remote_host and xdebug.remote_port to configure the IP addressand port where the debugger should connect to. There is also axdebug.remote_connect_back setting that can be used if your development serveris shared with multiple developers.

If you want the debugger to initiate a session when an error situationoccurs (PHP error or exception) then you also need to change thexdebug.remote_mode setting. Allowed values for this setting are 'req' (thedefault) which makes the debugger initiate a session as soon as a script isstarted, or 'jit' when a session should only be initiated on an error.

After made all those settings Xdebug will still not start a debugging sessionautomatically when a script is run. You need to activate Xdebug's debuggerand you can do that in three ways:

Using an environment variable

When running the script from the command line you need to set anenvironment variable, like:

On Windows, setting an environment variable is done with set:

You can also configure the xdebug.remote_host, xdebug.remote_port,xdebug.remote_mode and xdebug.remote_handler in this same environment variable aslong as you separate the values by a space:

All settings that you can set through the XDEBUG_CONFIG setting can also be setwith normal php.ini settings.

Using a GET parameter

If you want to debug a script started through a web browser, simply addXDEBUG_SESSION_START=session_name as parameter to the URL.Instead of using a GET parameter, you can also set XDEBUG_SESSION_START as aPOST parameter, or through a cookie named XDEBUG_SESSION. Refer to the next section to read on how debug sessions workfrom within a browser window.

Using a browser extension

An alternative way to activate the debugger while running PHP through a webserver is by installing one of the following four browser extensions. Each ofthem allows you to simply enable the debugger by clicking on one button. Whenthese extensions are active, they set the XDEBUG_SESSION cookie directly,instead of going through XDEBUG_SESSION_START as described inHTTP Debug Sessions further on.

The extensions are:

Xdebug Helper for Firefox

This extension for Firefox was built to make debugging with an IDE easier. You can find the extension at https://addons.mozilla.org/en-GB/firefox/addon/xdebug-helper-for-firefox/. The source code for this extension is on GitHub.

Xdebug Helper for Chrome

This extension for Chrome will help you to enable/disable debugging and profiling with a single click. You can find the extension at https://chrome.google.com/extensions/detail/eadndfjplgieldjbigjakmdgkmoaaaoc.

XDebugToggle for Safari

This extension for Safari allows you to auto start Xdebug debugging from within Safari. You can get it from Github at https://github.com/kampfq/SafariXDebugToggle.

Xdebug launcher for Opera

This extension for Opera allows you to start an Xdebug session from Opera.

Before you start your script you will need to tell your client that it canreceive debug connections, please refer to the documentation of the specificclient on how to do this. To use the bundled client simply start it afterdownloading it. You canstart it by running dbgpClient on Linux,dbgpClient-macos on MacOS, and dbgpClient.exe onWindows.

When the debug client starts it will show version information and thenwaits until a connection is initiated by the debug server (Xdebug):

Xdebug Cli

After a connection is made the output of the debug server is shown:

Now you can use the commands as explained on the DBGp documentation page. When the script ends thedebug server disconnects from the client and the debug client resumes withwaiting for a new connection. There is a more comprehensive documentationavailable for Command Line Debug Client as well.

Communication Set-up

With a static IP/single developer

With remote debugging, Xdebug embedded in PHP acts like the client, and the IDEas the server. The following animation shows how the communication channel isset-up:

• The IP of the server is 10.0.1.2 with HTTP on port 80
• The IDE is on IP 10.0.1.42, so xdebug.remote_host is set to 10.0.1.42
• The IDE listens on port 9000, so xdebug.remote_port is set to 9000
• The HTTP request is started on the machine running the IDE
• Xdebug connects to 10.0.1.42:9000
• Debugging runs, HTTP Response provided

With an unknown IP/multiple developers

If xdebug.remote_connect_back is used, the set-up is slightly different:

• The IP of the server is 10.0.1.2 with HTTP on port 80
• The IDE is on an unknown IP, so xdebug.remote_connect_back is set to 1
• The IDE listens on port 9000, so xdebug.remote_port is set to 9000
• The HTTP request is made, Xdebug detects the IP address from the HTTP headers
• Xdebug connects to the detected IP (10.0.1.42) on port 9000
• Debugging runs, HTTP Response provided

HTTP Debug Sessions

Xdebug contains functionality to keep track of a debug session when startedthrough a browser: cookies. This works like this:

• When the URL variable XDEBUG_SESSION_START=name is appendedto an URL—or through a POST variable with the same name—Xdebug emits a cookiewith the name 'XDEBUG_SESSION' and as value the value of theXDEBUG_SESSION_START URL parameter. The default expiry time of the cookie isone hour, but this can be configured through thexdebug.remote_cookie_expire_time setting. The DBGp protocol also passes thissame value to the init packet when connecting to the debuggingclient in the 'idekey' attribute.
• When there is a GET (or POST) variable XDEBUG_SESSION_START or theXDEBUG_SESSION cookie is set, Xdebug will try to connect to a debuggingclient.
• To stop a debug session (and to destroy the cookie) simply add the URLparameter XDEBUG_SESSION_STOP. Xdebug will then no longer tryto make a connection to the debugging client.

Multiple Users Debugging

Xdebug only allows you to specify one IP address to connect to withxdebug.remote_host) while doing remote debugging. It does notautomatically connect back to the IP address of the machine the browser runs on, unless you use xdebug.remote_connect_back.

If all of your developers work on different projects on the same (development)server, you can make the xdebug.remote_host setting for each directorythrough Apache's .htaccess functionality by using php_valuexdebug.remote_host=10.0.0.5. However, for the case where multipledevelopers work on the same code, the .htaccess trick does not work as thedirectory in which the code lives is the same.

There are two solutions to this. First of all, you can use a DBGp proxy.For an overview on how to use this proxy, please refer to the article at Debuggingwith multiple users. You can download the proxy onActiveState's website as part of the python remote debugging package. There is somemore documentation in theKomodo FAQ.

Secondly you canuse the xdebug.remote_connect_backsetting that was introduced inXdebug2.1.

Implementation Details

Xdebug's implementation of theDBGp protocol's context_namescommand does not depend on the stack level. The returned value is always thesame during each debugger session, and hence, can be safely cached.

Custom DBGp commands

The DBGp protocol allows for debugger engine specific commands, prefixed withthe xcmd_ prefix. Xdebug includes a few of these, and they'redocumented here.

DBGp: xcmd_profiler_name_get

If Xdebug's profiler is currently active (See: Profiling), this commandreturns the name of the file that is being used to write the profilinginformation to.

DBGp: xcmd_get_executable_lines

This command returns which lines in an active stack frame can have a workingbreakpoint. These are the lines which have an EXT_STMTopcode on them. This commands accepts a -d option, whichindicates the stack depth, with 0 being the top leve stack frame.

The command returns the information in the following XML format:

Related Settings and Functions

• integerxdebug.extended_info = 1
• stringxdebug.idekey = *complex*
• stringxdebug.remote_addr_header = '
• booleanxdebug.remote_autostart = false
• booleanxdebug.remote_connect_back = false
• integerxdebug.remote_cookie_expire_time = 3600
• booleanxdebug.remote_enable = false
• stringxdebug.remote_handler = dbgp
• stringxdebug.remote_host = localhost
• stringxdebug.remote_log =
• integerxdebug.remote_log_level = 7
• stringxdebug.remote_mode = req
• integerxdebug.remote_port = 9000
• integerxdebug.remote_timeout = 200

• xdebug_break() : bool
• xdebug_is_debugger_active() : bool

Settings

integer xdebug.extended_info = 1#

Available in Xdebug < 2.8

Controls whether Xdebug should enforce 'extended_info' mode for the PHPparser; this allows Xdebug to do file/line breakpoints with the remotedebugger. When tracing or profiling scripts you generally want to turn off thisoption as PHP's generated oparrays will increase with about a third of the sizeslowing down your scripts. This setting can not be set in your scripts withini_set(), but only in php.ini.

string xdebug.idekey = *complex*#

Controls which IDE Key Xdebug should pass on to the debugging client orproxy. The IDE Key is only important for use with the DBGp Proxy Tool,although some IDEs are incorrectly picky as to what its value is.

The default is based on the DBGP_IDEKEY environment setting. Ifit is not present, the default falls back to an empty string.

If this setting is set to a non-empty string, it selects its value overDBGP_IDEKEY environment variable as default value.

The internal IDE Key also gets updated through debugging session managementand overrides the value of this setting as is explained in the documentation.

string xdebug.remote_addr_header = '#

Introduced in Xdebug >= 2.4

If xdebug.remote_addr_header is configured to be a non-empty string, thenthe value is used as key in the $SERVER superglobal array to determine whichheader to use to find the IP address or hostname to use for 'connecting backto'. This setting is only used in combination with xdebug.remote_connect_backand is otherwise ignored.

boolean xdebug.remote_autostart = false#

Normally you need to use a specific HTTP GET/POST variable to startremote debugging (see Step Debugging). Whenthis setting is set to 1, Xdebug will always attempt to start a remotedebugging session and try to connect to a client, even if the GET/POST/COOKIEvariable was not present.

boolean xdebug.remote_connect_back = false#

Introduced in Xdebug >= 2.1

If enabled, the xdebug.remote_host setting is ignored and Xdebug willtry to connect to the client that made the HTTP request. It checks the$_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'] variables tofind out which IP address to use.

If xdebug.remote_addr_header is configured, then the $SERVER variable withthe configured name will be checked before the$_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'] variables.

This setting does not apply for debugging through the CLI, as the $SERVERheader variables are not available there.

Please note that there is no filteravailable, and anybody who can connect to the webserver will then be able tostart a debugging session, even if their address does not matchxdebug.remote_host.

integer xdebug.remote_cookie_expire_time = 3600#

Introduced in Xdebug >= 2.1

This setting can be used to increase (or decrease) the time that the remote debugging session stays alive via the session cookie.

boolean xdebug.remote_enable = false#

This switch controls whether Xdebug should try to contact a debug clientwhich is listening on the host and port as set with the settingsxdebug.remote_host andxdebug.remote_port. If a connection can not be established the script will justcontinue as if this setting was 0.

string xdebug.remote_handler = dbgp#

Available in Xdebug < 2.9

Can only be 'dbgp' to represent thedebugger protocol. The DBGpprotocol is the only supported protocol.

string xdebug.remote_host = localhost#

Selects the host where the debug client is running, you can either use ahost name, IP address, or 'unix:///path/to/sock' for a Unix domain socket.This setting is ignored if xdebug.remote_connect_back is enabled.

Support for Unix domain sockets was introduced in Xdebug 2.6.

string xdebug.remote_log = #

Configures a file name to log all Step Debugging connection attempts,failures, and communication.

Enable this functionality by setting the value to a absolute path. Make surethat the system user that PHP runs at (such as www-data if you arerunning with Apache) can create and write to the file.

The file is opened in append-mode,and will therefore not be overwritten by default. There is no concurrencyprotection available.

When successfully enabled, the log file will include any attempt that Xdebugmakes to connect to an IDE:

It includes the opening time (2020-06-21 17:54:05), theIP/Hostname and port Xdebug is trying to connect to(localhost:9000), and whether it succeeded (Connected toclient :-)). The number in brackets ([1603325]) is theProcess ID.

It also logs the debugging communication itself, which starts with the <init XML element:

The fileuri attribute lists the entry point of yourapplication, which can be useful to compare to breakpoint_setcommands to see if path mappings are set-up correctly.

Beyond the <init element, you will find the configuration offeatures:

And continuation commands:

You can read about DBGP - A common debugger protocol specification at its dedicated documation page.

The xdebug.remote_log_level setting controls how much information islogged.

Note: Many Linux distributions now use systemd, whichimplements private tmp directories. This means that when PHPis run through a web server or as PHP-FPM, the /tmp directory isprefixed with something akin to:

integer xdebug.remote_log_level = 7#

Introduced in Xdebug >= 2.8

Configures which logging messages should be emitted by the Step Debugging.

The following levels are supported:

string xdebug.remote_mode = req#

Selects when a debug connection is initiated. This setting can have twodifferent values:

req

Xdebug will try to connect to the debug client as soon as the scriptstarts.

jit

Xdebug will only try to connect to the debug client as soon as an errorcondition occurs.

integer xdebug.remote_port = 9000#

The port to which Xdebug tries to connect on the remote host. Port9000 is the default for both Xdebug and the Command Line Debug Client.As many clients use this port number, it is best to leave this settingunchanged.

integer xdebug.remote_timeout = 200#

Introduced in Xdebug >= 2.6

The amount of time in milliseconds that Xdebug will wait for on anIDE to acknowledge an incoming debugging connection. The default value of 200ms should in most cases be enough. In case you often get dropped debuggingrequests, perhaps because you have a high latency network, or a development boxfar away from your IDE, or have a slow firewall, then you can should increasethis value.

Please note that increasing this value might mean that your requests seem to'hang' in case Xdebug tries to establish a connection, but your IDE is notlistening.

Functions

xdebug_break() : bool#

This function makes the debugger break on the line it is called from, as if a normal file/line breakpoint was set on this line through the debugger protocol.

The function returns true if a debugging session is (now) active, and the breakpoint was succesfully set. It returns false if a debugging session was not active and could not be activated.

xdebug_is_debugger_active() : bool#

Returns true if a debugging session through DBGp is currently active with a client attached; false, if not.

This section describes on how to install Xdebug.

How you install Xdebug depends on your system. There are the following possibilities:

• Linux with a package manager such as apt, yum, or something else.
• Linux without an Xdebug package with PECL.
• macOSX with homebrew, through PECL.
• Windows, with help from a wizard.
• Unix-like operating systems, from source.

Installing on Linux #

Installing Xdebug with a package manager is often the fastest way. Depending on your distribution, run the following command:

• Alpinelinux:
  sudo apk add php7-pecl-xdebug
• Arch Linux:
  sudo pacman -S xdebug
• CentOS:
  sudo yum install php-xdebug
• CentOS (Remi Repro):
  sudo yum install php74-php-xdebug
• Debian (9/stretch, testing/buster/bullseye/sid):
  sudo apt-get install php-xdebug
• Fedora (32):
  sudo yum install php-xdebug
• Fedora (Remi Repro):
  sudo yum install php74-php-xdebug
• Gentoo:
  emerge dev-php/xdebug
• Manjaro (20.1/Mikah):
  sudo pacman -S xdebug
• RHEL:
  sudo yum install php-xdebug
• RHEL (Remi Repro):
  sudo yum install php74-php-xdebug
• SUSE (openSUSE, Enterprise):
  sudo zypper in php7-xdebug
• Ubuntu (18.04 LTS/Bionic, 20.04 LTS/Focal):
  sudo apt-get install php-xdebug
• Ubuntu (Ondřej Surý's PPA):
  sudo apt-get install php7.4-xdebug

Linux distributions might be providing an old and/or outdated version.If the package managerinstalls a version that is no longer supported (see Supported Versions), please installXdebug with PECL, or from sourceinstead.

Xdebug's latest version is 3.0.4.

Installing with PECL #

You can install Xdebug through PECL on Linux & macOS with Homebrew.Run:

On Apple M1 hardware, you might instead need to use:

Warning: You should ignore any prompts to add'extension=xdebug.so' tophp.ini — this will cause problems.

In some cases pecl will change the php.ini file toadd a configuration line to load Xdebug. You can check whether it did byrunning php -v. If Xdebug shows up with a version number, thanyou're all set and you can configure Xdebug's other functions, such asStep Debugging, or Profiling.

If pecl did not add the right line, skip to the Configure PHP section.

¹ On macOS, you should have PHP installed with Homebrew.

Installing on Windows #

There are a few precompiled modules for Windows, they are all for the non-debugversion of PHP. You can get those at the downloadpage. Follow these instructions to get Xdebuginstalled.

Installation From Source #

Obtain #

You can download the source of the latest stable release 3.0.4.

Alternatively you can obtain Xdebug from GIT:

This will checkout the latest development version which is currently3.1.0-dev. This development branch might not always work asexpected, and may have bugs.

You can also browse the source on GitHub at https://github.com/xdebug/xdebug.

Compile #

There is a wizard available that provides youwith the correct file to download, and which paths to use.

You compile Xdebug separately from the rest of PHP. You need access to thescripts phpize and php-config. If your systemdoes not have phpize and php-config, you willneed to install the PHP development headers.

Debian users can do that with:

And RedHat and Fedora users with:

It is important that the source version matches the installed version as thereare slight, but important, differences between PHP versions. Once you haveaccess to phpize and php-config, take thefollowing steps:

1. Unpack the tarball:

   tar -xzf xdebug-3.0.4.tgz

   You should notunpack the tarball inside the PHP source code tree.Xdebug is compiled separately, all by itself, as stated above.

2. cd xdebug-3.0.4

3. phpize

   If phpize is not in your path, please make surethat it is by expanding the PATH environment variable. Make sureyou use the phpize that belongs to the PHP version that you want to use Xdebugwith. See this FAQ entry if you're having someissues with finding which phpize to use.

4. ./configure --enable-xdebug

5. make

6. make install

Configure PHP #

1. Add the following line to php.ini:

   zend_extension=/wherever/you/put/it/xdebug

   To find out which php.ini file to modify, run a script with thefollowing:

   Alternatively, you can run php --ini on the command line.

   Note: There could be more than onephp.ini file. In many set-ups there is a different one for thecommand line (often cli/php.ini) and the web server (oftenfpm/php.ini).

   Note: If you want to use Xdebug andOPCache together, you must have the zend_extension line for Xdebugbelow the line for OPCache. Otherwise, they won't work properly together.

2. Restart your webserver, or PHP-FPM, depending on what you areusing.

3. Verify that Xdebug is now loaded.

   Create a PHP page that calls xdebug_info(). If you request thepage through the browser, it should show you an overview of Xdebug's settingsand log messages.

   On the command line, you can also run php -v. Xdebug and itsversion number should be present as in:

With Xdebug loaded, you can now enable individual features, such asStep Debugging, or Profiling.

Related Settings and Functions

• stringxdebug.log =
• integerxdebug.log_level = 7
• stringxdebug.mode = develop

• xdebug_info() : void

Settings

string xdebug.log = #

Configures Xdebug's log file.

Xdebug will log to this file all file creations issues, Step Debuggingconnection attempts, failures, and debug communication.

Enable this functionality by setting the value to a absolute path. Make surethat the system user that PHP runs at (such as www-data if you arerunning with Apache) can create and write to the file.

The file is opened in append-mode,and will therefore not be overwritten by default. There is no concurrencyprotection available.

The log file will include any attempt that Xdebugmakes to connect to an IDE:

It includes the opening time (2020-09-02 07:19:09.616195), theIP/Hostname and port Xdebug is trying to connect to(localhost:9003), and whether it succeeded (Connected toclient :-)). The number in brackets ([2693358]) is theProcess ID.

It includes:

[2693358]

process ID in brackets

2020-09-02 07:19:09.616195

opening time

For Step Debugging:

For Profiling:

For Function Trace:

All warnings and errors are described on the Description of errors page, withdetailed instructions on how to resolve the problem, if possible. All errors are always logged throughPHP's internal logging mechanism (configured with error_login php.ini). All warnings and errors also show up in thediagnostics log that you can view by calling xdebug_info().

Step Debugger Communication

The debugging log can also log the communication between Xdebug and an IDE.This communication is in XML, and starts with the <init XMLelement:

The fileuri attribute lists the entry point of yourapplication, which can be useful to compare to breakpoint_setcommands to see if path mappings are set-up correctly.

Beyond the <init element, you will find the configuration offeatures:

And continuation commands:

You can read about DBGP - A common debugger protocol specification at its dedicated documation page.

The xdebug.log_level setting controls how much information islogged.

Note: Many Linux distributions now use systemd, whichimplements private tmp directories. This means that when PHPis run through a web server or as PHP-FPM, the /tmp directory isprefixed with something akin to:

This setting can additionally be configured through theXDEBUG_CONFIGenvironment variable.

integer xdebug.log_level = 7#

Configures which logging messages should be added to the log file.

The log file is configured with the xdebug.log setting.

The following levels are supported:

Criticals, errors, and warnings always show up in thediagnostics log that you can view by calling xdebug_info().

Criticals and errors are additionally logged throughPHP's internal logging mechanism (configured with error_login php.ini).

This setting can additionally be configured through theXDEBUG_CONFIGenvironment variable.

string xdebug.mode = develop#

This setting controls which Xdebug features are enabled.

This setting can only be set in php.ini orfiles like 99-xdebug.ini that are read when a PHP process starts(directly, or through php-fpm), but not in .htaccess and.user.ini files, which are read per-request.

The following values are accepted:

off

Nothing is enabled. Xdebug does no work besides checking whetherfunctionality is enabled. Use this setting if you want close to 0overhead.

develop

Enables Development Aids including the overloaded var_dump().

coverage

Enables Code Coverage Analysis to generate code coverage reports, mainly incombination withPHPUnit.

debug

Enables Step Debugging. This can be used to step through your code while itis running, and analyse values of variables.

gcstats

Enables Garbage Collection Statistics to collect statistics about PHP's GarbageCollection Mechanism.

profile

Enables Profiling, with which you can analyse performance bottleneckswith tools like KCacheGrind.

trace

Enables the Function Trace feature, which allows you record every functioncall, including arguments, variable assignment, and return value that is madeduring a request to a file.

You can enable multiple modes at the same time by comma separating theiridentifiers as value to xdebug.mode: xdebug.mode=develop,trace.

You can also set the mode by setting the XDEBUG_MODE environmentvariable on the command-line; this will take precedence over the xdebug.mode setting, but will no change the value of the xdebug.mode setting.

Functions

xdebug_info() : void#

This function returns an HTML page which shows diagnostic information. It is analogous to PHP's phpinfo() function.

The HTML output includes which mode is active, what the settings are, and diagnostic information in case there are problems with debugging connections, opening of files, etc.

Each warning and error in the diagnostics log also links through to the Description of errors documentation page.