1.11. Understanding PHP Error Messages

PHP tries to be helpful when problems arise. It provides different types of error messages and warnings with as much information as possible.

1.11.1. Types of PHP error messages

PHP can display five types of messages. Each type of message displays the name of the file where the error was encountered and the line number where PHP encountered the problem. Different error types provide additional information in the error message. The types of messages are

• Parse error: A parse error is a syntax error that PHP finds when it scans the script before executing it.

• Fatal error: PHP has encountered a serious error that stops the execution of the script.

• Warning: PHP sees a problem, but the problem isn't serious enough to prevent the script from running.

• Notice: PHP sees a condition that might be an error or might be perfectly okay.

• Strict: Strict messages, added in PHP 5, warn about coding standards. You get strict messages when you use language that is poor coding practice or has been replaced by better code.

We recommend writing your PHP scripts with an editor that uses line numbers. If your editor doesn't let you specify which line you want to go to, you have to count the lines manually from the top of the file every time that you receive an error message. You can find information about many editors, including descriptions and reviews, at www.php-editors.com.

1.11.1.1. Understanding parse errors

Before starting to run a script, PHP scans the script for syntax errors. When it encounters an error, it displays a parse error message. A parse error is a fatal error, preventing the script from even starting to run. A parse error looks similar to the following:

Parse error:  parse error, error , in c:	est.php on line 6

Often, you receive this error message because you've forgotten a semicolon, a parenthesis, or a curly brace. The error displayed provides as much information as possible. For instance, the following might be displayed:

Parse error: parse error, unexpected T_ECHO, expecting ',' or ';', in c:	est.php on line 6

This error means that PHP found an echo statement where it was expecting a comma or a semicolon, which probably means you forgot the semicolon at the end of the previous line.

T_ECHO is a token. Tokens represent various parts of the PHP language. Some, like T_ECHO or T_IF, are fairly clear. Others are more obscure. See the appendix of tokens in the PHP online manual (www.php.net/manual/en/tokens.php) for a list of parser tokens with their meanings.

1.11.1.2. Understanding fatal errors

A fatal error message is displayed when PHP encounters a serious error during the execution of the script that prevents the script from continuing to execute. The script stops running and displays a message that contains as much information as possible to help you identify the problem.

One problem that produces a fatal error message is calling a function that doesn't exist. (Functions are explained in Chapter 2 in this minibook.) If you misspell a function name in your PHP script, you see a fatal error message similar to the following:

Fatal error: Call to undefined function xxx() in C:Program FilesApache GroupApache2htdocsPHPandMySQLinfo.php on line 10

In this case, PHP can't find a function named xxx that you call on line 10.

We use the term fatal errors to differentiate this type of errors from other errors. However, PHP just calls them (confusingly) errors. You won't find the term fatal error in the manual. Also, the keyword needed to display these types of errors is E_ERROR. (We cover this later in the chapter in the "Displaying selected messages" section.)

1.11.1.3. Understanding warnings

A warning message displays when the script encounters a problem but the problem isn't serious enough to prevent the script from running. Warning messages don't mean that the script can't run; the script does continue to run. Rather, warning messages tell you that PHP believes that something is probably wrong. You should identify the source of the warning and then decide whether it needs to be fixed. It usually does.

If you attempt to connect to a MySQL database with an invalid username or password, you see the following warning message:

Warning: mysql_connect() [function.mysql-connect]: Access denied for user 'root'@'localhost' (using password: YES) in C:Program FilesApache GroupApache2htdocs	est.php on line 9

The attempt to connect to the database failed, but the script doesn't stop running. It continues to execute additional PHP statements in the script. However, because the later statement probably depends on the database connection being established, the later statements won't execute correctly. This statement needs to be corrected. Most statements that produce warning messages need to be fixed.

1.11.1.4. Understanding notices

A notice is displayed when PHP sees a condition that might be an error or might be perfectly okay. Notices, like warnings, don't cause the script to stop running. Notices are much less likely than warnings to indicate serious problems. Notices just tell you that you're doing something unusual and to take a second look at what you're doing to be sure that you really want to do it.

One common reason why you might receive a notice is that you're echoing variables that don't exist. Here's an example of what you might see in that instance:

Notice:Undefined variable: age in testing.php on line 9

1.11.1.5. Understanding strict messages

Strict messages warn about coding standards. They point out language that's poor coding practice or has been replaced by better code. The strict error type was added in PHP 5. Strict messages don't stop the execution of the script. However, changing your code so that you don't see any strict messages makes the script more reliable for the future. Some of the language highlighted by strict messages might be removed entirely in the future.

Some of the strict messages refer to PHP language features that have been deprecated. Deprecated functions are old functions that have been replaced by newer functions. The deprecated functions are still supported, but will be removed in the future. PHP might add a separate error type E_DEPRECATED to identify these types of errors so that both E_STRICT and E_DEPRECATED messages will identify different types of problems.

1.11.2. Displaying error messages

You can handle error messages in any of the following ways:

• Display some or all error messages on your Web pages.

• Don't display any error messages.

• Suppress a single error message.

You can tell PHP whether to display error messages or which error messages to display with settings in the php.ini file or with PHP statements in your scripts. Settings in php.ini set error handling for all your scripts. Statements in a script set error handling for that script only.

1.11.2.1. Turning off error messages

Error messages are displayed on your Web pages by default. Displaying error messages on your Web pages is a security risk. You can have error messages turned on when you're developing your Web site, so you can fix the errors, but when your Web pages are finished and ready for the public to view, you can shut off the error messages.

You can turn off all error messages for all scripts in your Web site in the php.ini file. Find the following setting:

display_errors = On

Change On to Off.

You can turn off errors in an individual script with the following statements:

ini_set("display_errors","off");

Changing the setting doesn't change the error in any way; it changes only whether the error message is displayed. A fatal error still stops the script; it just doesn't display a message on the Web page.

One way to handle error messages is to turn them off in php.ini and turn them on in each individual script during development. Then, when the Web site is ready for public viewing, you can remove the ini_set statements that turn on the error messages.

1.11.2.2. Displaying selected messages

You can specify which type of error messages you want to display with the following setting in php.ini:

error_reporting  =

You use one of several codes to tell PHP which messages to display. Some possible settings are

error_reporting = E_ALL | E_STRICT
error_reporting = 0
error_reporting = E_ALL & ~ E_NOTICE

The first setting displays E_ALL, which is all errors, warnings, and notices except stricts; and E_STRICT, which displays strict messages. The second setting displays no error messages. The third setting displays all error messages except stricts and notices, because the & ~ means "and not."

Other codes that you can use are E_WARNING, which means all warnings, and E_ERROR, which means all fatal runtime errors.

You can also set the type of message to display for an individual script. You can add a statement to a script that sets the error reporting level for that script only. Add the following statement at the beginning of the script:

error_reporting(errorSetting);

For example, to see all errors except stricts, use the following:

error_reporting(E_ALL);

1.11.2.3. Suppressing a single error message

You can stop the display of a single error message in a PHP statement. In general, this isn't a good idea. You want to see your error messages and fix the problems. However, occasionally, suppressing a single notice is the simplest method to prevent an unsightly message from displaying on the Web page.

You can stop the display of an error message by placing an at sign (@) where you expect the error message to be generated. For example, the @ in the following statement suppresses an error message:

echo @$news1;

If the variable $news1 hasn't been set previously, this statement would produce the following notice:

Notice: Undefined variable: news1 in C:Program FilesApache GroupApache2htdocsPHPandMySQLinfo.php on line 10

However, the @ in front of the variable name keeps the notice from being displayed. This feature should be used rarely, but it can be useful in a few situations.

1.11.3. Logging error messages

You can store error messages in a log file. This produces a permanent record of the errors, whether or not they displayed on the Web page. Logging messages requires two settings:

• log_errors: Set this to on or off to send errors to a log file.

• error_log: Specify the filename where errors are to be logged.

1.11.3.1. Logging errors

You can tell PHP to log errors with a setting in php.ini. Find the following setting:

log_errors = Off

Change the setting to On. After you save the changed php.ini file and restart your Web server, PHP logs errors to a text file. You can tell PHP where to send the errors with the error_log setting described in the next section. If you don't specify a file with the error_log settings, the error messages are written to the Apache error log, located in the logs subdirectory in the directory where Apache is installed. The error log has the .err file extension.

You can log errors for an individual script by including the following statement at the beginning of the script:

ini_set("log_errors","On");

This statement sets error logging for this script only.

1.11.3.2. Specifying the log file

You specify the file where PHP logs error messages with a setting in php.ini. Find the setting:

;error_log = filename

Remove the semicolon from the beginning of the line. Replace filename with the path/filename of the file where you want PHP to log error messages, such as:

error_log = "c:phplogserrs.log"

The file you specify doesn't need to exist. If it doesn't exist, PHP will create it.

After you save the edited php.ini file and restart your Web server, error messages are logged in the specified file. Each error message is logged on a separate line, with the date and time at the beginning of the line.

You can specify a log file for an individual script by including the following statement at the beginning of the script:

ini_set("error_log"," c:phplogserrs.log ");

This statement sets the log file for this script only.