Fix Your Code With The Debug Backtrace

The PHP debug_backtrace() function returns a function backtrace.
In a nutshell, the function backtrace is the list of all the function calls made up to that point.

The backtrace is one of the tools that you can use to debug your PHP scripts.

Specifically, it is the best tool when the value you need to debug is the result of multiple function calls.
So, let's see how that works exactly.

Let's take an example.
Say that you want to calculate the volume of a square pyramid, given the side of its square base and its height.

We are going to define a squareArea() function to calculate the base square area, a pyramidVolume() function to calculate the volume of a generic pyramid, and a squarePyramidVolume() function to calculate the volume of a square pyramid specifically.

Finally, we will call the squarePyramidVolume() function with 3 as the base square side and 4 as the pyramid height.
Here is our code:

function squareArea($side) {
return $side + $side;
}

function pyramidVolume($base, $height) {
return $base * $height / 3;
}

function squarePyramidVolume($side, $height) {
$baseArea = squareArea($side);
$volume = pyramidVolume($baseArea, $height);
echo 'Volume is ' . $volume;
}

squarePyramidVolume(3, 4);

The result should be 12, but this script prints 8 instead.
Something's wrong... but where? Is it the base area calculation that's wrong, or is it the pyramid volume calculation?

This example is easy. But in real scenarios, the error is often well hidden.

And here is where debug_backtrace() comes in our help.

You need to use debug_backtrace() inside the last function of the chain.
That would be pyramidVolume().
debug_backtrace() returns an array, so you can print it nicely with the <pre> tags.

Like this:

function pyramidVolume($base, $height) {
echo '<pre>';
print_r(debug_backtrace());
echo '</pre>';
return $base * $height / 3;
}

Now when you run the code again, you'll get the backtrace:

Array
(
[0] => Array
(
[file] => C:\xampp\htdocs\test.php
  [line] => 9
  [function] => pyramidVolume
  [args] => Array
  (
    [0] => 6
    [1] => 4
  )
)
[1] => Array
(
  [file] => C:\xampp\htdocs\test.php
[line] => 4
[function] => squarePyramidVolume
[args] => Array
(
[0] => 3
[1] => 4
)
)
)

Each element of the backtrace array is a function call.

The order is backwards, so the element [0] is the last call while [1] is the first.
For each call, you can see information including the function name and arguments.

In particular, you can see that pyramidVolume() is being called with 6 as the first argument (the base area).

But hey, shouldn't the base area be 9? Why is it 6?
This tells you that there is something wrong with the base variable.
And now you can go and check the culprit: the squareArea() function!
Indeed, there's a bug there: the area should be $side*$side, not $side+$side.

And that's how you use debug_backtrace().
Yes, it is a bit tricky, but in specific cases like this it can really save you tons of debugging time.