PHP Debugging

The majority of the time, PHP debugging is a bit more straightforward than HTML debugging because most web servers will actually show you PHP errors directly on your live site. These error messages can be used to track down the bad code to get it fixed.

With that said, there are some web servers that suppress these PHP error messages. There is some PHP code that can be used to make some of the errors display on these servers, but ultimately, you simply cannot get all errors with that web server setting disabled.

One easy way to tell if your web server doesn't show PHP errors is to simply create an error yourself and see if it displays an error message on your live site.

Try this code (which has an error in it - a missing semicolon at the end of $a = 1):

<?php

$a = 1

echo $a;

?>

If that code produces an error, you're good to go. If it does not (it may just show you a blank page without the error messages), then you will need to send your web host a quick email to get error reporting enabled. Simply say 'I noticed PHP error reporting is disabled on my server. Could you please enable the error_reporting setting on my server in php.ini for debugging purposes?'.

It is also possible that error_reporting is disabled, but the error_log setting may be enabled. Take a look at the base directory of your site and look for a file called error_log. If this can be found, download it and open it in Notepad++ - this file will contain the error messages from your site. Sometimes this file may actually be generated in directories other than your public_html directory. The error_log is technically generated in the directory of the script you're running that has the errors. However, this is the original script not being used and not necessarily the script with the error in it. For example, with WordPress, all error logs on the site will be found in the base directory because scripts are processed through the index.php file in the base directory (even PHP code in the content of your pages). For administration pages in WordPress, this error_log is created in the wp-admin directory of the site.

As long as you can get access to errors from your site using one of those two methods, you can proceed with this tutorial. Without those error messages, you'll literally be blind trying to figure out what the problem is in your PHP code.

It is also worth explaining that there are different types of errors. The least serious of these errors are called Notices - these will actually not be displayed on a large majority of web servers, which is quite alright. For example, if you try to use a variable in an IF, ELSE statement and that variable was never defined, one of these Notice errors would be displayed (if enabled on your server). However, these errors will generally not alter the end result of your script, so I will be discussing other errors.

I am now going to go through some example PHP error codes. The main thing to pay attention to here is the wording of the error codes because I will be teaching you how to apply these same concepts to other errors of the same type. This is truly the key to debugging PHP - just understanding these error codes and where to go look in your code as a result. If all else fails, search the first few words from your error code (just leave out information that relates specifically to your site), and you can generally find out about that error and how to fix it.

Parse Error

Using the PHP code that I provided above will generate a parse error.

Here is the parse error generated from that code:

Notice the beginning of the line: Parse error

Next is a clarification of the exact error: syntax error, unexpected T_ECHO

If you search Parse error: syntax error, unexpected T_ECHO on Google, then you can easily find out information about what this error means and how to fix it (just in case this happens and you are not sure what to do).

A syntax error indicates that you are missing a character in your coding, which prevents it from processing correctly.

Next, the middle of the error that is in bold text indicates where this error happens on your site. For this example, it points to a PHP file in the wp-content/plugins/exec-php folder of my site. This is because I run the code in my page content on a WordPress site - it is uses the plugin exec-php to process the PHP code. If you run the code through a standard PHP file on your site, it would indicate that particular PHP file as generating the error (WordPress using exec-php will always indicate that plugin file).

Use the information provided there with the file name to determine where to look for the error. On WordPress sites, it doesn't indicate that the error is in the PHP file for that plugin though - the error is in your page content instead (that is why it says eval()'d code).

The last part of the error message is a line number - this indicates the line number in the code that is creating the error.

Notepad++ works great to help you find code base on those line numbers. I've copied that PHP code into a PHP file in Notepad++ to demonstrate:

Notice on the left-hand side how the lines of code are numbered - these are the line numbers referred to in the error codes!

This error code tells me to look at line #3. That line is the echo command, which is actually a correct line of PHP code, so why does it say the error is here?

The error is on line 3 because of the coding that is in line 2 - this pretty common, so be sure to look at the line before for errors also.

The error says that T_ECHO is unexpected in the code. T_ECHO references the PHP command ECHO.

PHP will uses representations (called Parser Tokens) for commands in this manner. If you run upon one of these that you don't recognize, look at the page below for more info:

http://www.php.net/manual/en/tokens.php

The error in this example happens because line #2 is missing the semicolon at the end of the line (which closes that PHP command). Since that line of code is not closed properly with a semicolon, then the ECHO command on the next line is unexpected (because a semicolon is the next character that is expected in the code).

Unexpected $end

Sometimes this same error sequence can be used without referencing a Parser Token.

Take a look at this sample PHP code (which has an error):

This PHP code generates this error message (running through a WordPress page):

In this error, the main difference is towards the beginning: unexpected $end

$end is not actually listed as a Parser Token on php.net.

This error message actually indicates that you are missing a curly bracket in your PHP code. $end makes reference to the end of the PHP code - the end of the code is unexpected because of the syntax error (the missing curly bracket after the ELSE command).

The error line number, 10, is actually the very last line of code - the closing PHP tag. Whenever you get a PHP error that references the last line of the code like this, look for missing curly brackets.

Here is the fixed PHP code for this example - notice that I simply added the missing, closing curly bracket to line #8 - after the ELSE command.

One more thing I want to point out with this example is another feature of Notepad++. Look where my mouse/typing cursor is located in the picture above - right after the closing curly bracket that I added. Whenever you click immediately before or after a parenthesis or curly bracket in your PHP code in Notepad++, it will highlight that parenthesis or curly bracket in red AND it will also highlight the matching parenthesis or curly bracket!

You can use this technique to easily find missing parenthesis or curly brackets in your code by simply looking to see if Notepad++ matches them correctly. If you are missing one, it may indicate a different character as the matching character (instead of the correct one).

Unexpected '}'

Sometimes PHP will mention a specific charter in the error code as being unexpected.

I have used the same PHP code from before but used a different error this time:

This time, I have left off the opening curly bracket for the ELSE statement instead of the closing curly bracket.

Instead of getting another unexpected $end error this time, I actually get an unexpected '}' error:

With the missing opening curly bracket this time, the extra closing curly bracket is indicated as the error instead of the end of the code. This type of error is generally easier to fix because the line number in the code that is referenced has more meaning (because it points to an actual line of code and not the last line of the file).

By simply adding the missing opening curly bracket, this code will be fixed. The fixed code for this example is actually exactly the same as the previous example, so I won't repeat that again.

Warning Errors

Another type of error that PHP can generate is a Warning. A Warning error also indicates a problem with your code, but this type of error doesn't stop valid code in the same script from processing correctly (but it does with other errors, like the parse errors demonstrated previously).

I have set up another example to show this type of error. I have included the broken code below:

At a first glance, this code may appear to be correct. The colors in Notepad++ show up correctly in this example, so the error is not a parse/syntax error.

The problem with this example is actually the variable that I have declared in the second line of code. I set $a equal to the number 1. That alone isn't a problem, but then the code in line number 3 tries to use that variable as though it was an array.

Here is the output of this code - an error code is displayed but also note the additional text shown below the error code:

The error here is a Warning error.

The actual error is: Invalid argument supplied for foreach()

Remember, if you run upon an error that you don't know, just search everything up to this point in the error message in Google.

The error is generated on line #3 of the code.

Below the error is text This code still gets processed, despite errors above it. Notice that text was displayed because of the ECHO command used on line #7 of the code. Despite the error happening before line #7, that code still gets processed because it is valid code and Warning errors do not cause the script to completely stop running!

If you look at line #3 in the code, you'll see that is the foreach() statement that is used to loop through values in an array. Since $a is a variable and not an array, the Warning error is shown and indicates an invalid argument (and that function name). Invalid argument simply means that the arguments (variables/arrays) you've supplied for a command are of the wrong type.

In this example, the problem is that you can't loop through the values of a variable - only arrays.

Here is the code but fixed - I fixed it by changing the $a variable into an array. This could also be fixed by eliminating the foreach statement, since the original variable $a only had one value.

With these Warning errors, the affected part of the code will not run, but everything else will still get processed. As a result, these errors may not prevent your script from working overall, even though this one part would not function (it really just depends if the other parts of your script depend on the broken part to work).

Fatal Errors

Besides Notices and Warnings, the other main type of PHP error is a Fatal Error. These errors completely prevent a script from running, even the parts that do not have errors. The Parse/Syntax Errors I discussed previously do completely stop a script from running, but there is one main difference - it doesn't prevent parent scripts from running.

I have put together an example of a Fatal Error to show how this works and what causes it - here is the broken code for this example:

First I will point out the error here. I have defined a function by the name of my_custom_function_name, which simply echoes some text to the browser.

The error occurs when I try to call that function and do not provide the correct name. Even though the names are close, PHP cannot figure out what you want because you could technically have two different functions in a script - each with one of those names: my_custom_function_name and mycustomfunctionname.

Now look at the browser display for this code - I am actually running this within a WordPress site so I can demonstrate the difference between a Fatal Error and a Parse Error:

I have shown the entire browser output this time, including the other parts that are generated by WordPress.

The actual Fatal error here is: Call to undefined function

The undefined function is: mycustomfunctionname()

This just means that the function doesn't exist in the script, so this error is actually pretty straightforward about what is wrong.

Now compare that to the full browser output from this Parse Error that is from a different example:

Notice how the Wordpress footer and sidebar show up with the Parse Error but NOT the Fatal Error. The Parse Error allows the parent script, WordPress, to continue to run, even though the rest of the script containing the Parse Error is still not processed. With the Fatal Error, it shuts down all output and script processing once the Fatal Error is reached, even for parent scripts (that is why the sidebar and footer do not show up on the Fatal Error page).

All that is needed to fix this error is to correct the function name being called to one that actually exists or just create a function by the name being used (or perhaps change the name of the actual function, instead of the call to the function - just depends on what works best for your situation).

I've fixed the PHP code below by simply changing the function call to the correct name that I defined for my function: