Stack Traces in 3 Minutes
As a developer, you will inevitably run into a stack trace daily. You know what I am talking about a bunch of lines stacked on top of each other with one looking more mysterious than the next. What the hell does it mean and where do we start decrypting this maze of seemingly unrelated text?
Well, fear no more. In this bite-sized article, I will explain just that.
Stack trace, what?
The PHP interpreter keeps track of every function executed at runtime by writing to a data structure called a stack. When a function is called it is added to the top of the stack and when the function finishes the interpreter removes it from the top of the stack.
A stack is a data structure where insertion and removal of items take place at the top of the stack. A basic stack implementation is also known as LIFO — Last In First Out
You can think of a stack trace as a manifest, a log of functions an application executed up to the point of failure. It will include information like the function name, filename, class name, line number,… where the interpreter thinks the error occurred. This allows us to re-trace steps the application took to identify the problem which caused the exception.
A stack trace does not include every function an application called before an error, rather it includes only a chain of functions called at the time the error occurred
How to read a stack trace
For our demonstration let us use a nonsensical example of a class for a Poker game.
The following code will throw an exception which will produce the following stack trace.
PHP Fatal error: Uncaught Error: Call to undefined function shufflr() in /Projects/StackTrace/index.php:16Stack trace:
#0 /Projects/StackTrace/index.php(29): Poker\Deck->_shuffle()
#1 /Projects/StackTrace/index.php(33): Poker\Deck->deal()
#2 {main} thrown in /Projects/StackTrace/index.php on line 16
In the first line, we will see a type of an error that occurred, why it occurred as well as file and line where it happened.
The following lines show the number of function calls executed before an exception was thrown.
It is very important to read the stack in reverse from the bottom up.
This way we can see that the program executed a {main} function which called a deal function which called the _shuffle function at which point an execution was interrupted by a thrown exception.
If we trace the execution path combined with our trace knowledge, we will see that the error occurred on line 16 due to a typo in a method name inside the _shuffle function, which is also our last function call in the stack trace.
Please note that the stack trace includes only the chain of functions leading to an exception.
You can see this behavior by looking at the deal function where a private function _log was called along with the _shuffle function however as the _log function returned the interpreter removed it from the top of the stack and is thus not included in the chain leading up to the exception.
Conclusion
That is it. Let us quickly summarize what we have learned
- A stack trace is a list of functions called up to the point of an error
- Stack trace should be read from the bottom up
- A stack is a data structure where insertion and removal of items takes place at the top of the stack
Bonus
Some people like their errors as verbose as possible while others prefer them short and condensed.
Whatever your preference is a stack trace output can be easily modified per your needs by utilizing the set_exception_handler method, i.e.
This will produce an output similar to the following
Exception: Call to undefined function shufflr()
Origin: /Projects/StackTrace/index.php on line 16=========
/Projects/StackTrace/index.php deal [55]
/Projects/StackTrace/index.php _shuffle [30]
The next time you encounter a stack trace you can now confidently approach it head on.
