Latest revision as of 20:16, 23 November 2022

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.

Customizing The Error Page

System Themes

The Twenty-One and Six system themes use system theme error templates in the following locations:

• errors/internal-error.tpl
• errors/page-not-found.tpl
• errors/unknown-routepath.tpl

If you create a custom theme, you can customize these pages by creating these files in your theme's directory (for example, /templates/example/error/internal-error.tpl, where example is the directory for your custom theme).

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. To help reduce any further possible error paths, Smarty doesn't process this file.

Error Template Variables

These files can use the following variables:

• css — Any CSS content. By default, this is in the HTML head tag.
• email — The configured default email address in the General tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings.
• stacktrace — The PHP stacktrace of the error condition. The system only populates this information if Display Errors is enabled via the configuration file or in the Other tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings.
• systemurl — The configured System URL setting in the General tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings.
• 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.

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.

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 Display Errors in the Other tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings.

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 Other tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings.

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 Other tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings. This setting has the same prerequisites and behavior pattern as Log Errors.

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).