Basics of PHP Debugging – Read the errors

This post is also available in: Português (Portuguese (Brazil))

TL;DR

This post will give you some tips on the most important step of debugging your application: Read the errors. Looks idiot, but many developers fails here. They see – and don’t read – the error message and go directly to Google or Stack Overflow looking for direct answers. This approach may work when you are just running an application that you downloaded and installed on your web server, but will tell nothing when it’s related to your own code. But the error itself points what’s occurring and where (which line). So, READ THE ERRORS!

Introduction

Countless times I’ve seen posts on Stack Overflow where people posts like this:

I have this code “…” but it don’t work! How to fix it?

It don’t work? Just that? There are two alternatives for a code that don’t work: it throw a error message on the screen, or it don’t do the expected behavior, right? On this post, we learn how to deal with the first alternative, by READING THE ERRORS.

The error tell you important things

Remember this. The error is always pointing the mistake and trying to explain it to you that knows (or should know) the code.

PHP error messages have the following structure:

PHP Notice: Undefined variable: name in index.php on line 5
\________/ \______________________/ \_______/ \____/
(1) (2) (3) (4)

1 - Error severity
2 - Error message
3 - Filename
4 - Line number

Just by reading the error message (2) we can realize that we are calling to a variable that don’t exists, right? To fix it, we need to known on which file (3) and on what line (4) the error occurs.

To put context on this error, lets see the code:

Now we can clearly see that on line 5, we are passing $name as parameter, and PHP is telling us that that variable don’t exists.
In this case, we just need to look on the previous lines for the $name declaration, then notice that we typed the wrong variable name.

Nice, we read our first error message. What now?

Read the stack trace

On a complex application, sometimes you may not know why some piece of code is being called, or how that parameter value is there.

Let’s see this example:

Executing this code will result in the following error message:

Fatal error: Uncaught TypeError: Argument 1 passed to splitMyName() must be of the type string, null given, called in /var/www/public/demo.php on line 8 and defined in /var/www/public/demo.php:3 Stack trace: #0 /var/www/public/demo.php(8): splitMyName(NULL) #1 /var/www/public/demo.php(17): extractNameFromData(Array) #2 {main} thrown in /var/www/public/demo.php on line 3

Note that now after the error message, we have a Stack Trace. The stack trace is useful to understand who is calling a given function that results in that error. The stack trace is reverse, what means that the position #0 is the line of code that the error occurred.

Here we can see that: splitMyName is being called with NULL as parameter inside extractNameFromData() function. We also can see that the extractNameFromData() was called on line 17.

Now imagine in a complex application, where the stack is as big as the application, and that function is called on many places. It’s almost impossible (unless you have memorized your entire code) why that function is receiving the wrong parameter. We need to follow the stack trace! That’s the lesson here.

If your function looks right, someone should be messing the parameters. Maybe the function is called on the same file once, or many times, or even on many files. Will be easier if you follow the stack trace. You will just follow the traces that PHP gives to you.

Conclusion

Learn to read the errors is very important if you want to be a good and efficient developer. It will save you precious time that you can use to sleep. 😀

This series will have a few more posts, I plan to explain how to debug your logic when there’s no errors.