From d59057c4351d6ce20e39a11d120b6a60a6b608ac Mon Sep 17 00:00:00 2001 From: Guy Sartorelli Date: Sun, 5 Jan 2025 17:47:16 +1300 Subject: [PATCH] DOC Update error handling and logging docs --- .../07_Debugging/01_Error_Handling.md | 14 +++++++++++--- en/06_Upgrading/07_Deprecations.md | 4 ++-- en/08_Changelogs/5.4.0.md | 10 ++++++++++ 3 files changed, 23 insertions(+), 5 deletions(-) diff --git a/en/02_Developer_Guides/07_Debugging/01_Error_Handling.md b/en/02_Developer_Guides/07_Debugging/01_Error_Handling.md index 2e69766e8..132aa16ae 100644 --- a/en/02_Developer_Guides/07_Debugging/01_Error_Handling.md +++ b/en/02_Developer_Guides/07_Debugging/01_Error_Handling.md @@ -6,7 +6,7 @@ icon: exclamation-circle # Logging and error handling -Silverstripe CMS uses Monolog for both error handling and logging. It comes with two default configurations: one for +Silverstripe CMS uses Monolog for both error handling (for PHP errors and uncaught exceptions) and logging. It comes with two default configurations: one for logging, and another for core error handling. The core error handling implementation also comes with two default configurations: one for development environments, and another for test or live environments. On development environments, Silverstripe CMS will deal harshly with any warnings or errors: a full call-stack is shown and execution @@ -196,7 +196,15 @@ SilverStripe\Core\Injector\Injector: The `info` argument provides the minimum level to start logging at. -### Disabling the default handler +### Modifying the default error handler + +The default error handler catches uncaught exceptions and PHP errors and displays them in the browser and terminal. + +> [!WARNING] +> In general you should not attach your own error handler to the `Psr\Log\LoggerInterface.errorhandler` error handler service. +> Attaching a your handler to the `Psr\Log\LoggerInterface` service will allow you to handle unchaught exceptions, PHP errors, and manually logged error messages, and is therefore preferred. + +#### Disabling the default error handler You can disable a handler by removing its pushHandlers call from the calls option of the Logger service definition. The handler key of the default handler is `pushDisplayErrorHandler`, so you can disable it like this: @@ -208,7 +216,7 @@ SilverStripe\Core\Injector\Injector: pushDisplayErrorHandler: '%%remove%%' ``` -### Setting a different configuration for dev +#### Setting a different configuration for dev In order to set different logging configuration on different environment types, we rely on the environment-specific configuration features that the config system providers. For example, here we have different configuration for dev and diff --git a/en/06_Upgrading/07_Deprecations.md b/en/06_Upgrading/07_Deprecations.md index 6a2c9e59e..ba41825e1 100644 --- a/en/06_Upgrading/07_Deprecations.md +++ b/en/06_Upgrading/07_Deprecations.md @@ -53,7 +53,7 @@ By default, deprecation warnings will be emitted to the error logger, and will b ### Viewing deprecation warnings in the logs -Deprecation warnings are output to the same error logger as all other warnings and errors. You will need to make sure you have a logging handler attached to the default `Psr\Log\LoggerInterface` or `Psr\Log\LoggerInterface.errorhandler` singletons. For example, to log to a file you can add this to your YAML configuration: +Deprecation warnings are output to the same error logger as all other warnings and errors. You will need to make sure you have a logging handler attached to the default `Psr\Log\LoggerInterface` singleton. For example, to log to a file you can add this to your YAML configuration: ```yml SilverStripe\Core\Injector\Injector: @@ -62,7 +62,7 @@ SilverStripe\Core\Injector\Injector: constructor: - "/var/www/silverstripe.log" - "warning" # warning is the level deprecation warnings are logged as - Psr\Log\LoggerInterface.errorhandler: + Psr\Log\LoggerInterface: calls: ErrorLogFileHandler: [ pushHandler, [ '%$ErrorLogFileHandler' ] ] ``` diff --git a/en/08_Changelogs/5.4.0.md b/en/08_Changelogs/5.4.0.md index fbc0db1f7..ef54b6379 100644 --- a/en/08_Changelogs/5.4.0.md +++ b/en/08_Changelogs/5.4.0.md @@ -261,6 +261,16 @@ The `SilverStripe\CMS\Model\SiteTree.DESCRIPTION` localisation key (along with t This release includes a number of bug fixes to improve a broad range of areas. Check the change logs for full details of these fixes split by module. Thank you to the community members that helped contribute these fixes as part of the release! +### Change to error logging + +Some errors were incorrectly being logged using the error handler service, which resulted in displaying the error in the browser and CLI and, in live mode, not displaying the rest of the response to users. + +This was the result of a misunderstanding about the difference between the `Psr\Log\LoggerInterface.errorhandler` error handler service and the `Psr\Log\LoggerInterface` logging service. + +The `Psr\Log\LoggerInterface.errorhandler` error handler service should *not* be used for logging - its purpose is to handle the display of uncaught exceptions and PHP errors. + +Errors that were being logged to the error handler service are now being logged using the logging service instead. If you have connected a logging handler to that service, we recommend instead following the instructions in [configuring error logging](/developer_guides/debugging/error_handling/#configuring-error-logging) to attach your logging handler *only* to the logging service, which will also allow you to handle logging for the uncaught exceptions and errors the error handler displays. +