Error Logging and Handling Exceptions

Error Logging

If you’ve decided to log your errors to a separate text file, the Web server process owner must have adequate permissions to write to this file. In addition, be sure to place this file outside of the document root to lessen the likelihood that an attacker could happen across it and potentially uncover some information that is useful for surreptitiously entering your server. When you write to the syslog, the error messages look like this:

Dec 5 10:56:37 example.com httpd: PHP Warning:
fopen(/home/www/htdocs/subscribers.txt): failed to open stream: Permission
denied in /home/www/htdocs/book/8/displayerrors.php on line 3

When you write to a separate text file, the error messages look like this:

[05-Dec-2005 10:53:47] PHP Warning:
fopen(/home/www/htdocs/subscribers.txt): failed to open stream: Permission
denied in /home/www/htdocs/book/8/displayerrors.php on line 3

As to which one to use, that is a decision that you should make on a per-environment basis. If your Web site is running on a shared server, then using a separate text file or database table is probably your only solution. If you control the server, then using the syslog may be ideal, because you’d be able to take advantage of a syslog-parsing utility to review and analyze the logs. Take care to examine both routes and choose the strategy that best fits the configuration of your server environment.

PHP enables you to send custom messages as well as general error output to the system syslog. Four functions facilitate this feature. These functions are introduced in this section, followed by a concluding example.

define_syslog_variables()

void define_syslog_variables(void)

Thedefine_syslog_variables()function initializes the constants necessary for using theopenlog(),closelog(), andsyslog()functions. You need to execute this function before using any of the following logging functions.

openlog()

int openlog(string ident, int option, int facility)

Theopenlog()function opens a connection to the platform’s system logger and sets the stage for the insertion of one or more messages into the system log by designating several parameters that will be used within the log context:

• ident: A message identifier added to the beginning of each entry. Typically this value is set to the name of the program. Therefore, you might want to identify PHP-related messages as “PHP” or “PHP5”.
  
• option: Determines which logging options are used when generating the message. A list of available options is offered in Table 8-2. If more than one option is required, separate each option with a vertical bar. For example, you could specify three of the options like so:LOG_ODELAY | LOG_PERROR | LOG_PID.
  
• facility: Helps determine what category of program is logging the message. There are several categories, includingLOG_KERN,LOG_USER,LOG_MAIL,LOG_DAEMON,LOG_AUTH,LOG_LPR, andLOG_LOCALN, whereNis a value ranging between 0 and 7. Note that the designated facility determines the message destination. For example, designatingLOG_CRONresults in the submission of subsequent messages to thecronlog, whereas designatingLOG_USERresults in the transmission of messages to themessagesfile. Unless PHP is being used as a command-line interpreter, you’ll likely want to set this toLOG_USER. It’s common to useLOG_CRONwhen executing PHP scripts from acrontab. See the syslog documentation for more information about this matter.

closelog()

int closelog(void)

Thecloselog()function closes the connection opened byopenlog().

syslog()

int syslog(int priority, string message)

Thesyslog()function is responsible for sending a custom message to the syslog. The first parameter,priority, specifies the syslog priority level, presented in order of severity here:

1. LOG_EMERG: A serious system problem, likely signaling a crash
   
2. LOG_ALERT: A condition that must be immediately resolved to avert jeopardizing system integrity
   
3. LOG_CRIT: A critical error, which could render a service unusable but does not necessarily place the system in danger
   
4. LOG_ERR: A general error
   
5. LOG_WARNING: A general warning
   
6. LOG_NOTICE: A normal but notable condition
   
7. LOG_INFO: General informational message
   
8. LOG_DEBUG: Information that is typically only relevant when debugging an application

The second parameter,message, specifies the text of the message that you’d like to log. If you’d like to log the error message as provided by the PHP engine, you can include the string%min the message. This string will be replaced by the error message string (strerror) as offered by the engine at execution time.

Now that you’ve been acquainted with the relevant functions, here’s an example:

<?php
define_syslog_variables();
openlog("CHP8", LOG_PID, LOG_USER);
syslog(LOG_WARNING,"Chapter 8 example warning.");
closelog();
?>

This snippet would produce a log entry in themessages syslog file similar to the following:

--------------------------------------------Dec 5 20:09:29 CHP8[30326]: Chapter 8 example warning.
--------------------------------------------

Next: Exception Handling >>
 

More Programming Basics Articles
More By Apress Publishing