From 8a4574053f9a476e44b2b9c32e7fcc5e1cb15528 Mon Sep 17 00:00:00 2001 From: Guy Sartorelli <36352093+GuySartorelli@users.noreply.github.com> Date: Mon, 6 Jan 2025 16:52:50 +1300 Subject: [PATCH 1/4] DOC Update error handling and logging docs (#660) --- .../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 fc7c194bb..910b175d5 100644 --- a/en/08_Changelogs/5.4.0.md +++ b/en/08_Changelogs/5.4.0.md @@ -262,6 +262,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. + From cc3379a15c3349ab033f715f2a74d16604726dac Mon Sep 17 00:00:00 2001 From: Guy Sartorelli <36352093+GuySartorelli@users.noreply.github.com> Date: Tue, 7 Jan 2025 13:48:46 +1300 Subject: [PATCH 2/4] DOC Document newly deprecated API (#662) --- en/08_Changelogs/5.4.0.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/en/08_Changelogs/5.4.0.md b/en/08_Changelogs/5.4.0.md index 910b175d5..e7154d5bb 100644 --- a/en/08_Changelogs/5.4.0.md +++ b/en/08_Changelogs/5.4.0.md @@ -222,7 +222,7 @@ The `SilverStripe\CMS\Model\SiteTree.DESCRIPTION` localisation key (along with t - The [`SiteTree.icon`](api:SilverStripe\CMS\Model\SiteTree->icon) configuration property has been deprecated. It will be renamed to `cms_icon`. - The [`SiteTree.icon_class`](api:SilverStripe\CMS\Model\SiteTree->icon_class) configuration property has been deprecated. It will be renamed to `cms_icon_class`. This applies to all subclasses of `SiteTree` as well. - [`CMSMain::PageList()`](api:SilverStripe\CMS\Controllers\CMSMain::PageList()) has been deprecated. It will be renamed to `RecordList()`. -- [`CMSMain::PageListSidebar()`](api:SilverStripe\CMS\Controllers\CMSMain::PageListSidebar()) has been deprecated. It will be removed without equivalent functionality. +- [`CMSMain::PageListSidebar()`](api:SilverStripe\CMS\Controllers\CMSMain::PageListSidebar()) has been deprecated. It will be removed without equivalent functionality to replace it. - [`CMSMain::LinkPages()`](api:SilverStripe\CMS\Controllers\CMSMain::LinkPages()) has been deprecated. Use [`CMSMain::LinkRecords()`](api:SilverStripe\CMS\Controllers\CMSMain::LinkRecords()) instead. - [`CMSMain::LinkPagesWithSearch()`](api:SilverStripe\CMS\Controllers\CMSMain::LinkPagesWithSearch()) has been deprecated. Use [`CMSMain::LinkRecordsWithSearch()`](api:SilverStripe\CMS\Controllers\CMSMain::LinkRecordsWithSearch()) instead. - [`CMSMain::LinkPageEdit()`](api:SilverStripe\CMS\Controllers\CMSMain::LinkPageEdit()) has been deprecated. Use [`CMSMain::LinkRecordEdit()`](api:SilverStripe\CMS\Controllers\CMSMain::LinkRecordEdit()) instead. @@ -256,7 +256,12 @@ The `SilverStripe\CMS\Model\SiteTree.DESCRIPTION` localisation key (along with t - [`SiteTree::getIconClass()`](api:SilverStripe\CMS\Model\SiteTree::getIconClass()) has been deprecated. It will be replaced with `SilverStripe\CMS\Controllers\CMSMain::getRecordIconCssClass()`. - [`SiteTree::getPageIconURL()`](api:SilverStripe\CMS\Model\SiteTree::getPageIconURL()) has been deprecated. It will be replaced with `SilverStripe\CMS\Controllers\CMSMain::getRecordIconUrl()`. - [`SiteTree::generateChildrenCacheKey()`](api:SilverStripe\CMS\Model\SiteTree::generateChildrenCacheKey()) has been deprecated. It will be replaced with `SilverStripe\CMS\Controllers\CMSMain::generateChildrenCacheKey()`. -- [`Form::validationResult()`](api:SilverStripe\Forms\Form::validationResult()) has been deprecated. Use `SilverStripe\Forms\Form::validate()` instead. +- [`Form::validationResult()`](api:SilverStripe\Forms\Form::validationResult()) has been deprecated. Use [`Form::validate()`](api:SilverStripe\Forms\Form::validate()) instead. +- [`Director::get_session_environment_type()`](api:SilverStripe\Control\Director::get_session_environment_type()) has been deprecated. Use [`Director::get_environment_type()`](api:SilverStripe\Control\Director::get_environment_type()) instead. +- Use of the `CUSTOM_INCLUDE_PATH` constant to change the PHP include path has been deprecated and will not work in a future major release. +- [`SessionEnvTypeSwitcher`](api:SilverStripe\Control\Middleware\URLSpecialsMiddleware\SessionEnvTypeSwitcher) has been deprecated. It will be removed without equivalent functionality to replace it. +- [`VersionProvider::getComposerLockPath()`](api:SilverStripe\Core\Manifest\VersionProvider::getComposerLockPath()) has been deprecated. It will be removed without equivalent functionality to replace it. +- [`FlushInvalidatedResource::getResource()`](api:SilverStripe\i18n\Messages\Symfony\FlushInvalidatedResource::getResource()) has been deprecated. It will be removed without equivalent functionality to replace it. ## Bug fixes From 9543d9ad744f1f62592c7b3f6011199f033388a5 Mon Sep 17 00:00:00 2001 From: Guy Sartorelli <36352093+GuySartorelli@users.noreply.github.com> Date: Thu, 9 Jan 2025 09:27:47 +1300 Subject: [PATCH 3/4] DOC Document subsite deprecations (#666) --- en/08_Changelogs/5.4.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/08_Changelogs/5.4.0.md b/en/08_Changelogs/5.4.0.md index e7154d5bb..251baaba5 100644 --- a/en/08_Changelogs/5.4.0.md +++ b/en/08_Changelogs/5.4.0.md @@ -262,6 +262,8 @@ The `SilverStripe\CMS\Model\SiteTree.DESCRIPTION` localisation key (along with t - [`SessionEnvTypeSwitcher`](api:SilverStripe\Control\Middleware\URLSpecialsMiddleware\SessionEnvTypeSwitcher) has been deprecated. It will be removed without equivalent functionality to replace it. - [`VersionProvider::getComposerLockPath()`](api:SilverStripe\Core\Manifest\VersionProvider::getComposerLockPath()) has been deprecated. It will be removed without equivalent functionality to replace it. - [`FlushInvalidatedResource::getResource()`](api:SilverStripe\i18n\Messages\Symfony\FlushInvalidatedResource::getResource()) has been deprecated. It will be removed without equivalent functionality to replace it. +- [`Subsite::getMembersByPermission()`](api:SilverStripe\Subsites\Model\Subsite::getMembersByPermission()) has been deprecated. It will be removed without equivalent functionality to replace it. +- The `$join` parameter for the [`Subsite::get_from_all_subsites()`](api:SilverStripe\Subsites\Model\Subsite::get_from_all_subsites()) method has been deprecated. Use [leftJoin($table, $joinClause)](api:SilverStripe\ORM\DataList::leftJoin()) instead. ## Bug fixes From ea19f7a5e04e7eb91ab422a62fc82db87cd4da21 Mon Sep 17 00:00:00 2001 From: Guy Sartorelli <36352093+GuySartorelli@users.noreply.github.com> Date: Fri, 10 Jan 2025 10:47:57 +1300 Subject: [PATCH 4/4] DOC Document deprecating boolean into Form::loadDataFrom() (#668) --- en/08_Changelogs/5.4.0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/en/08_Changelogs/5.4.0.md b/en/08_Changelogs/5.4.0.md index 251baaba5..6e9ca3dd6 100644 --- a/en/08_Changelogs/5.4.0.md +++ b/en/08_Changelogs/5.4.0.md @@ -264,6 +264,7 @@ The `SilverStripe\CMS\Model\SiteTree.DESCRIPTION` localisation key (along with t - [`FlushInvalidatedResource::getResource()`](api:SilverStripe\i18n\Messages\Symfony\FlushInvalidatedResource::getResource()) has been deprecated. It will be removed without equivalent functionality to replace it. - [`Subsite::getMembersByPermission()`](api:SilverStripe\Subsites\Model\Subsite::getMembersByPermission()) has been deprecated. It will be removed without equivalent functionality to replace it. - The `$join` parameter for the [`Subsite::get_from_all_subsites()`](api:SilverStripe\Subsites\Model\Subsite::get_from_all_subsites()) method has been deprecated. Use [leftJoin($table, $joinClause)](api:SilverStripe\ORM\DataList::leftJoin()) instead. +- Passing a boolean value to the `$mergeStrategy` argument in [`Form::loadDataFrom()`](api:Silverstripe\Forms\Form::loadDataFrom()) has been deprecated. Pass [`Form::MERGE_CLEAR_MISSING`](api:Silverstripe\Forms\Form::MERGE_CLEAR_MISSING) instead of `true` and `0` instead of `false`. ## Bug fixes