Pedro Sostre


3 Non-Conventional PHP Troubleshooting/Debugging Methods That Can Save You Hours

Let’s start this out by saying I am a self-taught developer. To many formally educated programmers/developers/engineers, I do lots of things wrong.

I’m a hacker of the #2 variety:

So while I didn’t go to code school or get a degree in IT, I have been hacking things together for about 20 years now and I’ve gotten pretty good at it. If I have to build something nowadays, PHP/MySQL is usually my go to.

I don’t know Ruby or Python. I hear they are easier to work with and they feature more verbose error reporting, but since over 80% of all websites are powered by PHP, I figure that being proficient at it probably isn’t a bad thing.

PHP’s Anti-Helpful Errors

One of the things that drives everyone crazy is PHP’s habit of dying and leaving absolutely no clue as to what went wrong. The White Screen of Death (WSOD).

The nefarious White Screen of Death

As an entrepreneur, I’ve hired and worked with lots of developers. While most of them are professionally educated, they can still get tripped up when they encounter a WSOD that isn’t resolved by the standard debugging methods.

Another fun fail that PHP gives us is the ever helpful 500 error. This is often a syntax error and looks like this:

In either case, error handling is traditionally poor in PHP. While the debugging tools you get in the Python downloader package are quite sufficient most of the time — you really have to get creative when it comes to debugging PHP.

Established troubleshooting methods

I’m not going to spend too much time stating the obvious. If you’re a programmer, you are already familiar with standard and established debugging methods:

Displaying Errors on Screen & Error Logs

If your server is not configured to display errors (which it should be for any production environment), you can turn them on by putting the following at the top of your script:

ini_set(‘display_errors’, TRUE);
ini_set(‘display_startup_errors’, TRUE);

In many instances, you will see the errors on screen.

This does not always work.

Me when I’ve turned display_errors on and I still see no errors.

When you aren’t getting errors on the screen, you should try checking your error logs.

Depending on how your hosting environment is set up, you may or may not have access to error logs. For the purposes of this article, I’m going to assume that either you don’t have access to the logs, or the information contained in the logs don’t help you solve the problem.

Debugging Tools

I hear good things about Xdebug and modern IDEs like PhpStorm.

Xdebug is an extension for PHP to assist with debugging and development. It upgrades PHP’s var_dump() function, it adds stack traces for Notices, Warnings, Errors and Exceptions, it basically does a lot of the stuff PHP should do probably natively.

PhpStorm is an Integrated Development Environment (IDE) that helps by verifying your code as you type and helping you write neat code that’s (hopefully) bug free. When you do have issues, it offers a zero-configuration Visual Debugger and works with Xdebug and Zend Debugger.

Tools like this can help with catching syntax errors on the fly and getting more detailed errors at runtime. But what if either these tools aren’t solving the problem or you don’t have access to them? Time to consider some non-traditional debugging methods.

The Sostre Echo/Exit Method

Ok so maybe I didn’t actually invent this… and no one calls it the “Sostre Echo/Exit Method” — but I’ve shown enough developers how to do this that I’m convinced it should be a thing.

When you’re stuck and you have no idea how to find and fix an error — this can help isolate the issue.

It’s a variation on Runtime debugging, but it’s even simpler. When you have a script with hundreds of lines and you have no idea where the error is happening, this helps you determine what line is causing the issue.

If you’re stuck at the white screen of death, just start at the top of your document and write the following:

echo __LINE__;

And then run your script again.

If you still get the WSOD when the echo/exit is at the very top of your page, then you can scroll down to the next recommendation: Commenting Out Blocks of Code

If — instead of the WSOD — you see the line number, then you learn two things. 1) You probably aren’t dealing with a syntax error and 2) the issue is happening somewhere below whatever line number is being echoed.

From here you can just move those two lines of code further down the script, run it, and repeat until you get the WSOD again. At that point you know that the error is somewhere above your echo/exit code.

I understand how simple this seems, but you wouldn’t believe how many hours this has saved developers when they can’t figure out what’s going on. If you know exactly what line in the script is causing the failure, it becomes much easier to solve the problem.

Commenting out Blocks of Code

Again, this seems simple, but it’s not always the first thing you think of.

The echo/exit method works well when the issue is caused by a broken MySQL connection, a missing required file, or similar — but syntax errors may still return a 500 error.

When that happens, just start commenting out entire blocks of code.

To start, echo a “hello world” at the top of the script and comment out the entire rest of the script if you have to. You need the browser to show something — anything — so you can begin to figure out where the script is dying.

If you can get “hello world” to work, then start uncommenting code blocks little by little until the WSOD comes back.

Try the script on a different hosting environment

I’ve seen teams of developers spend hours trying to figure out why code wasn’t working, only to realize that the issue was a server-side configuration or restriction that was causing the code to fail.

If everything seems fine and you can’t see anything wrong with your code, try running the script on a different server. Keep a free or low cost shared account somewhere for testing in scenarios like this.

What Debugging Methods Work for You?

If you have some tips to share, post them in the comments below and I will add them to the article with full credit!

Shout out to CloudApp, which is the app I used to take/annotate the awesome screenshots. I used to use Snip, but it was recently discontinued and CloudApp is quite a nice upgrade. I highly recommend it when you need to clarify explanations, improve your debugging or QA process with screenshots, or take super simple screen recording.

Topics of interest

More Related Stories