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.

Introduction

Xdebug's (remote) debugger allows you to examine data structure, interactively walk through your and debug your code. There are two different protocols to communicate with the debugger: the old GDB-like command protocol (GDB) which is implemented in Xdebug 1.3 and 2; and the DBGp protocol which is implemented in Xdebug 2.

Clients

Xdebug 2 is bundled with a simple command line client for the DBGp protocol. There are a few other client implementations (both free and commercial) as well:

• Dev-PHP (IDE: Windows)
• Eclipse plugin, which has been submitted as an enhancement for the PDT (IDE).
• ActiveState's Komodo (IDE: Windows, Linux, Mac; Commercial).
• NetBeans (IDE: Windows, Linux, Mac OS X and Solaris.
• Notepad++ plugin (IDE: Windows).
• WaterProof's PHPEdit (IDE, from version 2.10: Windows; Commercial).
• Anchor System's Peggy (IDE: Windows, Japanese; Commercial).
• MP Software's phpDesigner (IDE: Windows, Commercial).
• Protoeditor (Editor: Linux).
• tsWebeditor (Editor: Windows).
• Xored's TrueStudio IDE (IDE; Commercial).
• VIM plugin (Tutorial) (Editor Plugin).
• jcx software's VS.Php (MS Visual Studio Plugin; Commercial).
• XDebugClient - Standalone Windows client.

A simple command line client for the GDB protocol is bundled with Xdebug 1.3. A client implementation of the deprecated GDB protocol can also be found in the free editor WeaverSlave.

Starting The Debugger

In order to enable Xdebug's debugger you need to make some configuration settings in php.ini. These settings are xdebug.remote_enable to enable the debugger, xdebug.remote_host and xdebug.remote_port to configure the IP address and port where the debugger should connect to and xdebug.remote_handler to configure which debug backend to use ("gdb" or "dbgp"). If you want the debugger to initiate a session when an error situation occurs (php error or exception) then you also need to change the xdebug.remote_mode setting. Allowed values for this setting are "req" (the default) which makes the debugger initiate a session as soon as a script is started, or "jit" when a session should only be initiated on an error.

After made all those settings Xdebug will still not start a debugging session automatically when a script is run. You need to activate Xdebug's debugger and you can do that in two ways:

1. When running the script from the command line you need to set an environment variable, like:

   export XDEBUG_CONFIG="idekey=session_name"
   php myscript.php
   

   You can also configure the xdebug.remote_host, xdebug.remote_port, xdebug.remote_mode and xdebug.remote_handler in this same environment variable. All those configurable settings can also be set with normal php.ini settings.
2. If you want to debug a script started through a web browser, simply add XDEBUG_SESSION_START=session_name as parameter to the URL. Refer to the next section to read on how debug sessions work from within a browser window.

Before you start your script you will need to tell your client that it can receive debug connections, please refer to the documentation of the specific client on how to do this. To use the bundled client simply start it after compiling and installing it. You can start it by running "debugclient". If you want to use the GDB commandset to debug your scripts, make sure you use a debugclient as bundled with Xdebug 1.3 as the one bundled with Xdebug 2 only works with the DBGp commandset.

When the debugclient starts it will show the following information and then waits until a connection is initiated by the debug server:

Xdebug Simple DBGp client (0.10.0)
Copyright 2002-2007 by Derick Rethans.
- libedit support: enabled
	 
Waiting for debug server to connect.

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

Connect
<?xml version="1.0" encoding="iso-8859-1"?>
<init xmlns="urn:debugger_protocol_v1"
      xmlns:xdebug="http://xdebug.org/dbgp/xdebug"
      fileuri="file:///home/httpd/www.xdebug.org/html/docs/index.php"
      language="PHP"
      protocol_version="1.0"
      appid="13202"
      idekey="derick">
  <engine version="2.0.0RC4-dev"><![CDATA[Xdebug]]></engine>
  <author><![CDATA[Derick Rethans]]></author>
  <url><![CDATA[http://xdebug.org]]></url>
  <copyright><![CDATA[Copyright (c) 2002-2007 by Derick Rethans]]></copyright>
</init>
(cmd)

Now you can use the commandset as explained on the DBGp documentation page. When the script ends the debug server disconnects from the client and the debugclient resumes with waiting for a new connection.

HTTP Debug Sessions

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

• When the URL variable XDEBUG_SESSION_START=name is appended to an URL Xdebug emits a cookie with the name "XDEBUG_SESSION" and as value the value of the XDEBUG_SESSION_START URL parameter. The expiry of the cookie is one hour. The DBGp protocol also passes this same value to the init packet when connecting to the debugclient in the "idekey" attribute.
• When there is a GET (or POST) variable XDEBUG_SESSION_START or the XDEBUG_SESSION cookie is set, Xdebug will try to connect to a debugclient.
• To stop a debug session (and to destroy the cookie) simply add the URL parameter XDEBUG_SESSION_STOP. Xdebug will then no longer try to make a connection to the debugclient.

There is also a FireFox 2 extension that allows you to trigger Xdebug's debugger or profiler without having to use XDEBUG_SESSION_START as parameter. You can configure which IDE key it uses. You can find this extension here.

Related Settings

Log opened at 2007-05-27 14:28:15
-> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="http://xdebug.org/dbgp/x ... ight></init>

<- step_into -i 1
-> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="http://xdebug.org/db ... ></response>

Related Functions