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 below for instructions on configuring Komodo to debug PHP programs. For general information about using the Komodo debugger, see Komodo Debugger Functions.

Komodo handles local and remote debugging of PHP programs differently than it treats 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 a web server environment being available, 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 depends on PHP calling 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 pane and entering a new value.

Configuring the PHP Debugger

To debug and run PHP programs with Komodo, follow these procedures to configure both PHP and Komodo. 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.

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. See below for more information.

Follow the steps below to configure the PHP debugging extension:

Step 1 - Ensure PHP is properly installed and 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 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.

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 get the version of your currently installed php executable. If it is older 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 Redhat installations from www.redhat.com/apps/support/updates.html. At the time of this writing, Redhat has not released an RPM for php 4.0.5. You can find 4.0.5 RPM's at http://rpmfind.net/.

Your compilation of PHP must support loading dynamic extensions. This is the default configuration for PHP under Linux, so chances are 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/.

Step 2 - Copy Komodo's Debugging Extensions to PHP

In order to use Komodo to 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.

In order to determine the destination directory for the shared library files, open the php.ini file and search for the value extension_dir. This path will be needed for the instructions below. 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, libxmlrpc.so.3, libxmlrpc_abyss.so.3, libxmlrpc_abyss_server.so.3, libxmlrpc_parse.so.3, and libxmlrpc_xmltok.so.3

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. All other files may be placed in the same directory as activedebug.so, or in any other directory path located on your LD_LIBRARY_PATH environment variable.

Note: you will need to add the path to the location of the libxmlrpc libraries to the LD_LIBRARY_PATH environment variable. Only activedebug.so MUST be in the php extensions directory, LD_LIBRARY_PATH will tell PHP where the other files are located. For example, if you use bash, add this line to your ~/.bashrc file:

export LD_LIBRARY_PATH=<php-extension-dir>:$LD_LIBRARY_PATH

If you are running an Apache web server and the mod_php4 module, the LD_LIBRARY_PATH variable must be set before you start the Apache server.

Step 3 - 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

    ;Remote Debugging Only

    activedebug.host=localhost ;where "localhost" is the domain name 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 file in Komodo, or some other editor such as emacs or vi.


  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

    ;Remote Debugging Only

    activedebug.host=localhost ;where "localhost" is the domain name 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"

Step 4 - (optional; local PHP debugging only) - Define the INI and interpreter for Komodo

To debug PHP programs locally, start Komodo and edit the Preferences. Make sure that a PHP executable is selected.

  1. From the Edit menu, select Preferences.
  2. In the Preferences dialog, click PHP.
  3. In the Use This Interpreter field, Komodo will provide a list of PHP interpreters found on your system (if they are located in directories included in the system's PATH variable). Select the desired interpreter from the list, or enter the path and name of the desired interpreter (if is is not located on the PATH), or click Browse to search for a PHP interpreter.
  4. In the PHP Configuration Path section, enter the directory where the php.ini file resides, or click Browse to search for the file. This setting is OPTIONAL. This is useful if you want to use a different .ini file for debugging.
  5. Click OK.
Top

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