PEAR Manual
PrevNext

I. Advanced PHP debugger

Introduction

About apd

APD is the Advanced PHP Debugger. It was written to provide strace/truss capability for profiling and debugging php code, as well as providing the ability to print out a full stack backtrace. APD does supports interactive and non interactive debugging, by default it writes data to trace files. APD provides event based logging, so that varying levels of information (including function calls, arguments passed, timings, etc.) can be turned on or off for individual scripts.

APD is a Zend Extension, modifying the way the internals of PHP handle function calls, and thus may or may not be compatible with other Zend Extensions (for example Zend Optimizer).

Installation

Make sure you have installed the CGI version of PHP and it is available in your current path along with the phpize script.

Change into the source directory (either created from the downloaded TAR archive or from checking out CVS) and run the following commands: 

./configure
make install

This automatically should install the 'php_apd' zend module into your php extensions directory directory. It isn't mandatory to have it there, in fact you can install it anywhere you care.

In your INI file, add the following lines: 

zend_extension = /absolute/path/to/php_apd.so
apd.dumpdir = /absolute/path/to/trace/directory

php.ini zend_extension setting

Depending on your PHP build, the zend_extension directive can be one of the following: 

zend_extension              (non ZTS, non debug build)
zend_extension_ts           (    ZTS, non debug build)
zend_extension_debug        (non ZTS,     debug build)
zend_extension_debug_ts     (    ZTS,     debug build)

zend_extension_debug = /absolute/path/to/php_apd.so

php.ini apd.dumpdir setting

This can either be an absolute path or a relative path. Relative means always relative to your where from you run your executeable. 

*** NOTE ******************************************************************
    *
    * If you're running the CGI version of PHP, you will need to add the '-e'
    * flag to enable extended information for apd to work properly:
    *
    *     php -e -f script.php
    *
    ***************************************************************************

Building on Win32

To build APD under windows you need a working PHP compilation environment as described on http://php.net/ (basically, it requires you to have MSVC, win32build.zip and bison/flex and some know how about how to get it to work). Also make sure that adp.dsp has DOS line endings! If it has unix line endings, MSVC will complain about it.

You can use normal Windows path values for your php.ini settings: 

zend_extension_debug_ts = c:\phpdev\php_apd.dll
apd.dumpdir = c:\phpdev\traces

How to use PHP-APD in your scripts

In your PHP script, add the following line: 

apd_set_session_trace(9);

Now run your script.

The dump output will be writting to: 

<apd.dumpdir>/apd_dump_<pid>

The output itself will look something like: 

16:37:51(george@wasabi)[~/src/apd]> cat /tmp/apd_dump_31994 

APD - Advanced PHP Debugger Trace File
---------------------------------------------------------------------------
Process Pid (31994)
Trace Begun at Fri Aug 10 16:37:45 2001
---------------------------------------------------------------------------
(  0.000000): apd_set_session_trace called at somewhere
(  0.001482): apd_set_session_trace() returned.  Elapsed (997475865.364909)
(  0.001563): getcwd() /opt/apache/htdocs/a.php:4
(  0.001628): getcwd() returned.  Elapsed (0.000065)
(  0.001819): require() /opt/apache/htdocs/a.php:6
              ++ argv[0] $(??) = /tmp/a.php
(  0.002231):   getcwd() /tmp/a.php:3
(  0.002290):   getcwd() returned.  Elapsed (0.000059)
(  0.002375):   include_once() /tmp/a.php:4
                ++ argv[0] $(??) = /tmp/aa.php
(  0.003276):   include_once() returned.  Elapsed (0.000901)
(  0.003334): require() returned.  Elapsed (0.001515)
(  0.003381): require_once() /opt/apache/htdocs/a.php:7
              ++ argv[0] $(??) = /tmp/aa.php
(  0.003515): require_once() returned.  Elapsed (0.000134)
(  0.003564): include() /opt/apache/htdocs/a.php:8
              ++ argv[0] $(??) = /tmp/b.php
(  0.003792): include() returned.  Elapsed (0.000228)
(  0.018341): RSHUTDOWN called - end of trace
---------------------------------------------------------------------------
Process Pid (31994)
Trace Ended at Fri Aug 10 16:37:45 2001
---------------------------------------------------------------------------

Contact Information

If you have comments, bugfixes, enhancements or want to help developping this beast, you can send an mail to apd@mail.communityconnect.com. Any help is very welcome.

Table of Contents
apd_callstack -- Returns the current call stack as an array.
apd_clunk -- Throw a warning and a callstack.
apd_croak -- Throw an error, a callstack and then exit.
apd_dump_regular_resources -- Return all current regular resources as an array.
apd_dump_persistent_resources -- Return all persistent resources as an array.
apd_dump_function_table -- Outputs the current function table.
override_function -- Overrides built-in functions.
rename_function -- Renames orig_name to new_name in the global function_table.
apd_set_session_trace -- Starts the session debugging.
apd_set_socket_session_trace -- Starts the remote session debugging.
apd_set_session -- Changes or sets the current debugging level.
apd_breakpoint -- Stops the interpreter and waits on a CR from the socket
apd_continue -- Restarts the interpreter
apd_echo -- echo to the debugging socket
apd_get_active_symbols -- get an array of the current variables names in the local scope
PrevHomeNext
PECL PackagesUpapd_callstack