phpmaster | Error Handling in PHP

Errors are the most common event a developer faces when programming. Errors can be categorized as syntactical, run-time, or logical: missing the semicolon at the end of a statement is an example of a syntax error; trying to connect to a database when the server is down is an example of a run-time error; providing incorrect data to a variable is an example of a logic error. To help reduce the number of errors in your code, and to mitigate their effects, proper error handling is essential in your web application. This article is a crash course in PHP error handling. You’ll learn about PHP’s built-in error reporting levels, and how to handle errors with custom error handlers and exception handling.

Key Takeaways

• PHP error handling is crucial for maintaining the integrity and functionality of a web application. It helps identify and fix issues that may arise during script execution, improving user experience by controlling what they see when an error occurs.
• PHP offers several built-in functions for error handling, including logging and displaying them. It also provides flexibility to customize error handling strategies by registering error handlers and using exceptions.
• Custom error handling in PHP can be achieved using set_error_handler() and set_exception_handler() functions. These allow developers to define custom error handling rules and exceptions, which can be useful for logging errors or sending error notifications.
• Exceptions in PHP are events that occur during script execution, disrupting the normal flow of instructions. They can be handled using try, catch, and finally blocks. If no catch block is found when an exception is thrown, PHP will display a fatal error and stop executing the script.

PHP Error Reporting Levels

All errors and warnings should be logged. Based on the severity of an error, notifications should be sent out to other systems/teams. So that you can better gauge its severity, PHP provides several built-in error levels to describe the nature of an error. Each level is represented by an integer value and named constant which can be used by the programmer. The table below is taken from the official PHP documentation and shows some of the different levels.

The levels can be masked together with bit-operators to include or subtract them from PHP’s configuration. For example, E_ALL|E_STRICT enables all errors and warnings with the addition of E_STRICT (necessary in versions of PHP prior to 5.4). PHP provides a few configuration directives related to logging and displaying errors. Their values are generally different depending on whether the system is in a development or a production environment. This table shows some of the error-related directives.

The configuration directives can be set either in php.ini, in a web server configuration file (httpd.conf or .htaccess file), or at run-time in your script using the ini_set() function. Read the documentation for more information on the directives and how/where to set them.

Creating Custom Error Handlers

It’s also good practice not to display raw errors to the end user. Errors that are displayed should be abstracted with friendly, custom error messages. PHP not only provides built-in functions for logging and displaying errors, but also for raising them. You can pragmatically trigger an error of a specific level using trigger_error(). For example, this code triggers an E_USER_NOTICE warning if the value of $test is greater than 1:

<span><span><?php
</span></span><span><span>$test = 5;
</span></span><span><span>if ($test > 1) {
</span></span><span>    <span>trigger_error('Value of $test must be 1 or less', E_USER_NOTICE);
</span></span><span><span>}</span></span>

Triggering errors with trigger_error() is useful when you have an error-handling infrastructure in place, allowing you to unify the handling of both custom errors and the errors and warnings raised by PHP. If you want to implement customized error handling strategies like sending an email or logging errors to a database based on their severity, then you’ll need to define custom error handlers using set_error_handler(). The function accepts two arguments: a callback function or static method that will be invoked when the error is raised, and optionally the error level the function/method handles. The signature of the callback is:

handler(int $errno, string $errstr, string $errfile, int $errline, array $errcontext)

Let’s take a look at a custom error handler function. The example below records errors to a database table database whenever one is encountered:

<span><span><?php
</span></span><span><span>$test = 5;
</span></span><span><span>if ($test > 1) {
</span></span><span>    <span>trigger_error('Value of $test must be 1 or less', E_USER_NOTICE);
</span></span><span><span>}</span></span>

The above snippet registers an error handler that does the following: when non-fatal errors occur, a record will be inserted into database instead of displaying the error and logging it to a file; When a fatal error occurs, it will be logged in database and terminate your script. There are some limitations to custom error handlers you should be aware of, however. The error handler bypasses PHP’s standard error handling behavior, so it can’t handle errors that may arise within your handler itself. In the event the database server is down, for example, the above function would fail to record the log. Also, the error handler is not able to catch certain internal errors, like E_CORE_ERROR and E_COMPILE_ERROR, or E_STRICT errors in the same file the handler is defined in since those errors occur before the handler has a chance to be registered.

Handling Errors using Exceptions

However good of an error handling framework you have in place, there will always be problems at run-time. Of course you don’t want these errors to show up in the user’s browser. This is where exception handling enters the picture. Exceptions allows you to handle errors and exceptional situations gracefully. Exceptions are represented in PHP by the class Excpetion (or any of its subclasses). They can be raised using throw and can be caught using a try/catch block. You can extend Exception to create custom exception types for trapping specific errors. The code that may trigger an exception is placed within the try block, and the code to handle the exception is placed within the catch block. Consider the following snippet:

handler(int $errno, string $errstr, string $errfile, int $errline, array $errcontext)

If an exception is thrown by the fictitious getDataFromService() method, it will be caught in the catch block and a message will be displayed. If getDataFromService() executes successfully then the flow will pass over the catch block and continue through the rest of the script. Any exceptions that are thrown and not caught will generate an E_FATAL error with the message “Uncaught Exception.” The Exception class offers six different methods to access information about what caused the problem, as shown in the table below.

Creating a Custom Exception Handler

PHP will let you throw any object as if it were an exception, but as a rule of thumb the exception should extend PHP’s built-in Exception class. Based on the object’s type, you can handle the exceptions differently. Custom exception handling can perform suitable actions like logging error messages in file, providing exact details about the line on which the error occurred by examining the calling stack, etc.  Have a look at this example:

<span><span><?php
</span></span><span><span>$test = 5;
</span></span><span><span>if ($test > 1) {
</span></span><span>    <span>trigger_error('Value of $test must be 1 or less', E_USER_NOTICE);
</span></span><span><span>}</span></span>

The code above defines two new custom exception types, NameException and EmailException, which can be used to indicate different errors. Then within the try block, the code checks if values have been supplied for the variables $name and $email. If either is empty, then the appropriate exception is thrown using throw. The corresponding catch block is executed which handles the error.

Re-throwing Exceptions

try/catch blocks can be nested. Sometimes you’ll want to catch an exception, look at some of its properties, and then throw it again to let a parent catch block handle it. This can often be useful to check an error condition and decide whether it should be fatal or not. This example code demonstrates re-throwing an exception:

handler(int $errno, string $errstr, string $errfile, int $errline, array $errcontext)

Uncaught Exception Handler

Similar to how set_error_handler() allows you specify a function to handle run-time errors, the set_exception_handler() function allows you to handle exceptions that make it all the way up the call stack without being caught by any catch blocks. For example, if an exception makes it all the way up your stack, it would be a good idea to log it in a log file. You can create a callback function and register it  with set_exception_handler() as shown in the example below.

<span><span><?php
</span></span><span><span>function errorHandler($errno, $errstr, $errfile, $errline) {
</span></span><span>    <span>static $db;
</span></span><span>    <span>if (empty($db)) {
</span></span><span>        <span>$db = new PDO(DSN, DBUSER, DBPASS);
</span></span><span>    <span>}
</span></span><span>
</span><span>    <span>$query = "INSERT INTO errorlog (severity, message, filename, lineno, time) VALUES (?, ?, ?, ?, NOW())";
</span></span><span>    <span>$stmt = $db->prepare($query);
</span></span><span>
</span><span>    <span>switch ($errno) {
</span></span><span>        <span>case E_NOTICE:
</span></span><span>        <span>case E_USER_NOTICE:
</span></span><span>        <span>case E_DEPRECATED:
</span></span><span>        <span>case E_USER_DEPRECATED:
</span></span><span>        <span>case E_STRICT:
</span></span><span>            <span>$stmt->execute(array("NOTICE", $errstr, $errfile, $errline));
</span></span><span>            <span>break;
</span></span><span>
</span><span>        <span>case E_WARNING:
</span></span><span>        <span>case E_USER_WARNING:
</span></span><span>            <span>$stmt->execute(array("WARNING", $errstr, $errfile, $errline));
</span></span><span>            <span>break;
</span></span><span>
</span><span>        <span>case E_ERROR:
</span></span><span>        <span>case E_USER_ERROR:
</span></span><span>            <span>$stmt->execute(array("FATAL", $errstr, $errfile, $errline));
</span></span><span>            <span>exit("FATAL error <span><span>$errstr</span> at <span>$errfile</span>:<span>$errline</span>"</span>);
</span></span><span>
</span><span>        <span>default:
</span></span><span>            <span>exit("Unknown error at <span><span>$errfile</span>:<span>$errline</span>"</span>);
</span></span><span>    <span>}
</span></span><span><span>}
</span></span><span>
</span><span><span>set_error_handler("errorHandler");
</span></span><span>
</span><span><span>$test = 5;
</span></span><span><span>if ($test > 1) {
</span></span><span>   <span>trigger_error("Value of <span><span>$test</span> must be 1 or less"</span>, E_USER_NOTICE);
</span></span><span><span>}</span></span>

Summary

PHP offers variety of built-in functions for handling error conditions, including logging and displaying them. It also provides you the flexibility to customize your error handling strategies by registering error handlers and using exceptions. Errors are a fact of life, but hopefully the information I presented in this article will help you handle them more gracefully. Image via Ilya Andriyanov / Shutterstock

Frequently Asked Questions (FAQs) about Error Handling in PHP

What is the importance of error handling in PHP?

Error handling in PHP is crucial for maintaining the integrity and functionality of a web application. It helps developers identify and fix issues that may arise during the execution of a script. Without proper error handling, a minor issue can cause significant problems, such as crashing the application or exposing sensitive information to users. It also improves the user experience as it allows developers to control what the user sees when an error occurs, rather than displaying confusing error messages.

How does PHP handle errors by default?

By default, PHP sends an error report to the server’s error log and displays an error message on the screen. This behavior is not ideal for a live website because it can reveal sensitive information to the user. Therefore, it’s recommended to change the default error handling settings for a live website.

What are the different types of errors in PHP?

PHP classifies errors into several types, including fatal errors, warnings, parse errors, and notices. Fatal errors are critical errors, such as calling a non-existent function or writing to a file that isn’t writable. Warnings are non-fatal errors that allow the script to continue running. Parse errors occur when there’s a syntax mistake in the script. Notices are minor errors or possible errors that PHP encounters while executing a script.

How can I customize error handling in PHP?

PHP provides several functions to customize error handling, such as set_error_handler() and set_exception_handler(). These functions allow you to define custom error handling rules and exceptions. You can specify a custom function to handle errors, which can be useful for logging errors or sending error notifications.

What is an exception in PHP?

An exception is an event that occurs during the execution of a script that disrupts the normal flow of the script’s instructions. When an exception is thrown, PHP will stop executing the script and start looking for a catch block to handle the exception. If no catch block is found, PHP will display a fatal error and stop executing the script.

How can I handle exceptions in PHP?

PHP provides the try, catch, and finally blocks to handle exceptions. The try block contains the code that may throw an exception. The catch block contains the code to handle the exception. The finally block contains the code that will be executed regardless of whether an exception was thrown or not.

What is the difference between errors and exceptions in PHP?

The main difference between errors and exceptions in PHP is how they are handled. Errors are handled by the PHP engine and can be controlled using error reporting settings and custom error handlers. Exceptions, on the other hand, are handled by the script and can be controlled using try, catch, and finally blocks.

How can I turn off error reporting in PHP?

You can turn off error reporting in PHP by using the error_reporting() function with 0 as its argument. However, turning off error reporting is not recommended for a live website because it can make it difficult to identify and fix issues.

What is the role of the @ operator in PHP error handling?

The @ operator in PHP is used to suppress error messages. When prepended to an expression in PHP, any error messages that might be generated by that expression will be ignored.

How can I log errors in PHP?

PHP provides the error_log() function to send an error message to the server’s error log or to a specified file. This function can be useful for keeping track of errors and debugging. You can also configure PHP to log all errors by changing the log_errors directive in the php.ini file.

The above is the detailed content of phpmaster | Error Handling in PHP. For more information, please follow other related articles on the PHP Chinese website!