Difference between revisions of "Error Management"

Revision as of 17:08, 13 August 2021

The WHMCS application will suppress all non-critical warnings and notices and attempt to complete all requested actions in its default configuration. If an error condition is critical in nature and the continued execution of a requested action is either detrimental or not possible, the system will display a friendly, styled error page and log the event. This aligns with the behavior of most public-facing, production websites and is usually optimal for your WHMCS deployment.

However, WHMCS can't support environments and error conditions with a "one size fits all" approach. Due to this, WHMCS provides several methods that enable you to define your error options in a way that best addresses your production and debugging needs.

Prior to version 7.2.0, only the Display Errors and SQL Debug Mode options are available as documented in this article. Any error condition would result in a blank or partially loaded page unless you enabled Display Errors. This would render the undecorated error stacktrace when possible.

Customizing The Error Page

System Themes

Client Area System Themes
We introduced Twenty-One in WHMCS 8.1. We plan to remove Six in a future version.

The Twenty-One and Six system themes provide a system theme template at errors/internal-error.tpl. You can modify this within your own system theme. If this file is not present in your default system theme, use a stock copy of it. To help reduce any further possible error paths, Smarty doesn't process this file.

You cannot alter the dynamic content of this file. However, your customized file can alter the placement, provide its own hardcoded alternative, or exclude this dynamic content.

css — Any CSS content. By default, this is in the HTML head tag.
title — The document title. By default, this is in the title tag of the head tag, as well as within an h1 tag of the default body.
systemurl — The configured System URL at Configuration () > System Settings > General Settings in the General tab.
email — The configured default email address at Configuration () > System Settings > General Settings in the General tab.
stacktrace — The PHP stacktrace of the error condition. The system only populates this information if Display Errors is enabled via configuration file or at Configuration () > System Settings > General Settings in the Other tab.

If the system encounters an error condition very early, before WHMCS has the opportunity to initialize, the system renders a rudimentary but HTML friendly body. If this is not possible due to the timing of the error, the system will use the web server environment settings (which may be informative but are not likely to be stylized or friendly).

Controlling How Errors Are Managed

Error Reporting and Display

WHMCS provides two levels of control to affect errors and their management. However, you should consider three levels of control:

Environment Error Control

The lowest level control is the environment level. WHMCS cannot manipulate this level. The control options and methods to use to modify them are specific to your web server environment. Usually, ini settings control these and the PHP binary that Apache uses consume them. While WHMCS cannot alter these environment settings, by the very nature of being a web application, it must utilize them while reading the first few code directives.

Unless there is a very rudimentary issue with the environment or access to files that WHMCS uses, there should be no need to leverage this level of control. Our default recommendation for production environments is to set the display_errors and error_reporting directives to 0. You can read more about what your options are and their appropriate usage in the PHP Manual.

Configuration File Control

The system reads the configuration file (configuration.php in the application's deployment directory) very early. The file allows you to specify two options via variables:

$display_errors — This will control whether details about the error will be present in the friendly error page. A value of 1 or true (a numeric or boolean value, respectively) will enable this behavior while a value of 0 or false (a numeric or boolean value, respectively) will disable this behavior. We recommend that you do not define this variable and leave this option in an implicitly disabled state for production, since it may lead to information disclosure.
$error_reporting_level — This will control the sensitivity of observed PHP errors, warnings, and notices. You must set this to a numeric value (usually a combination of PHP constants, as a bitmask value). We recommend that you do not define this variable and allow the application to implicitly set a production-appropriate value.

Special Note About Error Reporting Level

We recommend that you do _not_ change the $error_reporting_level within configuration.php or the corresponding PHP ini error_reporting directive at the environment level, during normal production or staging operation.

Specifying a more sensitive $error_reporting_level, which observes non-critical warnings and notices, may result in premature exits and prevent normal production behavior.

General Settings Control

Display Errors — This will control whether details about the error will be present in the friendly error page. This value takes precedence over the respective setting ($display_errors) in the configuration file. You can find the Display Errors option in the Settings >> General Settings >> Other tab of the admin area.

Controlling Logging

WHMCS will always attempt to log errors that result in an error page. These may include uncaught exceptions or PHP errors, warnings, and notices that you observe due to the effective error reporting level. The location of the log entry may vary based on the time of the error and any configured logging options.

WHMCS Activity Log

If you wish for WHMCS to attempt to record uncaught exceptions or observed PHP errors, warnings, and notices to the Activity Log, then you can enable Log Errors in the Settings >> General Settings >> Other tab.

Logging to the Activity Log will require a full initialization of the WHMCS core with an active connection to the database. If the error condition occurs prior to meeting these prerequisites, then the error will only propagate to the Environment Log.

There is a separate toggle available for MySQL® query error and warning conditions. You can enable SQL Debug Mode in the Settings >> General Settings >> Other tab. This setting has the same prerequisites and behavior pattern as Log Errors setting.

Environment Log

As part of the initialization process, the system registers an error log handler to the web server environment error log. The system provides this logging channel to ensure error traceability, regardless of your effective Log Errors setting. The system defines the environment error log destination target at the environment level and WHMCS doesn't control it. Typically, this is the Apache error log, but may be different in your environment. WHMCS will always attempt to log the observed errors and uncaught exceptions to this log if possible. If the error condition happens before WHMCS can register its error log handler, then the system uses the web server environment settings.

PHP Errors vs. Exceptions

PHP has the concept of "errors" and "exceptions." PHP Errors are classified by type and their importance varies for critical to simply informative. PHP Exceptions, while diverse in nature, are a signal to stop the current routing and return control to the previous invocation so that the system can use an appropriate, alternative code.

Example error types range from the insensitive E_ERROR and E_PARSE (which mean there is a critical problem interpreting the code) to hyper-sensitive E_STRICT (which mean there's a code instruction that may trigger ancillary contexts that the developer should note for cross-compatibility against PHP versions or incorporated libraries, but there is not an "error"). Depending on the error type, it may be possible to suppress the error and continue the current code path. For critical errors, such as E_ERROR and E_PARSE, it is not possible continue the current code path since it explicitly represents a non-functional code and there is no viable alternative path available.

Ideally, all code that emits an exception will have surrounding code which can observe the exceptional condition and take a valid, user-friendly path. If this is not possible, then PHP will continue to revert control, all the way back to the originally-called script. If the original script cannot observe the exception, it becomes an "uncaught exception" and will behave like a critical error.

If the system invokes an uncaught exception or "error" condition (based on the error reporting level), PHP will attempt to execute any registered "handlers" that PHP defined before the condition occurred. The "handlers" provide a last minute opportunity to affect how to report the condition; it does not have the power to mitigate the condition or revert to an alternative code path. WHMCS registers various error and exception handlers as soon as possible so that if such a condition occurs, there's a final opportunity to output a friendly message. If the condition happens before WHMCS has the opportunity to register its handlers, such as missing or corrupt core files or an invalid environment, the result will be the behavior that the webserver defines (for example, PHP ini and Apache settings).