Docs For Class PHP_FunctionCallTracer

[line 133]
Function Call Tracer

Traces functions arguments, returned parameters, and watched variables. Sets user functions and processes any of the above.

Main methods:

self::traceArguments() traces the function arguments.
self::traceReturn() traces the returned parameters by the function.
self::traceVariables() traces variables within the function.
self::setUserFunctions() sets user functions to process variables.
self::processVariables() processes variables with user functions.
self::getTrace() returns the function calls trace.
self::putTrace() displays or writes the function calls trace in a file.

Usage including trace examples is fully documented in docs/examples files.

Some basic examples:

 Example 1: tracing argument: $a, variable: $b, returned parameter: $c

 require_once 'PHP/FunctionCallTracer.php';

 function foo($a)
 {
          PHP_FunctionCallTracer::traceArguments();

          $b = strtoupper($a);
          PHP_FunctionCallTracer::traceVariables($b);

          $c = true;
          PHP_FunctionCallTracer::traceReturn($c);
          return $c;
 }

 $c = foo('foo');
 PHP_FunctionCallTracer::putTrace();

 Example 2: tracing and rounding variable: $a

 require_once 'PHP/FunctionCallTracer.php';

 PHP_FunctionCallTracer::setUserFunctions('round');

 function bar($a)
 {
          $a *= 2;
          PHP_FunctionCallTracer::traceVariables($a);
          PHP_FunctionCallTracer::processVariables();

          return $a;
 }

 $a = bar(1.23);
 PHP_FunctionCallTracer::putTrace();

Author: Michel Corne <mcorne@yahoo.com>
Version: Release:@package_version@
Copyright: 2007 Michel Corne
Link: http://pear.php.net/package/PHP_FunctionCallTracer
License: The BSD License

createStackKey [line 226]

array createStackKey(
array
$trace)

Creates a function call ID stack key

Based on the backtrace. Ignores the last function call. Retains only the data clearly identifying the call: 'file', 'line', 'class', 'type', 'function'. Serializes the backtrace to build the key.

Return: the function call ID stack key
Access: public

Parameters:

array $trace — the function call backtrace

[ Top ]

filterTrace [line 200]

array filterTrace(
array
$trace, array
$keys)

Filters some key/values of a function calls trace

Return: the filtered function call trace
Access: public

Parameters:

array	`$trace`	—	the function call trace
array	`$keys`	—	the keys to keep

[ Top ]

getTrace [line 247]

array getTrace(
[boolean
$getPhpInfo = true])

Gets the function calls trace

This method is usually called at the end of a debugging session.

Return: the function calls trace
Access: public

Parameters:

boolean $getPhpInfo — the phpinfo is to be captured if true, or not if false, the default is true

[ Top ]

isCallable [line 278]

boolean isCallable(
array
$function)

Determines if the provided user function is callable

Return: true if callable, false if not
Access: public

Parameters:

array $function — the user function, e.g. 'dechex', or object method, e.g. array($object, 'foo'), or static method, e.g. array('foo', 'bar')

[ Top ]

processVariables [line 332]

boolean processVariables(
)

Processes a set of variables with provided user functions

It is usually called after self::traceArguments(), self::traceReturn(), or self::traceVariables(). It will process the variables passed to the above functions. This method is used in 2 different ways.

(1) If the package is used with one user function, e.g. self::setUserFunctions('dechex'), this method is expecting as arguments the keys of variables that were passed to the above functions. Examples when called after self::traceArguments($a, $b, $c):

self::processVariables() => $a, $b, $c are processed.
self::processVariables(true) => $a, $b, $c are processed.
self::processVariables(0) => $a only is processed.
self::processVariables(0,1) => $a and $b only are processed.

(2) If the package is used with 2 or more user function : e.g. self::setUserFunctions('dechex', 'bin2hex'), this method is expecting for each argument a set of keys of variables that were passed to the above functions. Examples when called after self::traceArguments($a, $b, $c):

self::processVariables() => $a, $b, $c are processed by dechex.
self::processVariables(null, true) => $a, $b, $c are processed by bin2hex.
self::processVariables(0, 1) => $a is processed by dechex and $b by bin2hex.
self::processVariables(0, array(1, 2)) => $a is processed by dexhex, and $b and $c by bin2hex.

Automatically calls self::traceArguments() if this method is the first one called within a function.

Return: false if this method is not called by a function, true otherwise (actually the function call trace detail)
Access: public

[ Top ]

putTrace [line 401]

array putTrace(
[string
$file = ''], [boolean
$getPhpInfo = null])

Displays or writes the function calls trace in a file

This method is usually called at the end of a debugging session.

Return: the function calls trace
Access: public

Parameters:

string	`$file`	—	the name of the file, or the standard ouput if empty or by default
boolean	`$getPhpInfo`	—	the phpinfo is to be captured if true, or not if false, the default is true for a file and false for the standard output

[ Top ]

reset [line 434]

void reset(
)

Resets the class settings and working variables

This method is needed when 2 or more debug sessions are run in a row. There is no need to call this method before self::setUserFunctions() which calls this method internally.

Access: public

[ Top ]

setUserFunctions [line 465]

array setUserFunctions(
)

Sets provided user functions

Each argument is expected to be a callable function or object/class method. Examples:

self::setUserFunctions('dechex') => the PHP function dexhex
self::setUserFunctions(array($object, 'foo')) => the object method foo
self::setUserFunctions(array('foo', 'bar')) => the class method foo::bar
self::setUserFunctions('dechex', array('foo', 'bar')) => a combination of the PHP function dexhex and the class method foo::bar.

The first argument is the user function/method #0, the second is #1 etc... This order number is used when passing variables keys to self::processVariables().

Verifies that the user functions/methods are callable. Reports which ones are callable or not in the function calls trace.

Return: the 2 sets of callable and invalid functions/methods
Access: public

[ Top ]

tidyMethodName [line 496]

string tidyMethodName(
mixed
$function)

Tidies the object/class method name

Return: the tidied function/method name, e.g. 'dexhex', or 'blah=>foo', or 'foo::bar'
Access: public

Parameters:

mixed $function — a function name, e.g. 'dechex', or an object method, e.g. array('class' => $object, 'type' => '->', 'function' => 'foo'), or a class method, e.g. array('class' => 'foo', 'type' => '::', 'function' => 'bar')

[ Top ]

traceArguments [line 546]

boolean traceArguments(
)

Traces the argments passed to a function

Usually called within a function before the rest of the function code. Normally, not expecting any arguments since they are captured automaticly. However, if the function expects arguments passed by reference, the arguments should be passed explicitly, due to PHP Bug 42058: "debug_backtrace messes up with references". For example, given the function foo($a, &$b): self::traceArguments($a, $b) should be used instead of self::traceArguments() to trace arguments properly.

Called automaticly by self::traceReturn(), self::traceVariables() or self::processVariables() if it is not called explicitly before any of those methods within the function.

It should always be called if the function itself calls other functions that are being traced as well, in order to keep the function calls in order within the trace.

Return: false if this method is not called by a function, true otherwise (actually the function call trace detail)
Access: public

[ Top ]

traceReturn [line 600]

boolean traceReturn(
)

Traces the return parameters

Optionally called within a function before a return statement. Normally expecting the parameters returned by the function, plus optionally any other variables. For example, given the return($a, $b) statement in a function: self::traceReturn($a, $b) should preceed this return statement.

Automatically calls self::traceArguments() if it is not called explicitly before this method within the function.

Return: false if this method is not called by a function, true otherwise (actually the function call trace detail)
Access: public

[ Top ]

traceVariables [line 639]

boolean traceVariables(
)

Traces variables used by a function

Expecting a list of variables. For example, self::traceVariables($a, $b).

Automatically calls self::traceArguments() if it is not called explicitly before this method within the function.

Return: false if this method is not called by a function, true otherwise (actually the function call trace detail)
Access: public

[ Top ]

Class: PHP_FunctionCallTracer

Class Overview

Author(s):

Version:

Copyright:

Methods

Inherited Variables

Inherited Methods

Class Details

Method Detail

createStackKey [line 226]

Parameters:

filterTrace [line 200]

Parameters:

getTrace [line 247]

Parameters:

isCallable [line 278]

Parameters:

processVariables [line 332]

putTrace [line 401]

Parameters:

reset [line 434]

setUserFunctions [line 465]

tidyMethodName [line 496]

Parameters:

traceArguments [line 546]

traceReturn [line 600]

traceVariables [line 639]