Revision as of 12:41, 12 May 2017

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 execute of a requested action is either detrimental or not possible, then a friendly, styled error page will be shown and the event logged.  This aligns with the behavior of most public-facing, production websites and is usually the optimal paradigm for your WHMCS deployment.

However, environments and error conditions cannot be ubiquitously supported with a "one size fits all" approach.  So, 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

Template

The Six theme provides a template in errors/internal-error.tpl.  You may modify this template within your own theme.  If this file is not present in your default theme, then an internal copy of it will be used.  This template is not processed by Smarty in order to reduce any further possible error paths.  

The dynamic content of this template cannot be altered. However, your customized template may choose to either alter the placement, or provide its own hardcoded alternative, or simply exclude this dynamic content. 

• css - any CSS content.  By default to be placed within the HTML "head" tag.
• title - the document title.  By default, this is used in within the "title" tag of the "head" tag as well as within an "h1" tag of the default body.
• systemurl - the configured System URL defined in Settings >> General Settings >> General tab
• email - the configured default email address defined in Settings >> General Settings >> General tab
• stacktrace - the PHP stacktrace of the error condition.  This is only populated if Display Errors is enabled (via configuration file or in Settings >> General Settings >> Other tab)

Controlling How Errors Are Managed

Error Reporting & Display

WHMCS provides two levels of control to affect errors and their management, however there are actually three levels of control that must considered.

Environment Error Control

The lowest level control is the environment level.  This level cannot be manipulated by WHMCS.  The control options and how to modify them will be specific to your webserver environment.  Usually these are controlled by ini settings as consumed by the PHP binary that Apache is using.  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 used by WHMCS, there should be no need to leverage this level of control.  Our default recommendation for production environments is to set both 'display_errors' and 'error_reporting' directives to '0' (number zero, no quotes).  You can read more about what your options are and their appropriate usage in the [PHP Manual](http://php.net/manual/en/errorfunc.configuration.php)

Configuration File Control

The configuration file (configuration.php in the application's deployment directory) is read very early and 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, no quotes) will enable this behavior while a value of "0" or "false" (a numeric or boolean value, respectively, no quotes) will disable this behavior.  It is recommended that you do not defined 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.  This must be set to a numeric value (usually a combination PHP constants represented as a bitmask value).  It is recommended that you do not defined this variable, and allow an production-appropriate value to be implicit set by the application.

Special Note About Error Reporting Level

Specifying a more sensitive $error_reporting_level, which observes non-critical warnings and notices, may result in pre-mature exit and prevent normal production behavior from functioning properly.  We recommend that you do not change the $error_reporting_level, either within configuration.php or via a PHP ini value 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.

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 observed due to the effective error reporting level. The location of the log entry may vary based on when the error condition was triggered as well as any configured logging options that may have been set.

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 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.  SQL Debug Mode can enabled in 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, an error log handler is registered to the webserver environment error log. This logging channel is provided to ensure error traceability, regardless of your effective Log Errors setting.  The environment error log destination target is defined at the environment level and is not controlled by WHMCS.  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 webserver environment settings will be utilized.

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 an appropriate, alternative code can be take if possible.

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 to take affect that the developer should note for cross-compatibility against PHP versions or incorporated libraries, but there is not an "error" per se).  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 represent 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 just like a critical error.

If an uncaught exceptions or "error" condition (as observed based on the error reporting level) is invoked, PHP will attempt to execute any registered "handlers" that were defined before the condition was encountered. The "handlers" simply 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/corrupt core files or invalid environment, the result will be the behavior as defined by the webserver (i.e., PHP ini and Apache settings).