Cli Xdebug

admin



The port to which Xdebug tries to connect on the remote host. Port 9000 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 setting unchanged. GIBBY 126 West 1570 South, Lehi, Utah 84043. (801) 706-6971. cgibby@gmail.com EXPERIENCE Owner/Developer Match The Memory, Lehi, Utah. October 2009-Present.

Debug PHP code using the Xdebug PHP Extension.

  • Interactive Console
  • Breakpoints
  • Watches
  • Multiple Debug Sessions
  • Path Mappings
  • Step through debugging (Over, In, Out)
  • Stack and Context views
  • UTF8 Support
  • Uses atom-debug-ui

This is currently an alpha release, and still in active development.

Install Xdebug

You may already have Xdebug installed. Check the results of the phpinfo function for xdebug information.If no xdebug section exists, you likely need to install this. *nix users can likely find it within their package manager of choice.Alternative installation or compiling instructions are available here.

Setting up Xdebug

With these settings, PHP will connect to your editor for every script it executes.The alternative is to switch xdebug.remote_autostart to false, and install an Xdebug helper extension for your browser of choice, such as:

  • The easiest Xdebug for Mozilla Firefox
  • Xdebug Helper for Google Chrome

These browser extensions will give you a button within your browser to enable/disable Xdebug. The extensions might have configuration options for an 'IDE key' (which is used for an XDEBUG_SESSION cookie). The IDE key for Atom with PHP Debug is 'xdebug-atom'.

Cli Xdebug

It is also possible to run a php script from the command line with Xdebug enabled.You can find more information on this at the Xdebug documentation for Starting The Debugger.See can find a complete list and explanation of Xdebug settings here.

Start Debugging

To begin debugging:

  1. Open up your PHP file in atom
  2. Add a breakpoint:

Move the cursor to a line you want to break on and set a breakpoint by pressing Alt+F9, selecting Toggle Breakpoint from the Command Palette (ctrl+shift+p)or with the php-debug menu (Packages -> php-debug->Toggle Breakpoint).This will highlight the line number green, to indicate the presence of a breakpoint.

  1. Open the debug view by pressing ctrl+alt+d, selecting 'Toggle Debugging' from the Command Palette or php-debug menu.
  2. Start the script with Xdebug enabled. If everything is setup correctly, the entire line of the breakpoint will be highlighted in green, indicating the current line of the script.

If everything worked correctly, you can now use the various buttons/commands to step through the script.

Server Port

This is the port that the atom client will listen on.Defaults to 9000

Server Address

This is the address that the atom client will listen on.Defaults to 127.0.0.1

Xdebug DBGP Protocol Debugging

Outputs protocol debugging messages to the atom debug console

Xdebug: Max Depth

Max depth for variable scopes

Xdebug: Max children

Maximum number of array elements to show in variables

Xdebug: Max Data

Maximum data for variables

Display: Sort Arrays/Object alphabetically

Sort Arrays/Object alphabetically instead of by php default

Display: Status Bar

Allow PHP Debug to be opened from the status bar

Exceptions

Default exceptions and errors for PHP-Debug to break on

Path Maps

Pathmaps are now configured for each project folder during connection

Installation

Xdebug.cli Color

Install the extension: Press F1, type ext install php-debug.

This extension is a debug adapter between VS Code and Xdebug by Derick Rethans. Xdebug is a PHP extension (a .so file on Linux and a .dll on Windows) that needs to be installed on your server.

  1. Install XdebugI highly recommend you make a simple test.php file, put a phpinfo(); statement in there, then copy the output and paste it into the Xdebug installation wizard. It will analyze it and give you tailored installation instructions for your environment. In short:

    • On Windows: Download the appropriate precompiled DLL for your PHP version, architecture (64/32 Bit), thread safety (TS/NTS) and Visual Studio compiler version and place it in your PHP extension folder.
    • On Linux: Either download the source code as a tarball or clone it with git, then compile it.

  2. Configure PHP to use Xdebug by adding zend_extension=path/to/xdebug to your php.ini. The path of your php.ini is shown in your phpinfo() output under 'Loaded Configuration File'.

  3. Enable remote debugging in your php.ini:

    For Xdebug v3.x.x:

    For Xdebug v2.x.x:

    There are other ways to tell Xdebug to connect to a remote debugger, like cookies, query parameters or browser extensions. I recommend remote_autostart (Xdebug v2)/start_with_request (Xdebug v3) because it 'just works'. There are also a variety of other options, like the port, please see the Xdebug documentation on remote debugging for more information. Please note that the default Xdebug port changed between Xdebug v2 to v3 from 9000 to 9003. The extension still defaults to 9000, so make sure your configuration in launch.json and php.ini match.

  4. If you are doing web development, don't forget to restart your webserver to reload the settings.

  5. Verify your installation by checking your phpinfo() output for an Xdebug section.

VS Code Configuration

In your project, go to the debugger and hit the little gear icon and choose PHP. A new launch configuration will be created for you with two configurations:

  • Listen for XdebugThis setting will simply start listening on the specified port (by default 9000) for Xdebug. If you configured Xdebug like recommended above, everytime you make a request with a browser to your webserver or launch a CLI script Xdebug will connect and you can stop on breakpoints, exceptions etc.
  • Launch currently open scriptThis setting is an example of CLI debugging. It will launch the currently opened script as a CLI, show all stdout/stderr output in the debug console and end the debug session once the script exits.
Xdebug cli vscode

Supported launch.json settings:

  • request: Always 'launch'
  • hostname: The address to bind to when listening for Xdebug (default: all IPv6 connections if available, else all IPv4 connections)
  • port: The port on which to listen for Xdebug (default: 9000)
  • stopOnEntry: Whether to break at the beginning of the script (default: false)
  • pathMappings: A list of server paths mapping to the local source paths on your machine, see 'Remote Host Debugging' below
  • log: Whether to log all communication between VS Code and the adapter to the debug console. See Troubleshooting further down.
  • ignore: An optional array of glob patterns that errors should be ignored from (for example **/vendor/**/*.php)
  • xdebugSettings: Allows you to override Xdebug's remote debugging settings to fine tuning Xdebug to your needs. For example, you can play with max_children and max_depth to change the max number of array and object children that are retrieved and the max depth in structures like arrays and objects. This can speed up the debugger on slow machines.For a full list of feature names that can be set please refer to the Xdebug documentation.
    • max_children: max number of array or object children to initially retrieve
    • max_data: max amount of variable data to initially retrieve.
    • max_depth: maximum depth that the debugger engine may return when sending arrays, hashs or object structures to the IDE.
    • show_hidden: This feature can get set by the IDE if it wants to have more detailed internal information on properties (eg. private members of classes, etc.) Zero means that hidden members are not shown to the IDE.

Options specific to CLI debugging:

  • program: Path to the script that should be launched
  • args: Arguments passed to the script
  • cwd: The current working directory to use when launching the script
  • runtimeExecutable: Path to the PHP binary used for launching the script. By default the one on the PATH.
  • runtimeArgs: Additional arguments to pass to the PHP binary
  • externalConsole: Launches the script in an external console window instead of the debug console (default: false)
  • env: Environment variables to pass to the script

Features

  • Line breakpoints
  • Conditional breakpoints
  • Function breakpoints
  • Step over, step in, step out
  • Break on entry
  • Breaking on uncaught exceptions and errors / warnings / notices
  • Multiple, parallel requests
  • Stack traces, scope variables, superglobals, user defined constants
  • Arrays & objects (including classname, private and static properties)
  • Debug console
  • Watches
  • Run as CLI
  • Run without debugging

Remote Host Debugging

To debug a running application on a remote host, you need to tell Xdebug to connect to a different IP than localhost. This can either be done by setting xdebug.remote_host to your IP or by setting xdebug.remote_connect_back = 1 to make Xdebug always connect back to the machine who did the web request. The latter is the only setting that supports multiple users debugging the same server and 'just works' for web projects. Again, please see the Xdebug documentation on the subject for more information.

To make VS Code map the files on the server to the right files on your local machine, you have to set the pathMappings settings in your launch.json. Example:

Please also note that setting any of the CLI debugging options will not work with remote host debugging, because the script is always launched locally. If you want to debug a CLI script on a remote host, you need to launch it manually from the command line.

Troubleshooting

  • Ask a question on StackOverflow
  • If you think you found a bug, open an issue
  • Make sure you have the latest version of this extension and Xdebug installed
  • Try out a simple PHP file to recreate the issue, for example from the testproject
  • In your php.ini, set xdebug.remote_log = /path/to/logfile(make sure your webserver has write permissions to the file)
  • Set 'log': true in your launch.json

Contributing

To hack on this adapter, clone the repository and open it in VS Code. You need NodeJS with NPM installed. Install dependencies by running npm install.

You can debug the extension (run it in 'server mode') by selecting the 'Debug adapter' launch configuration and hitting F5. Then, open a terminal inside the project, and open the included testproject with VS Code while specifying the current directory as extensionDevelopmentPath:

Xdebug Cli Docker

VS Code will open an 'Extension Development Host' with the debug adapter running. Open .vscode/launch.json and uncomment the debugServer configuration line. Hit F5 to start a debugging session. Now you can debug the testproject like specified above and set breakpoints inside your first VS Code instance to step through the adapter code.

The extension is written in TypeScript. You can compile it through npm run build. npm run watch enables incremental compilation.

Tests are written with Mocha and can be run with npm test. The tests are run in CI on Linux, macOS and Windows against multiple PHP and Xdebug versions.