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.
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:
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/.
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.
Windows Users:
- Open the php.ini configuration file in Komodo.
- 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
activedebug.host=localhost
activedebug.port=9001
activedebug.remoteport=9000
Linux Users:
- Open the php.ini configuration file file in Komodo, or some other editor such as emacs or vi.
- 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
activedebug.host=localhost
activedebug.port=9001
activedebug.remoteport=9000
To debug PHP programs locally, start Komodo and edit the Preferences. Make
sure that a PHP executable is selected.
- From the Edit menu, select Preferences.
- In the Preferences dialog, click PHP.
- 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.
- 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.
- Click OK.
Top
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
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:
- 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.
- From the Debug menu, select Listen for Remote Debugger.
A Listening for Connection dialog opens and indicates the port number
for the process.
- Open your web browser and access the script you want to debug.
- In Komodo, open the PHP script you want to debug.
- 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
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
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
- 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.
- 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.
- 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
|