Manual

Creates a function calls debug trace. Functions arguments, returned parameters and watched variables are reported in the same section for each function call. The trace is available as an array, or can be displayed or written in a file. Traced variables can be processed by provided user functions for displaying purposes.

Introduction

Introduction – PHP_FunctionCallTracer creates function calls debug trace.

Overview

Functions arguments, returned parameters and watched variables are reported in the same section for each function call. The trace is available as an array, or can be displayed or written in a file. Traced variables can be processed by provided user functions for displaying purposes.

This package is not a replacement for full fledged PHP debuggers. It is useful for (1) remote debugging, (2) to debug a complex sequence of function calls, (3) to display non text variables in a user readable format.

Remote debugging is sometimes the only option to debug a package that works fine on your system, e.g. a 32-bit OS, but breaks on a different system, e.g. a 64-bit OS, which you have no access to. A remote user who has the latter OS could run the package, then send you the trace for analysis.
It is sometimes difficult not to loose track of functions calls in some live debugging sessions even with top notch PHP editor/debuggers. The trace produced by this package may come handy and is easy to use in combination with the source code to track calls and variables.
Some variables native format does not always display well, typically: packed data and UTF-8 strings. They can be converted as they are being traced to a readable format by provided user functions. For example: converting binary strings to hexadecimal, or UTF-8 string to Unicode.

Basic Use

Basic Use – Simple trace of function arguments and returned variables.

Overview

traceArguments() is used to trace the function arguments. There is no need to pass the function arguments to traceArguments() to trace them. Note that traceArguments() may not be used, if the function does not call any other function or if the function calls functions that are not being traced.

traceVariables() is used to trace variables within the function. The variables to trace must be passed as arguments to traceVariables(). traceVariables() may be called as many times as required to watch variables value change.

traceReturn() is used to trace the variables returned by the function. The variables to trace must be passed as arguments to traceReturn().

putTrace() is used to display the trace to the standard output or to write it into a file.

How to use PHP_FunctionCallTracer

In this example, package.php contains two classes whose methods are traced. The package is used by an application trace.php. The trace is stored into trace.txt. To generate the trace, run: #php trace.php.

The package package.php

Note that testing if PHP_FunctionCallTracer is loaded: class_exists('PHP_FunctionCallTracer', false), is optional. It is useful only if the tracing methods are meant to be left in the code. They will be called only if PHP_FunctionCallTracer is loaded.

<?php
class math {
    /**
     * tracing the arguments and the returned parameter
     *
     * note that traceReturn() calls traceArguments() by default which is fine here
     * since this method does call other methods to trace
     */
    public static function prod($x, $y)
    {
        // class_exists('PHP_FunctionCallTracer', false)
        // and PHP_FunctionCallTracer::traceArguments();
        $p = $x * $y;

        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceReturn($p);
        return $p;
    }

    /**
     * tracing the arguments and the returned parameter
     *
     * traceArguments() must be called here since this method calls other methods
     * that may be traced, so that traced calls are displayed in the right order
     */
    public static function square($x)
    {
        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceArguments();

        $x2 = self::prod($x, $x);

        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceReturn($x2);
        return $x2;
    }
}

class geometry {
    private $pi = 3.14;

    /**
     * tracing the arguments and the returned parameter
     * another variable is traced along with the returned parameter
     */
    public function circle($r)
    {
        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceArguments();

        $pi2 = 2 * $this->pi;
        $c = math::prod($r, $pi2);

        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceReturn($c, $pi2);
        return $c;
    }

    /**
     * tracing the arguments, some variables and the returned parameter
     */
    public function disk($r)
    {
        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceArguments();

        $r2 = math::square($r);
        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceVariables($r2, $this->pi);

        $d = math::prod($r2, $this->pi);

        class_exists('PHP_FunctionCallTracer', false) and
        PHP_FunctionCallTracer::traceReturn($d);
        return $d;
    }
}
?>

The application trace.php

<?php
/**
 * adds the path of the package if this is a raw install
 * includes the package (example) to debug and the tracer package
 */
file_exists("../../../../PHP/") and set_include_path('../../../..' . PATH_SEPARATOR . get_include_path());
require_once 'package.php';
require_once 'PHP/FunctionCallTracer.php';

/**
 * creates an instance of the class to debug and calls a few methods
 * writes the trace in a file
 */
$geometry = new geometry;
$c = $geometry->circle(2);
$d = $geometry->disk(3);

$file = dirname(__FILE__) . '/trace.txt';
PHP_FunctionCallTracer::putTrace($file, false);
?>

The trace trace.txt