How to Use phpTrace to Debug PHP Function Calls and Parameters

Introduction to phptrace

phptrace is an open‑source tool from 360 Infrastructure that traces PHP execution, similar to strace but for PHP function calls. It can print the current PHP call stack and perform real‑time tracing of PHP functions, useful for development, testing, and production debugging.

Printing the current PHP process call stack

Unlike C programs where pstack or gdb can show the stack, PHP runs on a C‑based virtual machine. Using phptrace you can obtain the PHP‑level call stack directly.

$ pstack 3130
#0  0x00000035ee6accc0 in __nanosleep_nocancel () from /lib64/libc.so.6
#1  0x00000035ee6acb50 in sleep () from /lib64/libc.so.6
#2  0x0000000000714f23 in zif_sleep ()
#3  0x00000000008e36cd in execute_internal ()
#4  0x00007f27b38b2b77 in phptrace_execute_core () from /home/renyongquan/opt/php5.4.35/lib/php/extensions/debug-non-zts-20100525/phptrace.so
#5  0x00007f27b38b2c04 in phptrace_execute_internal () from /home/renyongquan/opt/php5.4.35/lib/php/extensions/debug-non-zts-20100525/phptrace.so
#6  0x00000000008e44bc in zend_do_fcall_common_helper_SPEC ()

Running phptrace on the same PID prints the PHP call stack:

$ ./phptrace -p 3130 -s
phptrace 0.1 demo, published by infra webcore team
process id = 3130
script_filename = /home/renyongquan/opt/nginx/webapp/block.php
[0x7f27b9a99dc8]  sleep /home/renyongquan/opt/nginx/webapp/block.php:6
[0x7f27b9a99d08]  say /home/renyongquan/opt/nginx/webapp/block.php:3
[0x7f27b9a99c50]  run /home/renyongquan/opt/nginx/webapp/block.php:10

The -p option specifies the PHP‑related process ID, and -s requests the stack information. Omitting -s switches to real‑time tracing.

Real‑time tracing of PHP calls (trace)

After installing the phptrace extension and restarting php‑fpm, the trace mode is enabled by default when -p is used.

$ phptrace -p 3130
curl http://localhost:8804/block.php   # re‑access block.php
phptrace output:
1417486170.247324 run(<Null>)
1417486170.247336   say($msg = "hello world")
1417486170.247356       sleep($seconds = "3600")

The first column is the timestamp, followed by the function call. In this example the sleep argument is 3600 seconds, so the HTTP request will return after one hour.

phptrace can also display return values and execution time when the traced functions return something.

$ ./phptrace -p 2459
1417506346.727223 run(<Null>)
1417506346.727232   say($msg = "hello world")
1417506346.727241       sleep($seconds = "1")
1417506347.727341       sleep => 0   1.000100
1417506347.727354   say => hello world   1.000122
1417506347.727358 run => nil   1.000135

Typical use cases

In a development environment, observe PHP function calls and their parameters.

Debug issues in development, e.g., missing files or directory access failures, by inspecting trace output.

Conclusion

phptrace provides a practical way to view PHP function calls, parameters, return values and timing, helping developers and operators diagnose problems during development, testing, and production.