# Debugging PHP Komodo IDE only

Tutorial

- PHP Tutorial

Komodo can be used to debug PHP programs locally or remotely. Remote PHP debugging encompasses 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.

Debugger commands can be accessed from the Debug menu, by shortcut keys, or from the Debug Toolbar. For a summary of debugger commands, see the Debugger Command List.

Komodo uses a PHP debugger extension called Xdebug that must be installed for Komodo to debug PHP scripts. Komodo automatically configures itself to use Xdebug for local PHP debugging, but the configuration must be done manually for remote PHP debugging. Pre-built binaries named "php_xdebug.dll" (for Windows) or "xdebug.so" (for Linux and Mac OS X) 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.

## Installing PHP

PHP debugging in Komodo will work with PHP 4.4 or later, with the exception of versions 5.0.0 through 5.0.2. If you are using PHP 5.0, you will need at least 5.0.3 or greater. Download PHP from http://www.php.net/downloads.php.

Refer to the PHP website for detailed information on installing 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.11 (or 5.0.0 through 5.0.2) 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.

- RPMs are available for Red Hat from www.redhat.com/apps/support/updates.html
- RPMs for for other distributions are available from http://rpmfind.net/.

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.

### Mac OS X

Although both the Jaguar and Tiger releases of OS X include a version of PHP, it is recommended that you obtain a more recent version. Either build from source code, or download a PHP module for OS X's Apache web server from www.entropy.ch/software/macosx/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

Komodo configures itself automatically for local PHP debugging by launching the default PHP interpreter (i.e. the first in your `PATH`) and attempting to load the Xdebug extension (`php_xdebug.dll` or `xdebug.so`). If this is successful, a new copy of `php.ini` is created automatically with debugging enabled which Komodo will use when debugging PHP scripts locally.

Note: If Xdebug is already installed and configured, make sure `xdebug.remote_autostart` is not enabled. This setting will interfere with local debugging in Komodo. If you need this option enabled for remote debugging, set the Path to alternate PHP configuration file under Preferences|Languages|PHP to point to a copy of `php.ini` without this option.

### Starting and Stopping a PHP Local Debugging Session

To step through the script, from Debug menu, select Step In.

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

To stop the debugger, from the Debug menu, select Stop.

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

## Remote PHP Debugging

Remote PHP debugging encompasses 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).

Find the appropriate extension for the version of PHP you are running and manually copy it into a directory on the server that the PHP interpreter and web server can access. The Xdebug files can be found in the php sub-directory of the Komodo installation. For example:

Windows

- File: `php_xdebug.dll`
- Location: `<komodo-install-directory>\lib\support\php\debugging\<PHP-version>` or the Komodo Remote Debugging page.

Linux

- File: `xdebug.so`
- Location: `<komodo-install-directory>/lib/support/php/debugging/<PHP-version>/` or the Komodo Remote Debugging page.

Mac OS X

- File: `xdebug.so`
- Location: `<komodo-install-directory>/Contents/SharedSupport/lib/support/php/debugging/<PHP-version>/` or the Komodo Remote Debugging page.

In the downloadable packages, the extensions are found in version-specific subdirectories of the unpacked archive.

The Xdebug extension does not have to be installed in the PHP `extension_dir` because its location is specified explicitly in php.ini (see below).

#### Step 2 - Edit the Web Server's PHP Configuration

Open the php.ini configuration file on the server. There may be multiple copies of this file, so check the value of "Loaded Configuration File" in the `phpinfo()` output to see which one is being used by the web server (e.g. create a phpinfo.php file containing the line '`<?php phpinfo(); ?>`' in a web server directory, then open the corresponding URL in a browser).

Note: Xdebug is incompatible with the Zend Optimizer and Zend Studio Debugger extensions. These extensions should be commented out in php.ini when configuring PHP for remote debugging with Komodo.

In the "`Dynamic Extension`" section, add the lines specified below. Edit the values to reflect your particular environment (see Xdebug settings explained below).

- Windows

  The php.ini configuration file is generally in your operating system directory (e.g. C:\WINDOWS or C:\WINNT) or in the same directory as `php.exe` (e.g. C:\PHP). Check `phpinfo()` as described above if you cannot find the file or have multiple copies.

      ; xdebug config for Windows
      ; - zend_extension_ts is for PHP <= 5.2
      ; - zend_extension is for PHP >= 5.3
      ; or you can specify both if your not sure.
      zend_extension_ts=c:\path\to\php_xdebug.dll
      zend_extension=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>

- Linux and Mac OS X

      ; xdebug config for Linux and Mac OS X
      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>

Xdebug settings explained:

`zend_extension_ts` or `zend_extension`
  Should be set to the full path to the xdebug library on your system. Use `zend_extension_ts` ("thread safe") on Windows PHP <= 5.2, else `zend_extension` for Windows PHP >= 5.3 and for all other platforms (i.e. Mac, Linux).
`xdebug.remote_enable`
  Enables remote debugging.
`xdebug.remote_handler`
  Should be set to `dbgp` for use with Komodo.
`xdebug.remote_mode`
  Set to `req` to have the script connect to Komodo when it starts. Set to `jit` to connect only on an error condition (see PHP Just-in-Time Debugging / Break on Exception).
`xdebug.remote_host`
  Set to the hostname or IP address of the computer running Komodo or the DBGP Proxy. Use 'localhost' or '127.0.0.1' if Komodo and the web server are running on the same system.
`xdebug.remote_port`
  Set to the same value as the debugging listener port configured in the Debugger Connection preferences (or the system assigned Host Port displayed under Debug|Listener Status)
`xdebug.idekey` (optional)
  If you are using the DBGP Proxy, set this to the Proxy Key configured in the Debugger Connection preferences.

Restart the web server to load the new configuration.

#### Step 3 - Verify the Web Server's PHP Configuration

Once the php.ini file is updated, verify that Xdebug is configured by checking the output of `phpinfo()` (described in Step 2). There should be an Xdebug section in the alpabetical list of modules which shows all of the relevant settings.

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.

Note: For Komodo to open an editable copy of the file, a Mapped URI must be created to link the file on the remote filesystem with the URI Komodo receives from the remote debugger.

#### To initiate remote debugging from a web browser:

1. Ensure PHP is installed and configured properly for your web server.
2. Ensure Komodo and PHP are configured for remote debugging (as described in "Configuring Remote PHP Debugging").
3. Click Debug | Listen for Debugger Connections.
4. In your browser, enter the URL of the script you want to debug. Append `?XDEBUG_SESSION_START=1` to the end of the URL (an HTTP GET with a true boolean value). For example:

       http://example.org/sample.php?XDEBUG_SESSION_START=1

   If you are using the DBGP Proxy, the value for the GET method should match the Proxy Key value shown in Debug|Listener Status. For example:

       http://example.org/sample.php?XDEBUG_SESSION_START=jdoe

   It is also possible to call `XDEBUG_SESSION_START` by adding it in an `input` element of an HTML form. For example:

       <input type="hidden" name="XDEBUG_SESSION_START" value="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

5. A PHP debugging session starts in Komodo. On the Debug menu, click Step In or Go/Continue to run to the first breakpoint.

#### To initiate remote debugging from the command line:

1. On the Debug menu, click Listen for Debugger Connections.
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/Mac OS X:

       export XDEBUG_CONFIG="remote_port=9000 remote_enable=1"

4. Run the script using the PHP interpreter:

       php -f sample.php

5. A PHP debugging session will start in Komodo. Click Step In to start stepping through the script or Go/Continue to run to the first breakpoint.

#### To initiate remote debugging using the DBGP Proxy:

1. From the Debug menu, select Listen for Debugger Connections.
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/Mac OS X:

       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. On the Debug menu, Click Step In to start stepping through the script or Go/Continue 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:

On the Debug menu, select Stop or pass the `XDEBUG_SESSION_STOP=1` variable by appending it to the URL or adding it to a form (as with `XDEBUG_SESSION_START=1` above).

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.

### Xdebug Logging

To log xdebug sessions on the server, add the following line to the xdebug config section of the php.ini configuration file:

    xdebug.remote_log=/tmp/xdebug.log

...or add `remote_log` to the `XDEBUG_CONFIG` environment variable. For example:

    export XDEBUG_CONFIG="remote_port=9000 remote_enable=1 remote_log=/tmp/xdebug.org"

You can replace "`/tmp/xdebug.org`" with any writable directory and the filename of your choice.

### PHP Just-in-Time Debugging / Break on Exception

PHP remote debugging can be configured to break when an exception is thrown. Sometimes called just-in-time debugging, this method allows you to test your application and stop to examine code when there is a problem.

To turn this on, change the `xdebug.remote_mode` setting in php.ini from '`req`' to '`jit`' or override the setting in your code:

    <?php
    ini_set('xdebug.remote_mode', 'jit');
    ...
    ?>

Whenever an exception is thrown, a debugging session is initiated with a break at the line that caused the problem.

This may generate a lot of breaks if PHP is configured with verbose error handling (e.g. `error_reporting = E_ALL`). In PHP 5, you can define your own Exception class which enables JIT debugging only for specific exceptions:

    <?php
    class KoException extends Exception
    {
      function __construct($message, $code = 0) {
        ini_set('xdebug.remote_mode', 'jit');
        parent::__construct($message, $code);
      }
    }

    throw new KoException('this is my exception!', 42);
    ?>

## Common PHP Debugging Problems

### Debugging PHP on OS X

The version of PHP supplied with Mac OS X is not complied with loadable extension support, so it is not compatible with Komodo's debugger (Xdebug). For PHP debugging on OS X, either build PHP from source with loadable extension support or use binaries from http://www.entropy.ch/software/macosx/php/. The 4.3.11 or 5.0.4 for Apache 1 packages have been found to work well with Komodo PHP debugging.

### Debugging PHP on 64-bit Linux

The version of `xdebug.so` for Linux provided by Komodo is not compatible with 64-bit versions of PHP. To configure PHP debugging on 64-bit Linux systems, compile Xdebug from source, replace Komodo-<version>/lib/support/php/debugging/<PHP version>/xdebug.so with the new 64-bit version, and re-check the PHP Configuration Debugger status in Komodo's PHP preferences..

### Zend Optimizer and Zend Studio Debugger

Xdebug is incompatible with the Zend Optimizer and Zend Studio Debugger extensions. If these extensions are enabled in php.ini, they will not be imported into the copy created by Komodo for debugging. When configuring Remote PHP Debugging, these extensions should be manually commented out in php.ini.