|
Komodo can be used to debug PHP programs locally or remotely. Remote PHP debugging encompases
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. This can be done manually or with the PHP
Configuration Wizard. 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.
PHP debugging in Komodo will work with PHP 4.3.10 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.1 (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.
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/.
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.
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.
If the automatic configuration of PHP debugging is not
successful, try configuring PHP debugging manually using the
PHP Configuration Wizard.
To start the wizard:
- On the Edit menu, click
Preferences.
- Under Languages, select
PHP.
- Click the Debugger Configuration Wizard
button to display the wizard's introductory window.
- Click Next to begin configuring PHP for
debugging.
The wizard will guide you through the steps necessary to
configure the debugging extension.
-
Choose Installation:
The first step assumes that you have already installed PHP. If you have more
than one version of PHP installed, choose the version to
configure. Browse to the directory containing the PHP
executable or enter the directory path in the Set up
this installation field, and then click
Next.
-
Choose PHP INI Path:
Next, choose the php.ini file to be copied and
its destination directory. Subsequent changes to the original
file will not be available in the new copy. Modify the new
file directly, or rerun the wizard to copy the changes. Click
Next.
- 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 location is
/usr/local/lib. It may also be located in the
same directory as your PHP executable.
-
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 is set, click
Next.
-
Ready to Install:
The final window in the wizard displays the installation
options. Confirm that the selections are correct and click
Next. To change any of the selections, click
Back.
The PHP Configuration Wizard is only used to configure local
debugging. To debug PHP remotely on a web server, see Configuring Remote PHP
Debugging.
If the wizard does not successfully enable local PHP
debugging, refer to Configuring Remote PHP Debugging for
more information on manual configuration and Common PHP Debugging
Problems for information on common problems.
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 encompases 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.
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.
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 required:
php_xdebug.dll
- Source location:
<komodo-install-directory>\lib\support\php\debugging\<PHP-version>
or the
Komodo Remote Debugging page.
- Destination: the
extension_dir as defined in the php.ini
file.
Linux
- File required:
xdebug.so
- Source location:
<komodo-install-directory>/lib/support/php/debugging/<PHP-version>/
or the
Komodo Remote Debugging page.
- Destination: the
extension_dir as defined in the php.ini
file.
Mac OS X
- File required:
xdebug.so
- Source location:
<komodo-install-directory>/Contents/SharedSupport/lib/support/php/debugging/<PHP-version>/
or the
Komodo Remote Debugging page.
- Destination: the
extension_dir as defined in the php.ini
file.
In the downloadable packages, the extensions are found in
version-specific subdirectories of the unpacked archive.
We recommend installing Xdebug in the existing PHP extensions
directory on the web server (specified by the
extension_dir variable in the php.ini
file). 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 and Mac OS
X.
Open the php.ini configuration file on the web
server. In the "Dynamic Extension" section, add the
lines specified below.
|
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.
|
-
Windows
; xdebug config for Windows
zend_extension_ts=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>
The php.ini configuration file should be in your
operating system directory (e.g. C:\WINDOWS or C:\WINNT), or
in the same directory as php.exe (e.g. C:\PHP).
If you used the PHP Windows installer, this file should be in
the correct location.
-
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>
Set remote_port to the same value as the
debugging listener port configured in
Edit|Preferences|Debugger (or the system
assigned Host Port displayed under
Debug|Listener Status). If Komodo is not running
on the same machine as the web server, you also need to set
remote_host to the correct IP address for
Komodo.
Restart the web server to load the new configuration.
Once the php.ini file is updated, verify that Xdebug
is configured by running the following command:
php -m
If your command-line PHP interpreter uses a different
php.ini file (this is often the case) or if you're not
sure which file it uses, create a phpinfo.php file
containting the line '<?php phpinfo(); ?>' in
a web server directory to display the configuration in a web
browser.
Make sure Xdebug appears in the Zend module lists, but not in the PHP
module list.
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".
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.
To initiate remote debugging from a web browser:
- Ensure PHP is installed and configured properly for your web server.
- Ensure Komodo and PHP are configured for remote debugging (as described
in "Configuring Remote PHP
Debugging").
- Click Debug | Listen for Debugger Connections.
- 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
- 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:
- On the Debug menu, click Listen
for Debugger Connections.
- 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"
- Run the script using the PHP interpreter:
php -f sample.php
- 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:
- From the Debug menu, select Listen
for Debugger Connections.
- 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>"
- Run the script using the PHP interpreter:
php -f sample.php
- 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.
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.
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.
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.
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 run
the PHP Configuration Wizard.
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.
|
