Subscribe to PHP Freaks RSS

Debugging: A Beginner's guide

by Ben Smithers on Jun 9, 2008 5:47:39 PM - 102,734 views


Everyday the forums see probably hundreds of topics posted where the problem is a fairly simple error. These generally fall in 4 categories:

  • Syntactical/parse errors
  • Fatal errors, warnings and notices
  • Database errors
  • Logical errors

As a beginner, it can be difficult to find and solve these errors. By tackling each of these in turn, I hope to teach you some methods of finding and solving them. So we'll get started with syntactical errors first.

Syntax Errors

Syntax errors. Eugh. We've all been there -- a nasty error message and we don't know what it means.

However, sometimes people don't even get as far as seeing the error message: they have PHP setup so that it won't display them. Handy for a live site; but rubbish for something in development. So turn them on! Either do this through your php.ini file (you're looking for the display_errors setting) or through the ini_set function. You can add this to the top of your code:


Note: Unfortunately, if your error is syntactical, then you'll need to make this change to your php.ini. If PHP can't parse the page correctly, then the change to the setting won't be made. (with thanks to philipolson for mentioning this)

This is often the cause of the 'My page shows nothing!' problem, which is seen so often on the forum. That is, there's a syntax error, but it's not being displayed.

Right, now that we're not flying blind and we're actually going to see our errors, we can move onto fixing them.

Syntax Errors -- Debugging

Computers are stupid. You can quite easily understand something with a missing piece of punctuation, but computers? They throw their teddies out the pram. You might, for instance, see this:

Parse error: syntax error, unexpected T_VARIABLE in C:\wamp\www\phpfreaks.php on line 3

Now, when something's unexpected, it means just that. However, it does not always mean that it's not required. For example, the above error message was generated with this code:

$foo ='foo'
$bar = 'bar';

The unexpected element of the above is $bar. But we wanted to define $bar, that's not unexpected. What is unexpected is the lack of semi-colon on the previous line. This leads us to one important aspect of finding and fixing errors: check the previous lines.

Other common causes of syntax errors are:

  • Unclosed quotes
  • Missing or Extra parentheses (for example, with if statements)
  • Unclosed braces -- more on this later

One thing that will help you avoid making syntax errors is the use of a good editor with syntax highlighting. This will make things such as unclosed quotes very obvious. I'd personally recommend PHP Designer or Eclipse, but other people will suggest different editors. There's a long thread here dedicated to the debate.

That's a wrap on syntax errors so we'll move onto fatal errors, warnings and notices.

Fatal Errors, Warnings and Notices

Now would be a good time to mention another common mistake: the use of error suppression during development. PHP allows you to quietly ignore errors (other than syntactical) by placing the @ symbol at the start of the line. As with the display of errors, this is handy for a production server –- but when you're trying to find out why something doesn't work, it's worse than useless.

Fatal errors

Fatal errors are caused when PHP understands what you've written, however what you're asking it to do can't be done. Common examples include trying to use a function or class that hasn't been defined. Fortunately, the error message generated should be nice and obvious:

Fatal error: Call to undefined function foobar() in C:\wamp\www\phpfreaks.php on line 2


Warnings refer to things which PHP can cope with, but it's likely you didn't intend them. Common causes include trying to include a missing file or using the incorrect number of parameters in a function. Again, the error message should help you out.

Probably the most common warning sent is the one that looks something like this:

Warning: Cannot modify header information - headers already sent by (output started at C:\wamp\www\phpfreaks.php:2) in C:\wamp\www\phpfreaks.php on line 3

Or like this:

Warning: session_start() [function.session-start]: Cannot send session cache limiter - headers already sent (output started at C:\wamp\www\phpfreaks.php:2) in C:\wamp\www\phpfreaks.php on line 3

Both of these are caused by the same thing: you cannot change headers -- which includes changing location or setting a cookie/session -- after you have sent any content to the browser (ok smarty-pants so you can with output buffering, but that's a different subject for a different day).

Note: Output includes whitespace. So you can't even send a space or blankline before you send a header. This catches people out sometimes, particularly when including files. You might have some whitespace after your closing PHP tag which is included in another file.


Finally, we have notices. So often ignored, but can actually help you track an awful lot of errors. A notice is generally given for something which is undefined: a variable, constant or element of an array.

Before you see them, however, you'll need to make sure that PHP is setup to report them. This requires a further change of your php.ini. I recommend changing the error_reporting setting to E_ALL. This can also be done at the top of your script with:


For more on error reporting and the relevant options, see the manual.

If you've just turned notices on, you may have just got a truckload of error messages. PHP can cope with notices, hence why your script was working before. But as mentioned, notices are incredibly useful for tracking typos by warning you of an undeclared variable. Common notices come from unquoted strings being used as the key of an array, such as:

$array = array('key'=>'value');
echo $array[key];

This is because, without quotes, key is a constant and not a string. Whenever PHP encounters undefined constants, it assumes that it's a string, so it can cope. However, best practice is to place quotes around the key if it is a string.

Note: It's perfectly acceptable to use an unquoted string as your key inside double quotes, such as:

$array = array('key'=>'value');
echo "The array contains just one value: $array[key]";

That about wraps it up for our first two types of error, so we'll move onto database errors.

Database Errors

How often have you seen this?

Warning: mysql_fetch_assoc(): supplied argument is not a valid MySQL result resource in C:\wamp\www\phpfreaks.php on line 5

The error message doesn't tell you a lot, does it? What it does tell you is that there was an error with your query. What we need is way of seeing that error. Handily, mysql_error() does just that. Now, you will see a lot of people on the forum (myself included) suggesting that to test a query you should add an or die statement and echo mysql_error() like so:

$result = mysql_query("SELECT * FROM tbl WHERE ...") or die(mysql_error());

However, better practice would be to use "or trigger_error()". Why? Well, because it will save you troubles should the script go live. By throwing an error, you still get the benefit of seeing the problem whilst you are developing and have display_errors turned on, but can also handle things gracefully should the script go live and you turn off error_reporting. You'll also want to echo your query. It's so much easier to spot a syntax error when you actually look at what is being executed. This is particularly true if the query is complex and contains many variables.

Therefore, you should do this:

$sql = "SELECT * FROM tbl WHERE ...";
$result = mysql_query($sql) or trigger_error(mysql_error().'<br />Query was:'.$sql,E_USER_ERROR);

Notice that we create our query in a string before we execute it; this allows us to echo it.

Now, you might also have a query which does not generate an error, but also doesn't return what you expect. You may, for example, be expecting lots of rows but don't get any. Again, the best thing you can do is to echo the query:

$sql = "SELECT * FROM tbl WHERE ...";
$result = mysql_query($sql) or trigger_error(mysql_error().'<br />Query was:'.$sql,E_USER_ERROR);
echo '<br />'.Query was:'.$sql.'<br />';

9 times out of 10 you will find that a variable in your query doesn't contain what you expected it to and so can trace the error.

Finally, we'll talk a little bit about logical errors on the next page.

Logical Errors

So your script doesn't report any errors and the queries are working fine. But it doesn't do what it's supposed to. Chances are, you have an error in your logic.

Unfortunately, logical errors are the hardest to find. You may have been expecting an if statement to be true, when indeed it is false. The best solution to any problem like this is: echo, echo, echo. You must echo out information at strategic places throughout your script to help you narrow down the problem. You might, for example, check that a function has been called by placing an echo inside it. You might echo a variable to check its value; or you might echo something after an if statement to see if it was true or false. Never assume anything. You might have missed something and your best bet is to be patient and track it down.

Logical errors are also often caused by poor code layout. Always indent code between braces. Again, a good editor will help you out, as it will do this for you. It's much easier to keep track of braces and spot missing ones if you properly indent your code. It should also allow you to highlight one brace and find it's partner. The worst error message you can see is this:

Parse error: syntax error, unexpected $end in C:\wamp\www\phpfreaks.php on line 3

This usually means there's an unclosed brace. I've seen plenty of people assume they can just tack a brace onto the end of the script. It's almost never that simple. If I see someone with this problem, they're on their own! Your only option is to carefully walk though your code and make sure every brace is opened and closed in the correct place.

This error would also be generated if you had an unclosed backtick (`). Thanks to 448191 for pointing out that a lot of editors don't pick this up in their highlighting, so it could be tricky to spot.

That's it for logical errors and the whole tutorial. Just sit tight through the summary and you'll be off.

Tutorial Summary

In no particular order, here are my tips for finding your errors:

  • Make sure PHP is displaying errors
  • Set your error reporting to E_ALL
  • Remove error suppression
  • Use a good editor
  • Indent your code
  • Use 'or trigger_error' statements with every query
  • Echo out if you're having problems
  • Check the previous lines for syntax errors

I should also say that my intention with this tutorial was to provide some general help for a beginner during the development stage. You should note that there are other, more graceful methods of handling errors (an error handling class with exceptions being the best route) in the long run. Even if you don't go the whole hog you should consider the following before your site goes live:

  • Turning off display errors. Yeah, I know I told you to turn it on earlier, but that was to help you find the error to start with. Once your site is live, you don't want users seeing nasty error messages.
  • Ensuring log_errors is turned on. This allows you to find out if any errors do occur after your site is live.
  • Think about your error_reporting level. In PHP 6, E_STRICT errors will become apart of E_ALL. For more on this, see the manual.


philipolson Jun 10, 2008 2:09:56 PM

One small note worth adding: setting display_errors at runtime (ini_set()) won't work if the script contains fatal errors (like a parse error) because it will never get executed.

Ben Smithers Jun 10, 2008 5:13:00 PM

That's a good point there. I'll add a note in to that effect.

anthropos9 Jun 10, 2008 6:55:58 PM

You can also set error reporting in the .htaccess file if you have access to that and not your php.ini file. Here's what you need to put in the .htaccess file

php_flag display_errors on
php_value error_reporting 2047

// Or whatever error reporting level you want to use - I use 2047.

Daniel Jun 11, 2008 12:54:49 AM

Re comment #1: Did you check that what you said is true? Setting it at runtine does work (providing you do it before any errors occur).

Ben Smithers Jun 11, 2008 1:40:02 AM

With a syntax error Daniel? Not in my tests. With error_reporting turned off, this prodces a blank page:

echo 'test'
echo 'test';
Daniel Jun 11, 2008 2:39:08 AM

Hmm... I tested using


That does not output any errors. I just figured it would be the same type of fatal error as a syntax error would.

Ben Smithers Jun 11, 2008 7:22:07 AM

Yeah, but then i think that makes sense. If there's a parse error, then the PHP engine wont be able make sense of the code; so it wont be able to understand that it's supposed to make a modification to the php.ini. Whereas with something like a fatal error for an undefined function, PHP can understand what it's being asked to do, just can't do it.

Also; valid point regarding .htaccess anthopos9. I'm not sure i'll add it in however, as it might just confuse the issue.

Stephen Jun 15, 2008 8:31:49 PM

Ben, with the htaccess thing... "php_flag display_errors on
php_value error_reporting 2047"

Right now theres nothing in the htaccess file but it writes errors to "error_log".
If I added in what you said would it fix it?

Ben Smithers Jun 16, 2008 3:51:06 PM

Well, it would turn turn display_errors On and it would set your error_reporting to 2047 which is all errors except recoverable. So if that's what you meant by 'fix it' then yes, i guess it would.

You might need to clarify, however.

Bleakers Jun 19, 2008 8:51:48 AM

I'm new to php and I am reading PHP 5 for Dummies, I'm at chapter 3 creating you first PHP script. The script I'm using is
<head><title>Hello World Script</title></head>
echo “<p>Hello World!</p>”
I saved it as helloworld.php on my localhost and even on my web server and I keep getting the same message:
Parse error: syntax error, unexpected '>' in C:\wamp\www\Test\helloworld.php on line 5
I have no idea whats wrong with it as I have just copied and pasted from the ebook!!
Please could someone help as I can't work it out?

Daniel Jun 19, 2008 1:17:22 PM

It appears you're using some sort of curly quotes instead of the regular straight ones. It's probably printed like that in your ebook. Try to type it manually and run it again.

Bleakers Jun 20, 2008 6:40:16 AM

Thank you very much Daniel. That has fix the problem.

akitchin Aug 21, 2008 6:12:02 PM

As an addendum to the section on logic errors, an extremely handy line of code for figuring out what variables have what values (without having to exhaustively echo them) is the following:

exit ('<pre>'.print_r(get_defined_vars(), TRUE));

This will exit the script - you can just as easily use echo. As a warning, it only works within the scope from which it is called (ie. from within functions only the local scope is returned), and from the global scope, you'll get all superglobals as well. This can flood you with data that you don't need - in this case, feel free to trim it down by specifying particular arrays in place of get_defined_vars().

Anggie Jatrasmara Oct 11, 2010 11:27:07 AM

yes, me too
always turn on error message, so we know if something invalid in our code ;)

Anggie Jatrasmara
pulsa murah

Add Comment

Login or register to post a comment.