Xdebug

https://xdebug.org/docs
Admin
Xdebug is a powerful debugging and profiling tool for PHP that aids in code analysis, error...
Tokens:166,928
Snippets:1,101
Trust Score:9.7
Update:21 hours ago
Show doc for...
Tokens:
Raw
### DBGp proxy startup output

Source: https://xdebug.org/docs/dbgpProxy

Example output when the proxy starts, showing version information and log messages. It indicates that SSL listeners are not enabled if the certificate file is missing, and shows the server and client listener addresses.

```text
Xdebug DBGp proxy (0.3)
Copyright 2020 by Derick Rethans
15:17:35.423 [warn] [SSL] The 'certs/fullchain.pem' file could not be found, not enabling SSL listeners
15:17:35.424 [info] [dbgpProxy] Proxy started
15:17:35.424 [info] [server] Started server server on 127.0.0.1:9003
15:17:35.424 [info] [server] Started client server on 127.0.0.1:9001
```

--------------------------------

### Start DBGp proxy on Linux

Source: https://xdebug.org/docs/dbgpProxy

Run the proxy binary on Linux from a shell. If the binary doesn't start or you get a 'not found' message, refer to the FAQ entry about Linux not found.

```bash
./dbgpProxy
```

--------------------------------

### Start dbgpClient on Linux

Source: https://xdebug.org/docs/dbgpClient

Run the client from a shell on Linux. If you get a 'not found' message, see the FAQ entry about Linux binary not found.

```bash
./dbgpClient
```

--------------------------------

### Start a function trace with xdebug_start_trace

Source: https://xdebug.org/docs/all_functions

Starts a function trace to a specified file. The example uses XDEBUG_TRACE_COMPUTERIZED and XDEBUG_TRACE_NAKED_FILENAME flags to create a tab-separated trace file without the .xt extension. The file is created at /tmp/xdebug.trace.

```php
<?php
xdebug_start_trace("/tmp/xdebug.trace", XDEBUG_TRACE_COMPUTERIZED|XDEBUG_TRACE_NAKED_FILENAME);
?>
```

--------------------------------

### xdebug_code_coverage_started() example and output

Source: https://xdebug.org/docs/all_functions

Shows how to check if code coverage is active before and after starting it. The output demonstrates that it returns false initially and true after calling xdebug_start_code_coverage().

```php
<?php
    var_dump(xdebug_code_coverage_started());

    xdebug_start_code_coverage();

    var_dump(xdebug_code_coverage_started());
?>
```

```text
bool(false)
bool(true)
```

--------------------------------

### xdebug_get_monitored_functions example and output

Source: https://xdebug.org/docs/all_functions

Example PHP code that starts a function monitor for strrev and array_push, runs some code, and then retrieves the monitored functions. The output shows the function name, filename, and line number for each monitored call.

```php
<?php
/* Start the function monitor for strrev and array_push: */
xdebug_start_function_monitor( [ 'strrev', 'array_push' ] );

/* Run some code: */
echo strrev("yes!"), "\n";

echo strrev("yes!"), "\n";

var_dump(xdebug_get_monitored_functions());
xdebug_stop_function_monitor();
?>
```

```plaintext
/tmp/monitor-example.php:10:
array(2) {
  [0] =>
  array(3) {
    'function' =>
    string(6) "strrev"
    'filename' =>
    string(24) "/tmp/monitor-example.php"
    'lineno' =>
    int(6)
  }
  [1] =>
  array(3) {
    'function' =>
    string(6) "strrev"
    'filename' =>
    string(24) "/tmp/monitor-example.php"
    'lineno' =>
    int(8)
  }
}
```

--------------------------------

### xdebug_time_index() example

Source: https://xdebug.org/docs/all_functions

Shows how to use xdebug_time_index() to measure the time index since script start. The example echoes the time index before and after a loop that does nothing. The output shows the time index values in seconds.

```php
<?php
echo xdebug_time_index(), "\n";
for ($i = 0; $i < 250000; $i++)
{
    // do nothing
}
echo xdebug_time_index(), "\n";
?>
```

--------------------------------

### Install Xdebug with PECL

Source: https://xdebug.org/docs/install

Run this command to install Xdebug via PECL. Ignore any prompts to add 'extension=xdebug.so' to php.ini, as this will cause problems. After installation, check with 'php -v' to see if Xdebug is loaded.

```bash
pecl install xdebug
```

--------------------------------

### Install Xdebug on Gentoo with emerge

Source: https://xdebug.org/docs/install

Use the emerge package manager to install Xdebug on Gentoo.

```bash
emerge dev-php/xdebug
```

--------------------------------

### Start function monitoring for functions

Source: https://xdebug.org/docs/all_functions

Starts monitoring for the given functions. The list is case sensitive, and dynamic calls to static methods are not caught.

```php
<?php
xdebug_start_function_monitor( [ 'strrev', 'array_push' ] );
?>
```

--------------------------------

### Install Xdebug for arm64e Architecture

Source: https://xdebug.org/docs/install

Run this command if 'file `which php`' reports 'arm64e'. It forces the installation to use the native ARM64 architecture.

```bash
arch -arm64 sudo pecl install xdebug
```

--------------------------------

### xdebug.trace_options bitfield example

Source: https://xdebug.org/docs/all_settings

Shows how to combine trace_options flags using bitwise OR. The example enables tab-separated format and disables automatic .xt extension.

```ini
xdebug.trace_options=0x02|0x08
```

--------------------------------

### xdebug.file_link_format example format

Source: https://xdebug.org/docs/all_settings

Example format for the xdebug.file_link_format setting, using %f for filename and %l for line number.

```plaintext
myide://%f@%l
```

--------------------------------

### Install Xdebug for x86_64 Architecture

Source: https://xdebug.org/docs/install

Run this command if 'file `which php`' reports 'x86_64'. It forces the installation to use the emulated x86_64 architecture.

```bash
arch -x86_64 sudo pecl install xdebug
```

--------------------------------

### Start function monitoring for class methods

Source: https://xdebug.org/docs/all_functions

Starts monitoring for static and dynamic class methods. The list is case sensitive, and dynamic calls to static methods are not caught.

```php
<?php
xdebug_start_function_monitor( [ 'DramModel::canSee', 'Whisky->drink'] );
?>
```

--------------------------------

### Start dbgpClient on Windows

Source: https://xdebug.org/docs/dbgpClient

Run the client from a Command Prompt on Windows.

```bash
dbgpClient.exe
```

--------------------------------

### Start DBGp proxy on Windows

Source: https://xdebug.org/docs/dbgpProxy

Run the proxy binary on Windows from a Command Prompt.

```batch
dbgpProxy.exe
```

--------------------------------

### Install Xdebug with PIE

Source: https://xdebug.org/docs/install

Run this command to install Xdebug using PIE. On Linux and macOS, PIE compiles from source; on Windows, it downloads pre-built binaries. PIE also attempts to enable Xdebug by creating an INI file or adding a line to php.ini.

```bash
pie install xdebug/xdebug
```

--------------------------------

### xdebug_get_code_coverage() example

Source: https://xdebug.org/docs/code_coverage

Starts code coverage with XDEBUG_CC_UNUSED and XDEBUG_CC_DEAD_CODE flags, defines functions a() and b(), calls b() twice, and dumps the coverage array.

```php
<?php
xdebug_start_code_coverage(XDEBUG_CC_UNUSED | XDEBUG_CC_DEAD_CODE);

function a($a) {
    return;
    echo $a * 2.5;
}

function b($count) {
    if ($count > 25) {
        echo "too much\n";
    }
    for ($i = 0; $i < $count; $i++) {
        a($i + 0.17);
    }
}

b(6);
b(10);

var_dump(xdebug_get_code_coverage());
?>
```

--------------------------------

### Start dbgpClient on macOS

Source: https://xdebug.org/docs/dbgpClient

Run the client from a shell on macOS.

```bash
./dbgpClient-macos
```

--------------------------------

### Check phpize path with phpize --help

Source: https://xdebug.org/docs/faq

Run 'phpize --help' to display the full path to phpize. This path should match where the CLI binary, php-config, and pear/pecl binaries are installed.

```bash
phpize --help
```

--------------------------------

### proxyinit

Source: https://xdebug.org/docs/dbgp

The IDE sends this command to the proxy when it starts to register itself and specify the port it listens on for debugging connections, along with an IDE key and multi-session support flag.

```APIDOC
## proxyinit

### Description
Registers the IDE with the proxy, providing the port the IDE listens on for debugging, an IDE key, and whether multiple debugger sessions are supported.

### Command
`proxyinit -p port -k ide_key -m [0|1]`

### Parameters
- **-p** (integer) - Required - The port that the IDE listens for debugging on. The address is retrieved from the connection information.
- **-k** (string) - Required - An IDE key, which the debugger engine will also use in its debugging init command. This allows the proxy to match requests to the IDE.
- **-m** (integer) - Optional - Indicates whether the IDE supports multiple debugger sessions. If missing, zero or no support is default.

### Response
#### Success Response
```xml
<proxyinit success="[0|1]"
           idekey="{ID}"
           address="{IP_ADDRESS}"
           port="{NUM}">
    <error id="app_specific_error_code">
        <message>UI Usable Message</message>
    </error>
</proxyinit>
```

The `address` and `port` attributes indicate the address and port that the proxy is configured to listen for DBGP connections on.
```

--------------------------------

### Check PHP Architecture

Source: https://xdebug.org/docs/install

Use this command to determine whether your PHP is compiled for arm64e or x86_64. The output will guide which 'arch' flag to use when installing Xdebug.

```bash
file `which php`
```

--------------------------------

### Example DBGp commands: step_into and context_get

Source: https://xdebug.org/docs/dbgpClient

Shows an interactive session where the user steps into the next line and then retrieves the current context variables. The output includes the command echo and the response.

```text
(cmd) step_into
1 | step_into > break/ok
1 | file:///tmp/xdebug-test-2.php:14

(cmd) context_get
2 | context_get
2 | uninitialized $a
```

--------------------------------

### xdebug_get_function_stack with from_exception option

Source: https://xdebug.org/docs/all_functions

Example PHP script that calls xdebug_get_function_stack with the 'from_exception' option, passing a thrown exception. This should be used in a user-defined exception handler to get the stack trace of where the exception was thrown.

```php
<?php
class Handlers
{
    function __construct(private string $title, private float $PIE) {}

    static function exceptionHandler($exception)
    {
        var_dump( xdebug_get_function_stack( [ 'from_exception' => $exception ] ) );
    }
}

class Elephpant
{
    function __construct(private string $title, private string $PIE) {}
}

class Error_Class
{
    public static function newError($errno = false)
    {
        $elephpant = new Elephpant("Bluey", M_PI);
        $randoVar = 42;

        throw new Exception();
    }

}

class Error_Entry
{
    public function __construct($base, $errno)
    {
        $return = Error_Class::newError(true);
    }
}

set_exception_handler(['Handlers', 'exceptionHandler']);
$e = new Error_Entry(1, 2);

?>
```

--------------------------------

### step_into command and response

Source: https://xdebug.org/docs/garbage_collection

Example of a step_into continuation command and its XML response, showing the status and reason, along with the current file and line number.

```XML
<- step_into -i 9
-> <response
       xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug"
       command="step_into" transaction_id="9"
       status="break" reason="ok">
           <xdebug:message filename="file:///home/httpd/www.xdebug.org/html/router.php" lineno="3">
           </xdebug:message>
   </response>
```

--------------------------------

### Example output of xdebugctl ps

Source: https://xdebug.org/docs/xdebugctl

Sample output from the 'xdebugctl ps' command showing running PHP scripts with their process details.

```text
       PID      RSS     TIME COMMAND
   1414004     1193 23596.36 /home/derick/dev/derickr-mqtt-fun/test.php (Xdebug3.5.0alpha3)
   2638744      510    10.51 /tmp/show-time.php (Xdebug3.5.0alpha4-dev)
```

--------------------------------

### DBGp proxy client registration output

Source: https://xdebug.org/docs/dbgpProxy

Example output when a client registers with the proxy, showing the IDE key and the client's address. The client should then be ready to accept debugging connections on its registered port.

```text
15:18:57.087 [info] [server] Start new client connection from 127.0.0.1:54196
15:18:57.087 [info] [proxyinit] [derickr] Added connection for IDE Key 'derickr': 127.0.0.1:9099
15:18:57.087 [info] [server] Closing client connection from 127.0.0.1:54196
```

--------------------------------

### Xdebug init XML element

Source: https://xdebug.org/docs/garbage_collection

Example of the XML init element sent by Xdebug to the IDE at the start of a debugging session. The fileuri attribute lists the entry point of the application, useful for comparing with breakpoint_set commands to verify path mappings.

```XML
<init
    xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug"
    fileuri="file:///home/httpd/www.xdebug.org/html/router.php"
    language="PHP" xdebug:language_version="7.4.11-dev"
    protocol_version="1.0" appid="2693358" idekey="XDEBUG_ECLIPSE">
        <engine version="3.0.0-dev"><![CDATA[Xdebug]]></engine>
        <author><![CDATA[Derick Rethans]]></author>
        <url><![CDATA[https://xdebug.org]]></url>
        <copyright><![CDATA[Copyright (c) 2002-2020 by Derick Rethans]]></copyright>
</init>
```

--------------------------------

### Install Xdebug on CentOS with yum

Source: https://xdebug.org/docs/install

Use the yum package manager to install Xdebug on CentOS. The command installs the php-xdebug package.

```bash
sudo yum install php-xdebug
```

--------------------------------

### Install Xdebug on Alpine Linux with apk

Source: https://xdebug.org/docs/install

Use the apk package manager to install Xdebug on Alpine Linux. The command installs the PHP 7 or PHP 8 PECL Xdebug package.

```bash
sudo apk add php7-pecl-xdebug
```

```bash
sudo apk add php8-pecl-xdebug
```

--------------------------------

### Start DBGp proxy on macOS

Source: https://xdebug.org/docs/dbgpProxy

Run the proxy binary on macOS from a shell.

```bash
./dbgpProxy-macos
```

--------------------------------

### Install Xdebug on Ubuntu (Ondřej Surý's PPA) with apt-get

Source: https://xdebug.org/docs/install

Use the apt-get package manager with Ondřej Surý's PPA to install Xdebug on Ubuntu. The PHP version in the package name can be substituted to match your PHP version.

```bash
sudo apt-get install php7.4-xdebug
```

```bash
sudo apt-get install php8.0-xdebug
```

```bash
sudo apt-get install php8.1-xdebug
```

--------------------------------

### dbgpClient startup output

Source: https://xdebug.org/docs/dbgpClient

Shows the version information and the message displayed while waiting for a debug server connection on port 9003.

```text
Xdebug Simple DBGp client (0.4.2)
Copyright 2019-2020 by Derick Rethans

Waiting for debug server to connect on port 9003.
```
Tokens:
Raw