Xdebug is an opensource Debugger and Profiler for PHP. PDT has built in support for Xdebug, which allows you to step-debug through your PHP projects. The first step is to install Xdebug and verify that Xdebug is running. See the Installation section of the Xdebug manual for how to obtain the extension. Xdebug is an opensource Debugger and Profiler for PHP. PDT has built in support for Xdebug, which allows you to step-debug through your PHP projects. The first step is to install Xdebug and verify that Xdebug is running. See the Installation section of the Xdebug manual for how to obtain the extension.
Xdebug allows you to log all function calls, including parameters and return values to a file in different formats.
Xdebug.remoteport has an interesting quirk in that if you don’t set the parameter, it defaults to port 9000. I guess it’s an interesting aspect that shows Xdebug’s history in that it was probably chosen as a default port before the CGI adopted replacement php-fpm used port 9000. While filling the details, make sure the setting specified in the php.ini file should match with IDE KEY and click Ok. Open the PHP file you want to debug in the Notepad and add a breakpoint to the script. You will see the Notepad icon blinking on the taskbar. Click on it and start debugging.
Those so-called 'function traces' can be a help for when you are new to anapplication or when you are trying to figure out what exactly is going on whenyour application is running. The function traces can optionally also show thevalues of variables passed to the functions and methods, and also returnvalues. In the default traces those two elements are not available.
Output Formats #
There are three output formats. One is meant as a human readable trace, anotherone is more suited for computer programs as it is easier to parse, and the lastone uses HTML for formatting the trace. You can switch between the twodifferent formats with the xdebug.trace_format setting. There are a few settingsthat control which information is written to the trace files. There aresettings for including variable assignments (xdebug.collect_assignments) and forincluding return values (xdebug.collect_return) for example. The example belowshows what effect the different settings have for the human readable functiontraces.
The Script
<?php
$str = 'Xdebug';
function ret_ord( $c )
{
return ord( $c );
}
foreach ( str_split( $str ) as $char )
{
echo $char, ': ', ret_ord( $char ), 'n';
}
?>
The Results
A typical output without the xdebug.collect_return orxdebug.collect_assignments features turned on is the following trace:
There are a number of settings that affect the output of trace files.
To show the return values of all function and method calls,turn on the xdebug.collect_return and xdebug.collect_assignments settings.
The default format is meant for consumption by humans. It is also possible togenerate a tab separated trace by setting xdebug.trace_format to 1.
The Xdebug source distribution has a scriptthat can be used to run some minimal analyses on these files.
VIM syntax file #
Xdebug ships with a VIM syntax file that syntax highlights the trace files:xt.vim. In order to make VIM recognise this new format you need to perform thefollowing steps:
- Copy the xt.vim file to ~/.vim/syntax
- Edit, or create, ~/.vim/filetype.vim and add the following lines:
With those settings made an opened trace file looks like:
Folding also sorta works so you can use zc and zo to fold awayparts of the trace files.
Related Settings and Functions
- booleanxdebug.collect_assignments = false
- booleanxdebug.collect_return = false
- stringxdebug.log =
- integerxdebug.log_level = 7
- stringxdebug.mode = develop
- stringxdebug.output_dir = /tmp
- stringxdebug.start_with_request = default
- integerxdebug.trace_format = 0
- integerxdebug.trace_options = 0
- stringxdebug.trace_output_name = trace.%c
- stringxdebug.trigger_value = '
- integerxdebug.var_display_max_children = 128
- integerxdebug.var_display_max_data = 512
- integerxdebug.var_display_max_depth = 3
- xdebug_get_tracefile_name() : mixed
- xdebug_info() : void
- xdebug_start_trace() : ?string
- xdebug_stop_trace() : false|string
Settings
boolean xdebug.collect_assignments = false#
This setting, defaulting to 0, controls whether Xdebug should addvariable assignments to function traces. Assign-by-var (=&)assignments are included too.
boolean xdebug.collect_return = false#
This setting, defaulting to 0, controls whether Xdebug should write thereturn value of function calls to the trace files.
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:
| Level | Name | Example |
|---|---|---|
| 0 | Criticals | Errors in the configuration |
| 1 | Errors | Connection errors |
| 3 | Warnings | Connection warnings |
| 5 | Communication | Protocol messages |
| 7 | Information | Information while connecting |
| 10 | Debug | Breakpoint resolving information |
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.
string xdebug.output_dir = /tmp#
The directory where Xdebug will write tracing, profiling, and garbagecollection statistics to. This directory needs to be writable for the systemuser with which PHP is running.
This setting can be changed in php.ini, .htaccess(and equivalent files), and within a PHP file with ini_set().
In some cases (when profiling, or whenxdebug.start_with_request=yes with tracing), Xdebugcreates the file before the script runs. In that case, changes made throughini_set() will not be taken into account.
This setting can additionally be configured through theXDEBUG_CONFIGenvironment variable.
string xdebug.start_with_request = default#
A Function Trace, Garbage Collection Statistics, Profiling, or Step Debuggingcan be activated at the start of a PHP request. Whether this happens depends onthe value of this setting:
yesThe functionality starts when the PHP request starts, and before any PHPcode is run.
For example xdebug.mode=trace andxdebug.start_with_request=yes starts a Function Trace for thewhole request.
noThe functionality does not get activated when the request starts.
You can still start a Function Trace with xdebug_start_trace(), Step Debugging with xdebug_break(), or Garbage Collection Statistics with xdebug_start_gcstats().
triggerThe functionality only gets activated when a specific trigger is presentwhen the request starts.
The name of the trigger is XDEBUG_TRIGGER, and Xdebug checksfor its presence in either $_ENV (environment variable),$_GET or $_POST variable, or $_COOKIE(HTTP cookie name).
There is also a legacy fallback to a functionality specific trigger name:XDEBUG_PROFILE (for Profiling), XDEBUG_TRACE(for a Function Trace), and XDEBUG_SESSION (forStep Debugging).
Debug session management for Step Debugging is alsoavailable through XDEBUG_SESSION_START.
With xdebug.trigger_value you can control which specific trigger value willactivate the trigger. If xdebug.trigger_value is set to an emptystring, any value will be accepted.
defaultThe default value depends on xdebug.mode:
- debug:
trigger - gcstats:
no - profile:
yes - trace:
trigger
integer xdebug.trace_format = 0#
The format of the trace file.
| Value | Description |
|---|---|
| 0 | shows a human readable indented trace file with:time index, memory usage, memory delta,level, function name,function parameters,filename and line number. |
| 1 | writes a computer readable format which has twodifferent records. There are different records for entering a stack frame, andleaving a stack frame. The table below lists the fields in each type of record.Fields are tab separated. |
| 2 | writes a trace formatted in (simple) HTML. |
Fields for the computerized format:
| Record type | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 - ... |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Entry | level | function # | always '0' | time index | memory usage | function name | user-defined (1) or internal function (0) | name of the include or require file | filename | line number | no. of arguments | arguments (as many as specified in field 11) - tab separated |
| Exit | level | function # | always '1' | time index | memory usage | empty | ||||||
| Return | level | function # | always 'R' | empty | return value | empty | ||||||
See the introduction for Function Trace for a few examples.
integer xdebug.trace_options = 0#
When set to '1' the trace files will be appended to, instead ofbeing overwritten in subsequent requests.
string xdebug.trace_output_name = trace.%c#
This setting determines the name of the file that is used to dumptraces into. The setting specifies the format with format specifiers, verysimilar to sprintf() and strftime(). There are several format specifiersthat can be used to format the file name. The '.xt' extension is always addedautomatically.
The possible format specifiers are:
| Specifier | Meaning | Example Format | Example Filename |
|---|---|---|---|
| %c | crc32 of the current working directory | trace.%c | trace.1258863198.xt |
| %p | pid | trace.%p | trace.5174.xt |
| %r | random number | trace.%r | trace.072db0.xt |
| %s | script name 2 | cachegrind.out.%s | cachegrind.out._home_httpd_html_test_xdebug_test_php |
| %t | timestamp (seconds) | trace.%t | trace.1179434742.xt |
| %u | timestamp (microseconds) | trace.%u | trace.1179434749_642382.xt |
| %H | $_SERVER['HTTP_HOST'] | trace.%H | trace.kossu.xt |
| %R | $_SERVER['REQUEST_URI'] | trace.%R | trace._test_xdebug_test_php_var=1_var2=2.xt |
| %U | $_SERVER['UNIQUE_ID'] 3 | trace.%U | trace.TRX4n38AAAEAAB9gBFkAAAAB.xt |
| %S | session_id (from $_COOKIE if set) | trace.%S | trace.c70c1ec2375af58f74b390bbdd2a679d.xt |
| %% | literal % | trace.%% | trace.%%.xt |
2 This one is only available for trace file names since Xdebug 2.6.
3 New in version 2.2. This one is set by Apache's mod_unique_id module
string xdebug.trigger_value = '#
This setting can be used when xdebug.start_with_request is set totrigger, which is the default for Step Debugging and Function Trace.
In trigger mode, Xdebug will only start itsfunctionality when the XDEBUG_TRIGGER is set in the environment,or when the XDEBUG_TRIGGER GET, POST, or COOKIE variable isset.
The legacy names XDEBUG_SESSION (for Step Debugging),XDEBUG_PROFILE (for Profiling), and XDEBUG_TRACE(for Function Trace) can also be used instead of XDEBUG_TRIGGER.
Normally, Xdebug does not look at which value is actually used. If thissetting is set to a non-empty string, then Xdebug will only trigger if thevalue matches the value of this setting.
With the following settings:
Xdebug's profiler will only start when either the environment variableXDEBUG_TRIGGER is set to StartProfileForMe, the GETor POST variable XDEBUG_TRIGGER is set toStartProfileForMe, or when the cookie XDEBUG_TRIGGERhas the value StartProfileForMe.
See also:
- xdebug.start_with_request#trigger
- For how the triggering mechanism works, and which environment and server variables Xdebug acts on.
integer xdebug.var_display_max_children = 128#
Controls the amount of array children and object's properties are shownwhen variables are displayed with either xdebug_var_dump(),xdebug.show_local_vars or when making a Function Trace.
To disable any limitation, use -1 as value.
This setting does not have any influence on the number of children that issend to the client through the Step Debugging feature.
integer xdebug.var_display_max_data = 512#
Controls the maximum string length that is shownwhen variables are displayed with either xdebug_var_dump(),xdebug.show_local_vars or when making a Function Trace.
To disable any limitation, use -1 as value.
This setting does not have any influence on the number of children that issend to the client through the Step Debugging feature.
integer xdebug.var_display_max_depth = 3#
Controls how many nested levels of array elements and object properties arewhen variables are displayed with either xdebug_var_dump(),xdebug.show_local_vars or when making a Function Trace.
The maximum value you can select is 1023. You can also use -1 asvalue to select this maximum number.
This setting does not have any influence on the number of children that issend to the client through the Step Debugging feature.
Setting the value to a high number could potentially result inPHP using up all the available memory, so use with caution.
Functions
xdebug_get_tracefile_name() : mixed#
Returns the name of the file which is used to trace the output of this script to, or null if tracing is not active. This is useful when the trace was started automatically because xdebug.start_with_request was set to yes.
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.
xdebug_start_trace( ?string $traceFile = null, int $options = 0 ) : ?string#
Start tracing function calls from this point to the file in the $trace_file parameter. If no filename is given, then the trace file will be placed in the directory as configured by the xdebug.output_dir setting.
In case a file name is given as first parameter, the name is relative to the current working directory. This current working directory might be different than you expect it to be, so please use an absolute path in case you specify a file name. Use the PHP function getcwd() to figure out what the current working directory is.
The name of the trace file is {$trace_file}.xt. If the trace was started at the beginning of the request because xdebug.start_with_request is set to yes, then the filename depends on the xdebug.trace_output_name setting.
The options parameter is a bitfield; currently there are three options:
The options parameter is a bitfield; currently there are three options:
- XDEBUG_TRACE_APPEND (1)
- makes the trace file open in append mode rather than overwrite mode
- XDEBUG_TRACE_COMPUTERIZED (2)
- creates a trace file with the format as described under 1 'xdebug.trace_format'.
- XDEBUG_TRACE_HTML (4)
- creates a trace file as an HTML table
- XDEBUG_TRACE_NAKED_FILENAME (8)
- Normally, Xdebug always adds '.xt' to the end of the filename that you pass in as first argument to this function. With the XDEBUG_TRACE_NAKED_FILENAME flag set, '.xt' is not added.
The settings xdebug.collect_assignments and xdebug.collect_return influence what information is logged to the trace file and the setting xdebug.trace_format influences the format of the trace file.
The full path and filename to which Xdebug traces is returned from this function. This will be either the filename you pass in (potentially with '.xt' added), or the auto generated filename if no filename has been passed in.
xdebug_stop_trace() : false|string#
Stop tracing function calls and closes the trace file.
The function returns the filename of the file where the trace was written to.
03 Dec 2020
Requirements
- XAMPP for Windows: https://www.apachefriends.org/download.html
Setup
- Download Xdebug for the specific PHP version:
- PHP 8.0 (64-Bit): https://xdebug.org/files/php_xdebug-3.0.0-8.0-vs16-x86_64.dll
- Move the downloaded dll file to:
C:xamppphpext - Rename the dll file to:
php_xdebug.dll - Open the file
C:xamppphpphp.iniwith Notepad++ - Disable output buffering:
output_buffering = Off - Scroll down to the
[XDebug]section (or create it) and copy/paste these lines:
- Restart Apache
PhpStorm
- Enable the Xdebug option: “Can accept external connections” and “Additionally listen on Xdebug 3 default port 9003”. Screenshot
- Use the PhpStorm bookmarklets generator to activate Xdebug from the browser side.
Xdebug With Postman Free
Netbeans
- Change the Netbeans debugging options: Screenshot
Xdebug With Postman Download
Visual Studio Code
- Install the PHP Debug Adapter for Visual Studio Code.
Postman
Xdebug With Postman App
Add XDEBUG_SESSION_START=PHPSTORM as query parameter to the url, e.g.
- http://localhost?XDEBUG_SESSION_START=PHPSTORM
Start debugger from the console
Enter cmd:
Known Issues
Xdebug With Postman Extension
Please enable JavaScript to view the comments powered by Disqus.