Komodo User Guide

Debugging PHP

New to PHP?
Check out the PHP Tutorial

You can use Komodo to debug PHP programs locally or remotely, including debugging in CGI or other Web Server API environments. See instructions below on how to configure Komodo to debug PHP using the PHP Configuration Wizard. programs. To manually configure PHP for debugging, see the Komodo FAQ. For general information about using the Komodo debugger, see Komodo Debugger Functions.

Komodo handles local and remote debugging of PHP programs differently than it handles Perl and Python programs. Komodo provides a debugger extension called ActiveDebug.dll. You must install this extension file for Komodo to debug PHP scripts.

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 environment, you will need to use Remote Debugging. Under local debugging, certain environment variables are not available, such as those provided by the CGI environment. You do not need to have a web server installed to use Komodo's local debugging features. Otherwise, local and remote debugging work the same, and are configured nearly the same. Once you have configured PHP to use the debugger extension, you can debug your scripts simply by opening a PHP file, and going to the Debug menu, then clicking on "Step Into".

Remote PHP Debugging

Remote debugging requires PHP to call Komodo. After you have followed instructions to configure PHP for remote debugging, you can start remote debugging. Go to the Debug menu, and click on "Listen for Remote Debugger...". When PHP is executed, it will contact Komodo and initiate a remote debugging session. This can be configured to happen with a web server, so that you can initiate a PHP program using a web browser, then debug the script with Komodo.

Viewing Variables

The Variables tab in the Output Pane displays the global and the local variables. Global variables include all variables available in the global scope.

Local variables include all the variables available in the scope your program is in. That is, if you call a function, you go into a new scope, so the local variables will change. You can interact with these variables - you can change the variable value by double-clicking the variable in the Locals tab and entering a new value.

Configuring the PHP Debugger

Before you can debug PHP scripts in Komodo, PHP must be configured to use the ActiveDebugger extension (ActiveDebug.dll).

Komodo requires PHP version 4.0.5 or greater. You can download PHP from http://www.php.net/downloads.php. If you want to debug PHP scripts under a web server environment, be sure PHP is operating correctly with your web server before configuring the debugger extension. Consult the PHP documentation for notes on configuring PHP with your web server.

Note: If you are installing PHP for the first time, the PHP installation program may not work correctly on Windows Millennium; please refer to the PHP site for installation instructions.

Using the PHP Configuration Wizard

The PHP Configuration Wizard simplifies the process of selecting a PHP executable to use for debugging, copying the PHP.ini file to a new directory and modifying it for debugging, and copying the ActiveDebugger extension to the directory defined in the .ini file.

To start the wizard:

  1. Select Edit|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 four main steps necessary to configure the debugging extension.

    1. Choose Installation

    The first step assumes that you have PHP installed. If you do not have PHP, you can download it from www.php.net. If you have more than one version of PHP installed, you can choose which version you want to configure. Browse to the directory containing the php.exe file or enter the directory path in the Set up this installation field. Click the Next button.

    2. Choose PHP INI Path

    Next, choose the php.ini file to be copied and its destination directory. Note that if you modify the original file at at later time, the changes will not be available in the version you copied to the debugger. You can either modify the the file in the debugger, or rerun this wizard to copy the changes. Click Next.

    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 has been set, click Next.

    4. Ready to Install

    The final window in the wizard displays the installation options you have selected. Confirm that the selections are correct and click Next. If you want to change any of the selections, click Back.

Note: If you want to manually configure PHP for debugging, see the instructions in the Komodo FAQ. For an introduction on using Komodo to debug PHP, see Using the PHP Remote Debugger.

Single Person Remote PHP Debugging In single person remote debugging, you can configure PHP to always look for a specific Komodo instance 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. See below for further information.

Multiple Person Remote PHP Debugging In multiple person remote debugging, you can configure PHP to accept different Komodo instances on different machines. Use this method when you have several people and several machines all able to debug PHP scripts on a single web server. Note that only one person will be able to debug any given script at a time.This configuration requires changes to the PHP script on a per-user basis.

Near the top of your PHP script, add the following command:

asdbg_break("localhost", 9000)

where localhost is the name of the machine that Komodo runs on, and 9000 is the port that Komodo listens for remote debuggers. To specify a debugging listener port, select Edit|Preferences|Debugger.

When the web server executes the PHP script and comes to this line, PHP then contacts Komodo on the machine and port specified. From then on, you can use Komodo to debug your script remotely.

You can add this line anywhere in your PHP script, but Komodo begins the debug process only when this line in your script is reached. The Komodo debugger begins on the line following asdbg_break().

If you add the asdbg_break() command without parameters, Komodo uses the default PHP parameters defined in the php.ini file.

Configuring PHP Debugging on an Apache Server

Apache configuration directives provide additional flexibility in configuring PHP for debugging. If you have configured your Apache installation to use Virtual Hosting (see httpd.apache.org/docs/vhosts/), you can add additional directives to your VirtualHost sections to differentiate how Komodo's PHP debugger extension operates for those hosts. Use the "php_admin_value" to set specific debugger settings for that virtual host. Here is an example:


NameVirtualHost *
<VirtualHost *>
php_admin_value activedebug.enabled 0
DocumentRoot "/Apache/htdocs/"
ErrorLog logs/www.error.log
Servername www.yourdomain.com
</VirtualHost>

<VirtualHost *>
php_admin_value activedebug.enabled 1
DocumentRoot "/Apache/htdocs/"
ErrorLog logs/debug.error.log
Servername debug.yourdomain.com
</VirtualHost>

This will enable debugging under debug.yourdomain.com, but not under www.yourdomain.com. You can additionally configure the virtual host to use a specific machine for remote debugging:


<VirtualHost *>
php_admin_value activedebug.enabled 3
php_admin_value activedebug.host komodo.yourdomain.com
DocumentRoot "/Apache/htdocs/"
ErrorLog logs/debug.error.log
Servername debug.yourdomain.com
</VirtualHost>

For more information on configuring Virtual Hosting under Apache, see the Apache documentation at httpd.apache.org/docs/.

Top

Using the PHP Remote Debugger

To Komodo, remote PHP debugging is similar to running PHP under a web server (such as Apache or IIS) as a CGI or server plug-in. You have CGI variables available and all other variables you would expect to have available when running PHP under a web server. Note that debugging is slower in a remote debugging configuration.

For an introduction to how Komodo handles PHP debugging, see PHP Debugger Overview.

To debug a PHP script:

  1. Ensure you have configured PHP for your web server, have it properly working, and have configured PHP and Komodo, as described in Configuring the PHP Debugger.
  2. From the Debug menu, select Listen for Remote Debugger.
    A Listening for Connection dialog opens and indicates the port number for the process.
  3. Open your web browser and access the script you want to debug.
  4. In Komodo, open the PHP script you want to debug.
  5. Begin debugging. Use F5 to step in, or Go to run to the first breakpoint.

    From then on, you can use the full Komodo debugging functionality, including setting breakpoints, stepping, viewing the call stack, and watching variables. The output from the debug process appears in the Output Pane in the Komodo Workspace. Komodo does not support a console for remote debugging.

    Your browser does not show the changes until you stop debugging.

To stop the debugger:

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

Configuring PHP for CGI Debugging

Komodo's Remote Debugging functions are specifically designed for CGI environments. Follow the instructions in Configuring the PHP Debugger for configuring Komodo to debug CGI applications written in PHP.

Top

PHP Debugger Troubleshooting

If you have attempted to debug a PHP script and receive an error message, there are a few things you can verify prior to contacting ActiveState's technical support.

Confirm PHP Configuration

  1. ActiveDebugger: in the command or shell window, enter php -m. "Active Debugger" should be listed as both a regular module and a zend extension. If this is not the case, your configuration is incorrect. See "Common PHP Configuration Problems" below.
  2. Syntax Checking: in Komodo, select Edit|Preferences. Click on Smart Editing, and ensure that "Enable background syntax checking" is checked. Open a php file and enter something that is syntactically incorrect, such as:
    <?
    asdf
    echo test;
    ?>
    
    Komodo should display a red squiggly line under echo test;. If it does not, it indicates that Komodo is not able to communicate with the PHP interpreter.
  3. Debug: if steps one and two were successful, ensure that the debugger is functioning by opening a PHP program and debugging it. Ensure that the correct Preferences are configured for PHP.

If any of the steps above were unsuccessful, proceed to the next section.

Common PHP Configuration Problems

  • Multiple PHP executables on one machine: in Komodo's Preferences, explicitly specify the PHP interpreter configured in your php.ini file. If you are running Komodo version 1.2 or higher, you can also explicitly select the location of the php.ini file.
  • Verify the PHP version: Komodo 1.2 and higher includes support for PHP versions 4.05, 4.0.6, 4.1.x and 4.2.x.
  • Verify DLL locations: the file "xerces-c_1_4.dll" (required by PHP 4.0.x only) must be located in the same directory as php.exe. By default, the location is:

    • Windows: c:\php
    • Linux: /usr/bin

    The file "activedebug.dll" must be located in the directory specified in the "extension_dir" variable in the php.ini file, for example:

    • Windows: c:\php\extensions
    • Linux: /usr/local/lib/php/extensions

  • Verify php.ini file specifications Ensure that your php.ini file specifies the correct location for the extension directory. By default, the php.ini file is located as follows:

    • Windows: c:\winnt
    • Linux: /usr/local/lib/php

    Ensure that the variable extension_dir in the php.ini specifies the correct directory for php extensions, as shown below:

    • Windows: extension_dir = c:\php\extensions
    • Linux: extension_dir = /usr/local/lib/php/extensions

    Ensure that the following variables are specified in the php.ini file:

    • extension=activedebug.dll
    • activedebug.enabled=1

Windows-Specific Configuration Issues

  • Confirm "SYSTEM PATH": if you are using and PHP 4.0.x and ISAPI.dll, or the Apache.dll if PHP is run as a system service, ensure that the directory containing the file "xerces-c_1_4.dll" is specified in your SYSTEM PATH, as opposed to your USER PATH. ("xerces-c_1_4.dll" should be located in the directory C:\PHP.) For example, on Windows 2000, right-click the "My Computer" icon on your desktop and select "Properties". On the "Advanced" tab, click Environment Variables. Ensure that the directory C:\PHP is included in the "PATH" variable in the "System variables" section. If necessary, re-start your web server.
  • Windows 2000 upgrade: if you upgraded to Windows 2000 from an earlier version of Windows, check the value of the "COMSPEC" variable in the "System variables" (as described above). It should point to C:\WINNT\system32\cmd.exe, and not command.com. If you must change the variable, reboot your system.
  • There are known issues regarding the installation of PHP on Windows Millennium systems; please refer to the PHP site for installation information.

Linux-Specific Configuration Issues

  • LD_LIBRARY_PATH: ensure that the variable LD_LIBRARY_PATH includes the directory where the xmlrpc*.so files were installed (see Configuring the PHP Debugger). Alternatively, add the path to your /etc/ld.so.conf file.
  • activedebug.so: the file activedebug.so must be located in the directory defined in your php.ini file for the variable extension_dir.

Version Error Messages

If you receive a dialog with the following text:

Warning
Active Debugger: Unable to initialize module
Module compiled with debug=0, thread-safety=1 module API=20001222
PHP compiled with debug=0, thread-safety=1 module API=20001222
These options need to match

you need to download an updated version of the activedebug.dll (Windows) or activedebug.so (Linux) from the Komodo Remote Debugging page.

Top