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 for PHP local debugging or remote debugging.

If you are not familiar with the Komodo debugger, it is recommended that you first consult Komodo Debugger Functions for an introduction. If you receive an error message while debugging a PHP script, see the PHP troubleshooting section of the Komodo FAQ.

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. This can be done manually or with the PHP Configuration Wizard. Note that the debugging extension for PHP 5 was not available at the time of the Komodo 2.5 release. When the extension is available, it will be published at http://aspn.activestate.com/ASPN/Downloads/Komodo/RemoteDebugging.

Viewing Variables

The Debug 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.

Top

Installing PHP

Before configuring PHP for local debugging or remote debugging, ensure that it is properly installed and is operational.

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 details 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.

Windows Users

If you are installing PHP on Windows and are unfamiliar with the installation of PHP, we recommend that you download the distribution that is packaged as a Windows Installer. As of version 4.0.5, the package with the Windows Installer is not a full distribution and is significantly smaller than the full distribution, but it is enough to get started with debugging PHP in Komodo.

You can find detailed documentation on installing PHP manually at http://www.php.net/manual/en/install-windows.php. Ensure that the PHP directory is included in your system's PATH statement.

Linux Users

Komodo ships with a PHP extension to support PHP debugging. Your Linux system may already have PHP installed. Login and type 'php -v' to determine the version of your currently installed php executable. If it is earlier than version 4.0.5 you will need to upgrade. You can find detailed documentation for installing and configuring PHP at http://www.php.net/manual/en/. RPMs are also available for Red Hat installations from www.redhat.com/apps/support/updates.html. You can find a 4.0.5 RPM at http://rpmfind.net/.

Your compilation of PHP must support loading dynamic extensions. This is the default configuration for PHP under Linux, so it is likely that your PHP installation already supports this.

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

--with-config-file-path=/path/to/phpini/ (note: this is only a path, do not include the filename)

where /path/to/phpini/ is the directory where the php.ini configuration file is stored. For further information about PHP installation, refer to http://www.php.net/manual/en/.

Top

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 configure remote debugging. Remote debugging also makes it possible to test scripts in their true environment.

Under local debugging, certain environment variables are not available, such as those provided by the CGI environment. (However, you have the option of simulating a CGI Environment by selecting this feature in the Debugging Options dialog box.) You do not need to have a Web server installed to use Komodo's local debugging features. Once you have configured PHP to use the debugger extension, you can debug your scripts by simply opening a PHP file and using Komodo Debugger Functions.

If you have attempted to debug a PHP script and received an error message, see the PHP troubleshooting section of the Komodo FAQ.

Configuring PHP Local Debugging

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.

The 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 ActiveDebugger extension to the directory defined in the .ini file. Note that the PHP Configuration Wizard should only be used to configure local debugging. If you want to debug PHP remotely, see Configuring PHP Remote Debugging.

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 already installed PHP. 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 later time, the changes will not be available in the version you copied to the debugger. You can either modify 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 prefer to manually configure PHP for local debugging, see the instructions in the Komodo FAQ.

Top

Remote PHP Debugging

Remote PHP debugging with Komodo is similar to running PHP under a Web server (such as Apache or IIS) as a CGI or server plug-in. CGI variables are available, as are all other variables that are available when running PHP under a Web server. Note, however, that debugging may be slower in a remote debugging configuration.

After you have followed instructions to configure PHP for remote debugging, you can begin debugging. When PHP is executed, it will contact Komodo and initiate a remote debugging session.

To debug a PHP script remotely:

  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

If you have attempted to debug a PHP script and received an error message, see the PHP troubleshooting section of the Komodo FAQ.

Configuring PHP Remote Debugging

If you configure remote debugging under a Web server, you can initiate a PHP program using a Web browser, then debug the script with Komodo. Remote debugging can be set up for a localhost Web server or a Web server installed on another machine. The php.ini file is configured differently, depending on the debugging scenario (see Step 2 - Edit the php.ini configuration file for more details).

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.

Remote debugging of PHP in Komodo has slightly different requirements, depending on how many people will be debugging scripts on the same Web server.

Single Person Remote PHP Debugging: In single person remote debugging, you can configure PHP 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

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 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(<remote_machine>, 9000)

where remote_machine is the hostname or IP address of the machine that Komodo runs on, and 9000 is the port that Komodo uses to listen for remote debuggers. To specify a debugging listener port, select Edit|Preferences|Debugger.

When the Web server executes the PHP script and reaches this line, PHP 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 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.

Note: If you are remote debugging with an Apache Web server, you can configure Virtual Hosting to run multiple Web servers on the same machine.

Although the PHP Configuration Wizard provides a simple way to configure local PHP debugging, you must configure remote debugging manually. The following procedure assumes that you have already installed PHP.

Step 1 - Copy Komodo's Debugging Extensions to PHP

In order to use Komodo to remotely debug PHP programs, you must manually copy some shared library files distributed with Komodo into the php extensions directory. The destination location depends on the value assigned to the extension_dir variable in the php.ini file.

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 path is /usr/local/lib, but that may have changed when php was installed on your system. It may also be located in the same directory as your php.exe executable. These files are also available for download from the Komodo Remote Debugging page.

To determine the destination directory for the shared library files, open the php.ini file and search for the value extension_dir. You will need this path for the instructions that follow. 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 Users

Files needed: ActiveDebug.dll

Source location: <komodo-install-directory>\php\ (by default, C:\Program Files\Komodo-x.x\php\debugging\php_version) (where x.x is the Komodo version)

Destination: ActiveDebug.dll should be placed in the extension_dir as defined in the php.ini file.

Linux Users

Files needed: activedebug.so

Source location: <komodo-install-directory>/php_version/ (by default, ~/Komodo-x.x/php/, where x.x is the Komodo version)

Destination: activedebug.so should be placed in the extension_dir as defined in the php.ini file.

Step 2 - Edit the php.ini configuration file

Windows Users:

  1. Open the php.ini configuration file in Komodo.


  2. Search for "Dynamic Extension", and add the following lines to the section (the lines below have been formatted so that they can be cut from this document and pasted into the php.ini file):

    extension=activedebug.dll ;[ActiveDebugger]
    activedebug.enabled=1 ;set this value to "0" if you will only be doing local debugging, to "1" for multi-person remote debugging, or to "3" for single-person remote debugging
    activedebug.host=localhost ;where "localhost" is the domain name or IP address of the machine running Komodo
    activedebug.port=9001 ; the port that PHP listens on, typically 9001
    activedebug.remoteport=9000 ; the port specified in the Debugger Preferences, by default "9000"

Linux Users:

  1. Open the php.ini configuration file in Komodo, or in another editor.


  2. Search for "Dynamic Extension", and add the following lines to the section (the lines below have been formatted so that they can be cut from this document and pasted into the php.ini file):

    extension=activedebug.so ;[ActiveDebugger]
    activedebug.enabled=1 ;set this value to "0" if you will only be doing local debugging, to "1" for multi-person remote debugging, or "3" for single-person remote debugging
    activedebug.host=localhost ;where "localhost" is the domain name or IP address of the machine running Komodo
    activedebug.port=9001 ;the port that PHP listens on, typically 9001
    activedebug.remoteport=9000 ; the port specified in the Debugger Preferences, by default "9000"
Top