Debugging PHP

Komodo can be used to debug PHP programs locally or remotely. Remote PHP debugging encompases all types of PHP debugging not initiated from within Komodo, including debugging PHP scripts running under a local web server.

The instructions below describe how to configure Komodo and PHP for debugging. For general information about using the Komodo debugger, see Komodo Debugger Functions.

Komodo uses a PHP debugger extension called Xdebug that must be installed for Komodo to debug PHP scripts. This can be done manually or with the PHP Configuration Wizard. Pre-built binaries named "php_xdebug.dll" (for Windows) or "xdebug.so" (for Linux and Solaris) are provided with Komodo and are also available for download from the Komodo Remote Debugging page.

See www.xdebug.org/install.php for instructions on compiling Xdebug from source on other platforms.

Tutorial

Installing PHP

PHP debugging in Komodo requires PHP version 4.3.1 or greater (including PHP 5). Download PHP from http://www.php.net/downloads.php.

To debug PHP scripts in a web environment, be sure PHP is operating correctly with your web server before configuring the debugger extension. Consult the PHP documentation for details on configuring PHP with various web servers.

Windows

If you are unfamiliar with the installation of PHP, we recommend using the Windows InstallShield package. To install the PHP executable or SAPI module manually, see the PHP website. Be sure that the PHP directory is included in your system's PATH.

Linux

Your Linux system may already have PHP installed. Login and type 'php -v' to determine the version of your current PHP interpreter. If it is earlier than version 4.3.1 you must upgrade. PHP must also support loading dynamic extensions (the default for PHP under Linux). If it does not, reinstall PHP as per the instructions on the PHP website.

When installing PHP to a non-default directory, you must add the following argument to the ./configure command:

	--with-config-file-path=/path/to/php.ini

...where /path/to/php.ini is the full path to the directory where the php.ini file is located.

Refer to the PHP website for further information on installing PHP.

 

Local PHP Debugging

In local debugging mode, Komodo executes PHP directly. While this is convenient for quickly debugging a PHP script, if your script depends on the availability of a web server, use Remote PHP Debugging even if the script is running on the same machine as Komodo. This makes it possible to test the script in its true environment.

When debugging locally, certain environment variables are not available, such as those provided by the CGI environment. However, it is possible to simulate a CGI environment by specifying CGI environment variables and CGI input in the Debugging Options dialog box. It is is not necessary to install a web server to use Komodo's local debugging features. Once you have configured PHP to use the debugger extension as described below, you can debug your scripts by opening a PHP file and using Komodo Debugger Functions.

If you receive an error message when attempting to debug a PHP script, check the PHP troubleshooting section of the Komodo FAQ.

Configuring Local PHP Debugging

Before debugging PHP scripts in Komodo, PHP must be configured to use the Xdebug extension (php_xdebug.dll or xdebug.so).

Komodo's PHP Configuration Wizard simplifies the process of selecting a PHP executable to use for local debugging. It copies the php.ini file to a new directory, modifies it for debugging, then copies the Xdebug extension to the directory defined in the .ini file. The PHP Configuration Wizard should only be used to configure local debugging. To debug PHP remotely, see Configuring Remote PHP Debugging.

To start the wizard:

  1. On the Edit menu, click Preferences.
  2. Under Languages, select PHP.
  3. Click the Debugger Configuration Wizard button to display the wizard's introductory window.
  4. Click Next to begin configuring PHP for debugging.

The wizard will guide you through the steps necessary to configure the debugging extension.

  1. Choose Installation:

    The first step assumes that you have already installed PHP. If you have more than one version of PHP installed, choose the version to configure. Browse to the directory containing the PHP executable or enter the directory path in the Set up this installation field, and then click Next.

  2. Choose PHP INI Path:

    Next, choose the php.ini file to be copied and its destination directory. Subsequent changes to the original file will not be available in the new copy. Modify the new file directly, or rerun the wizard to copy the changes. Click Next.

    • On Windows, the php.ini file is generally located in c:\windows, or c:\winnt, depending on your operating system. It may also be located in the same directory as your php.exe executable.
    • On Linux, the default location is /usr/local/lib. It may also be located in the same directory as your PHP executable.

  3. Choose PHP Extension Directory:

    Many PHP installations already include a default "extensions" directory. This is where the debugger extension should be installed. If you have specified an extensions directory in the .ini file, you do not need to change the path that appears in the Use this extensions directory field. It is important that the extensions are installed in the same directory as your PHP installation. If you choose a different location, some extensions may not work. Once the desired path is set, click Next.

  4. Ready to Install:

    The final window in the wizard displays the installation options. Confirm that the selections are correct and click Next. To change any of the selections, click Back.

Starting and Stopping a PHP Local Debugging Session

To step through the script, from Debug menu, select Step In or press 'F11'.

To run the script to the first breakpoint, from the Debug menu, select Go/Continue or press 'F5'.

To stop the debugger, from the Debug menu, select Stop, or press 'Shift+F5'.

See Komodo Debugger Functions for full instructions on using Komodo's debugging functionality.

 

Remote PHP Debugging

Remote PHP debugging encompases all types of PHP debugging not initiated from within Komodo, including debugging PHP scripts running under a local web server.

When a PHP script is run through a web browser, the web server uses the PHP interpreter to execute the script. If PHP is configured for remote debugging, the server contacts Komodo to start a debugging session. Komodo controls the debugging (e.g. stepping and breakpoints) once the session starts. CGI variables are available, as are all other variables that are available when running PHP under a web server.

Though remote PHP debugging allows PHP scripts to be run in their true environment, it may be slower than local PHP debugging.

Configuring Remote PHP Debugging

Remote debugging of PHP in Komodo is set up differently depending on how many people will be debugging scripts on the same web server:

Single User Remote PHP Debugging: In single user remote debugging, PHP is configured to always look for a specific instance of Komodo on a specific machine. This configuration requires no changes to the PHP script. Your web server and your instance of Komodo can be on one machine or two machines

Multi-User Remote PHP Debugging: When multiple users need to debug PHP scripts on a single web server, use the DBGP Proxy with the remote PHP debugging instructions below. While it is possible to configure Apache with Virtual Hosting, it is easier to configure multi-user remote PHP debugging with the proxy.

Remote PHP debugging must be configured manually. The following procedure assumes that you have already installed PHP.

Step 1 - Copy the Debugging Extension to the Web Server

Before debugging PHP scripts in Komodo, PHP must be configured to use the Xdebug extension (php_xdebug.dll or xdebug.so).

Manually copy xdebug.so (Unix) or php_xdebug.dll (Windows) into a directory on the server that the PHP interpreter and web server can access. We recommend installing Xdebug in the existing PHP extensions directory on the web server (specified by the extension_dir variable in the php.ini file). These Xdebug files can be found in the php/debugging/<PHP version> sub-directory of the Komodo installation or downloaded from the Komodo Remote Debugging page.

If you are installing PHP for the first time, the extension_dir may be set to "./". You should change this to a full, direct path, such as C:\php\extensions under Windows, or /usr/local/lib/php/extensions under Linux.

Windows

  • File required: php_xdebug.dll
  • Source location: <komodo-install-directory>\php\debugging\<PHP-version> or the Komodo Remote Debugging page.
  • Destination: the extension_dir directory as defined in the php.ini file.

Linux

  • File required: xdebug.so
  • Source location: <komodo-install-directory>/php/debugging/<PHP-version>/
  • Destination: the extension_dir directory as defined in the php.ini file.

Step 2 - Edit the Web Server's PHP Configuration

Windows

Open the php.ini configuration file on the web server. In the "Dynamic Extension" section, add the following lines:

	; xdebug config for Windows
	zend_extension_ts=c:\path\to\php_xdebug.dll
	xdebug.remote_enable=1
	xdebug.remote_handler=dbgp
	xdebug.remote_mode=req
        xdebug.remote_host=127.0.0.1
	xdebug.remote_port=9000
	xdebug.idekey=<idekey>

Note: The php.ini configuration file should be in your operating system directory (e.g. C:\WINDOWS or C:\WINNT), or in the same directory as php.exe (e.g. C:\PHP). If you used the PHP Windows installer, this file should be in the correct location.

Linux

Open the php.ini configuration file on the web server. In the "Dynamic Extension" section, add the following lines:

	; xdebug config for Linux
	zend_extension=/path/to/xdebug.so
	xdebug.remote_enable=1
	xdebug.remote_handler=dbgp
	xdebug.remote_mode=req
        xdebug.remote_host=127.0.0.1
	xdebug.remote_port=9000
	xdebug.idekey=<idekey>

Set the remote_port to the same value as the debugging listener port configured in Edit|Preferences|Debugger. If Komodo is not running on the same machine as the web server, you also need to set remote_host to the correct IP address for Komodo.

Once the php.ini file is updated, verify that Xdebug is configured by running the following command:

    php -m

Lists of all PHP and Zend modules are displayed. Make sure Xdebug appears in both lists.

Note: Recent versions of PHP are set to buffer program output by default. While debugging, it is useful to disable output buffering so that results of print and echo statements can be seen immediately when stepping through code. To disable output buffering, comment out the output_buffering setting in php.ini with a ";" character, or set it to "off".

Starting and Stopping a PHP Remote Debugging Session

Once remote PHP debugging is configured, the PHP interpreter can contact Komodo and initiate a remote debugging session when a PHP script is executed on the web server.

To debug a PHP script using a web browser:

  1. Ensure you have configured PHP for your web server, have it properly working, and have configured PHP and Komodo as described in Configuring Remote PHP Debugging.
  2. On the Debug menu, click Listen for Remote Debugger.
  3. Open your web browser and access the script you want to debug. Append "?XDEBUG_SESSION_START=<idekey>" to the end of the URL as a GET argument. The IDE Key should match the Proxy Key value shown in Debug|Listener Status. For example:
      http://example.org/sample.php?XDEBUG_SESSION_START=jdoe
    

    Note: This is only required for the first request. After that, Xdebug tracks the debugging session with a cookie. For more information on how this works, see www.xdebug.org/docs-debugger.php#browser_session

  4. A PHP debugging session starts in Komodo. Use 'F11' to Step In, or 'F5' (Go) to run to the first breakpoint.

To debug a PHP script remotely from the command line:

  1. From the Debug menu, click Listen for Remote Debugger.
  2. Set the XDEBUG_CONFIG environment variable. Use the port specified in Edit|Preferences|Debugger or listed in Debug|Listener Status.

    On Windows:
      set XDEBUG_CONFIG=remote_port=9000 remote_enable=1
    On Linux (using the bash shell):
      export XDEBUG_CONFIG="remote_port=9000 remote_enable=1"

  3. Run the script using the PHP interpreter:
      php -f sample.php
  4. A PHP debugging session will start in Komodo. Click Step In ('F11') to start stepping through the script or Go ('F5') to run to the first breakpoint.

To debug a PHP script remotely using the DBGP Proxy:

  1. From the Debug menu, select Listen for Remote Debugger.
  2. Set the XDEBUG_CONFIG environment variable as above. Use the port specified in Edit|Preferences|Debugger or listed in Debug|Listener Status. Add an IDE Key value to the XDEBUG_CONFIG environment variable that matches the Proxy Key value shown in Debug|Listener Status.

    On Windows:
      set XDEBUG_CONFIG=remote_port=9000 remote_enable=1 idekey=<USERNAME>
    On Linux (using the bash shell):
      export XDEBUG_CONFIG="remote_port=9000 remote_enable=1 idekey=<USER>"
  3. Run the script using the PHP interpreter:
      php -f sample.php
  4. A PHP debugging session will start in Komodo. Click Step In ('F11') to start stepping through the script or Go ('F5') to run to the first breakpoint.

Output from the debug session appears in the Bottom Pane of the Komodo Workspace. Komodo does not support a console for remote debugging. The browser will not show the script output until debugging is complete.

To stop the debugger:

  • From the Debug menu, select Stop
    or
  • Press 'Shift+F5'

See Komodo Debugger Functions for full instructions on using Komodo's debugging functionality.

If you receive an error message while debugging a PHP script that is not caused by the errors in the script itself, check the PHP troubleshooting section of the Komodo FAQ.

 

Using xdebug_break()

The xdebug_break() function is used to hard-code a break in a PHP program. It can be used instead of a Komodo breakpoint. For example:

	<?php
	echo "<p>Breaks after this line.</p>";
	xdebug_break();
	echo "<p>Breaks before this line.<p>";
	?>

This function breaks the code during a debugging session but will not initiate a new session. Use xdebug_break() in conjunction with the methods described above for starting debugging sessions.