Error Management - Revision history

SarahK: /* System Themes */

2022-11-23T20:16:36Z

‎System Themes

SarahK at 20:15, 11 May 2022

2022-05-11T20:15:31Z

SarahK at 18:52, 22 April 2022

2022-04-22T18:52:42Z

John: /* Controlling Error Management */ Controlling How Errors Are Managed heading must exist, it's referenced in the product

2021-08-13T17:08:50Z

‎Controlling Error Management: Controlling How Errors Are Managed heading must exist, it's referenced in the product

SarahK: /* Customizing The Error Page */

2020-11-20T22:04:52Z

‎Customizing The Error Page

SarahK: /* Environment Error Control */

2020-11-11T17:12:52Z

‎Environment Error Control

SarahK at 19:24, 29 April 2020

2020-04-29T19:24:27Z

Show changes

David at 19:01, 12 May 2017

2017-05-12T19:01:46Z

David at 19:01, 12 May 2017

2017-05-12T19:01:12Z

David at 16:13, 12 May 2017

2017-05-12T16:13:53Z

@@ Line 16: / Line 16: @@
 </div>
-The Twenty-One and Six system themes provide a system theme template at <tt>errors/internal-error.tpl</tt>. 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.
+The Twenty-One and Six system themes use system theme error templates in the following locations:
-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.
+* <tt>errors/internal-error.tpl</tt>
 * <tt>css</tt> — Any CSS content. By default, this is in the HTML <tt>head</tt> tag.
 * <tt>title</tt> — The document title. By default, this is in the <tt>title</tt> tag of the <tt>head</tt> tag, as well as within an <tt>h1</tt> tag of the default body.
 <div class="docs-alert-info">
-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).
+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.
 </div>

@@ Line 67: / Line 67: @@
 ====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|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
+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|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > 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.

@@ Line 4: / Line 4: @@
 <div class="docs-alert-info">
-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.
+Prior to WHMCS 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.
 </div>
@@ Line 22: / Line 22: @@
 * <tt>css</tt> — Any CSS content. By default, this is in the HTML <tt>head</tt> tag.
 * <tt>title</tt> — The document title. By default, this is in the <tt>title</tt> tag of the <tt>head</tt> tag, as well as within an <tt>h1</tt> tag of the default body.
-* <tt>systemurl</tt> — The configured '''System URL''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' in the '''General''' tab.
+* <tt>systemurl</tt> — The configured '''System URL''' in the '''[[General Tab|General]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
-* <tt>email</tt> — The configured default email address at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' in the '''General''' tab.
+* <tt>email</tt> — The configured default email address in the '''[[General Tab|General]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
-* <tt>stacktrace</tt> — The PHP stacktrace of the error condition. The system only populates this information if '''Display Errors''' is enabled via configuration file or at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' in the '''Other''' tab.
+* <tt>stacktrace</tt> — The PHP stacktrace of the error condition. The system only populates this information if '''Display Errors''' is enabled via configuration file or in the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
 <div class="docs-alert-info">
@@ Line 59: / Line 59: @@
 ====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.
+* 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|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
 ===Controlling Logging===
@@ Line 67: / Line 67: @@
 ====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.
+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|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > 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 ''Settings >> General Settings >> Other'' tab. This setting has the same prerequisites and behavior pattern as Log Errors setting.
+There is a separate toggle available for MySQL® query error and warning conditions.  You can enable '''SQL Debug Mode''' in the '''[[Other Tab|Other]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > 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====

@@ Line 30: / Line 30: @@
 </div>
-==Controlling Error Management==
+==Controlling How Errors Are Managed==
 ===Error Reporting and Display===

@@ Line 9: / Line 9: @@
 ==Customizing The Error Page==
-===Template===
+===System Themes===
-The Six theme provides a template in ''errors/internal-error.tpl''. You can modify this template within your own theme. If this file is not present in your default theme, use an internal copy of it.  Smarty doesn't process this template to help reduce any further possible error paths.
+<div class="docs-alert-warning">
-You cannot alter the dynamic content of this template. However, your customized template may choose to either alter the placement, provide its own hardcoded alternative, or exclude this dynamic content.
+The Twenty-One and Six system themes provide a system theme template at <tt>errors/internal-error.tpl</tt>. 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.
-* ''css'' — Any CSS content. By default, this is in the HTML "head" tag.
+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.
-* ''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 in ''Settings >> General Settings >> General'' tab.
+* <tt>css</tt> — Any CSS content. By default, this is in the HTML <tt>head</tt> tag.
-* ''email'' — The configured default email address in ''Settings >> General Settings >> General'' tab.
+* <tt>title</tt> — The document title. By default, this is in the <tt>title</tt> tag of the <tt>head</tt> tag, as well as within an <tt>h1</tt> tag of the default body.
-* ''stacktrace'' - The PHP stacktrace of the error condition. The system only populates this information if Display Errors is enabled via configuration file or in ''Settings >> General Settings >> Other'' tab.
+* <tt>systemurl</tt> — The configured '''System URL''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' in the '''General''' tab.
 <div class="docs-alert-info">
-If the system encounters an error condition very early, before WHMCS has the opportunity to initialize, the system renders a more rudimentary, yet still 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 stylized or friendly).
+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).
 </div>

@@ Line 35: / Line 35: @@
 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, <tt>ini</tt> 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 <tt>0</.tt>.  You can read more about what your options are and their appropriate usage in the [http://php.net/manual/en/errorfunc.configuration.php PHP Manual].
+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 <tt>display_errors</tt> and <tt>error_reporting</tt> directives to <tt>0</tt>.  You can read more about what your options are and their appropriate usage in the [http://php.net/manual/en/errorfunc.configuration.php PHP Manual].
 ====Configuration File Control====

← Older revision		Revision as of 19:01, 12 May 2017
Line 2:		Line 2:

	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.		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.
		+
		+	<div class="docs-alert-info">
		+	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 Display Errors was enabled which would render the undecorated error stacktrace.
		+	</div>

	==Customizing The Error Page==		==Customizing The Error Page==

@@ Line 3: / Line 3: @@
 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=
+==Customizing The Error Page==
-==Template==
+===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.
@@ Line 19: / Line 19: @@
 </div>
-=Controlling How Errors Are Managed=
+==Controlling How Errors Are Managed==
-==Error Reporting & Display==
+===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===
+====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 [http://php.net/manual/en/errorfunc.configuration.php PHP Manual]
-===Configuration File Control===
+====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:
@@ Line 34: / Line 34: @@
 * ''$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===
+====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.
 <div class="docs-alert-warning">
@@ Line 40: / Line 40: @@
 </div>
-===General Settings Control===
+====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.  The Display Errors option can be found within ''Settings >> General Settings >> Other'' tab of the admin area.
-==Controlling Logging==
+===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===
+====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.
@@ Line 53: / Line 53: @@
 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===
+====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 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.