php4-apd - PHP code execution profiler and debugger

This manual page documents briefly the php4-apd package and pprofp command. This manual page was written for the Debian distribution because the original program does not have a manual page.

php4-apd (the Advanced PHP Debugger) is a full-featured PHP profiler/debugger that is loaded as a zend_extension. It aims to be an analog of C's gprof or Perl's Devel::DProf, and provides PHP developers with a number of additional functions which can be used to obtain internal code execution details such as timing information, function call tree and stack backtrace. This is particularly useful for performance profiling purposes.

Once installed, APD provides a number of additional functions which you can place in your PHP code for either profiling or debugging. The debugging functions are:

array apd_callstack()

Returns the current call stack as an array (very cool).

apd_cluck([string warning[,string line delimiter])

Behaves like perl's Carp::cluck. Throw a warning and a callstack. The default line delimiter is "<BR />\n". Deprecated for users of PHP4.3+: use the internal debug_backtrace() and debug_print_backtrace() instead.

apd_croak([string error[, string line delimiter]])

Behaves like perl's Carp::croak. Throw an error, a callstack and then exit. The default line delimiter is "<BR />n". Deprecated for users of PHP4.3+: use the internal debug_backtrace() and debug_print_backtrace() instead.

array apd_dump_regular_resources()

Return all current regular resources as an array.

array apd_dump_persistent_resources()

Return all persistent resources as an array.

override_function(string func_name, string func_args, string func_code)

Syntax similar to create_function(). Overrides built-in functions (replaces them in the symbol table).

rename_function(string orig_name, string new_name)

Renames orig_name to new_name in the global function_table. Useful for temporarily overriding built-in functions.

The profiling functions can be placed at the start of your PHP code to force APD to dump profiling information out to text files in the directory defined in apd.dumpdir. These functions are:

apd_set_pprof_trace()

Dumps a tracefile named "pprof.<pid>" in your apd.dumpdir, which by default is set to /var/log/php4-apd/ on Debian systems. The tracefile is a machine parsable output file that can then be processed with the pprofp <tracefile> command. Do a 'pprofp -h' for detailed help, there are lots of options for sorting and formatting the output. Loads of fun here if your PHP is not running as fast as you'd like!

apd_set_session_trace(N)

Dumps a human-readable session trace named "apd_dump_<pid>" in your apd.dumpdir. This is the old way of doing things, noted here just because it still works (for now). It's been deprecated, so YMMV. Better to use a pprof trace instead if you can. 'N' is an integer that sets what items will be traced: just use a value of 99 for now, that'll turn on all implemented options.

More information can be found at http://pear.php.net/apd

At present options are configured in php.ini by setting variables that are passed to APD at startup. This may change in future.

apd.dumpdir

The directory used to store output files. Set to /var/log/php4-apd/ by default on Debian systems.

This manual page was written by Jonathan Oxer <jon@debian.org>, for the Debian GNU/Linux system (but may be used by others).