Merge pull request #165 from creative-commoners/pulls/4/nicer-depreca…

…tions

DOC Document new changes to deprecation output

en/00_Getting_Started/03_Environment_Management.md

@@ -42,20 +42,24 @@ You can set "real" environment variables using Apache. Please
 
 ## How to access the environment variables
 
-Accessing the environment variables should be done via the `Environment::getEnv()` method.
+Accessing the environment variables should be done via the [`Environment::getEnv()`](api:SilverStripe\Core\Environment::getEnv()) method.
 
 ```php
 use SilverStripe\Core\Environment;
 Environment::getEnv('SS_DATABASE_CLASS');
 ```
 
-Individual settings can be assigned via `Environment::setEnv()` or `Environment::putEnv()` methods.
+Individual settings can be assigned via [`Environment::setEnv()`](api:SilverStripe\Core\Environment::setEnv()) or [`Environment::putEnv()`](api:SilverStripe\Core\Environment::putEnv()) methods.
 
 ```php
 use SilverStripe\Core\Environment;
 Environment::setEnv('API_KEY', 'AABBCCDDEEFF012345');
 ```
 
+[warning]
+`Environment::getEnv()` will return `false` whether the variable was explicitly set as `false` or simply wasn't set at all. You can use [`Environment::hasEnv()`](api:SilverStripe\Core\Environment::hasEnv()) to check whether an environment variable was set or not.
+[/warning]
+
 ### Using environment variables in config
 
 To use environment variables in `.yaml` configs you can reference them using backticks. You can have multiple

en/02_Developer_Guides/07_Debugging/01_Error_Handling.md

@@ -170,6 +170,10 @@ SilverStripe\Core\Injector\Injector:
 The log file will be relative to the main index.php file path (default: inside public/), so "../silverstripe.log" will
 create a file in your project root.
 
+[notice]
+You will need to make sure the user running the php process has write access to the log file, wherever you choose to put it.
+[/notice]
+
 The `info` argument provides the minimum level to start logging at.
 
 ### Disabling the default handler

en/03_Upgrading/07_Deprecations.md

@@ -4,27 +4,112 @@ title: Deprecations
 
 # Deprecations
 
-## Updating your codebase to use avoid using deprecated API in Silverstripe CMS
-
 You'll need to go through your codebase to remove references to deprecated APIs and update your project logic.
 
 Major releases of Silverstripe CMS introduce many API changes. They include a deprecation message that will either tell you:
 - to simply use a different yet equivalent API instead, or
 - the API in question has no replacement. This is usually for API that was mostly irrelevant.
 
-To see deprecation warnings in your project and in your project's CI, add `SS_DEPRECATION_ENABLED=true` to your project's `.env` file.
+## Enabling deprecation warnings
+
+To enable deprecation warnings, set the `SS_DEPRECATION_ENABLED` environment variable in your project's `.env` file.
+
+[info]
+If the `SS_DEPRECATION_ENABLED` environment variable is set, this takes precedence over use of the `Deprecation::enable()` static method.
+[info]
+
+```env
+SS_DEPRECATION_ENABLED=true
+```
+
+Alternatively, add the following line to your project's `app/_config.php`.
+
+```php
+Deprecation::enable();
+```
+
+[info]
+Deprecation warnings will only ever show if your `SS_ENVIRONMENT_TYPE` is set to `dev`.
+[/info]
+
+Once you have resolved all of the deprecation warnings you can, it is recommended to turn off deprecation warnings again.
+
+Not all API that gets deprecated will have an equivalent replacement API in that same major version; some of the API is only available from the next major release. A good example of this is the upgrade for what powers the `SilverStripe\Control\Email\Email` class from `swiftmailer` in CMS 4 to `symfony/mailer` in CMS 5. In these cases, you'll need to upgrade to the new major version before you can access the replacement API.
+
+Some code that has been deprecated with no immediate replacement will not emit deprecation notices by default. If you wish to also see notices for deprecated code with no immediate replacement, add the following line to you project's `app/_config.php` file. Note that this will also emit deprecation notices for usages of the deprecated code inside core modules.
+
+```php
+Deprecation::enable(true);
+```
+
+## How to view deprecation warnings
+
+By default, deprecation warnings will be emitted to the error logger, and will be output at the end of CLI responses. They will not be included in HTTP responses by default.
+
+### 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 yml configuration:
+
+```yml
+SilverStripe\Core\Injector\Injector:
+  ErrorLogFileHandler:
+    class: Monolog\Handler\StreamHandler
+    constructor:
+      - "../silverstripe.log" # an absolute path, or a path relative to the index.php file (usually inside the public/ directory)
+      - "warning" # warning is the level deprecation warnings are logged as
+  Psr\Log\LoggerInterface.errorhandler:
+    calls:
+      ErrorLogFileHandler: [ pushHandler, [ '%$ErrorLogFileHandler' ] ]
+```
+
+[notice]
+You will need to make sure the user running the php process has write access to the log file, wherever you choose to put it.
+[/notice]
+
+See [Configuring error logging](/developer_guides/debugging/error_handling/#configuring-error-logging) to learn about other ways you can handle error logs.
+
+### Deprecation warnings in your browser
+
+Deprecation warnings won't be output to HTTP responses by default because it can be difficult to parse and collate information this way, and deprecation warnings in XHR/AJAX responses can result in unexpected behaviour in some situations. That said, you can choose to enable this output.
+
+Deprecation warnings can be set to output in HTTP responses by setting `SS_DEPRECATION_SHOW_HTTP` to a truthy value in your .env file.
+
+[info]
+If the `SS_DEPRECATION_SHOW_HTTP` environment variable is set, this takes precedence over use of the `Deprecation::setShouldShowForHttp()` static method.
+[info]
+
+```env
+SS_DEPRECATION_SHOW_HTTP=true
+```
+
+Alternatively, add the following line to your project's `app/_config.php`.
 
-Alternatively, add the following line to you project's `app/_config.php`.
 ```php
-Deprecation::enable()
+Deprecation::setShouldShowForHttp(true);
 ```
 
-Deprecation notices will only ever show if your `SS_ENVIRONMENT_TYPE` is set to `dev`.
+Note that the output for this won't be very easy to read. You might prefer instead to install [lekoala/silverstripe-debugbar](https://github.com/lekoala/silverstripe-debugbar) as a dev dependency. Deprecation warnings will be logged in the "messages" tab of the debugbar.
+
+[warning]
+The debugbar will _not_ show you any deprecation warnings that are triggered from XHR/AJAX requests or which are triggered after the middleware has finished generating the debugbar for the response.
+[/warning]
 
-Your project will now start emitting deprecation warnings on the frontend if you are calling deprecated code, along with the different API you should now use instead, if a replacement exists.
+## Deprecation warnings in the CLI
 
-Not all API that gets deprecated will have an equivalent replacement API in that same major version; some of the API is only available from the next major release.  A good example of this is the upgrade for what powers the `SilverStripe\Control\Email\Email` class from `swiftmailer` in CMS 4 to `symfony/mailer` in CMS 5. In these cases, you'll need to upgrade to the new major version before you can access the replacement API.
+Deprecation warnings are output for CLI responses by default (assuming they're enabled in general). The warnings are always output at the _end_ of the request, so you don't have to go looking through the output for them. You might want to disable outputting these warnings in CLI responses if, for example, you need to validate the output via code and don't want to add special cases for deprecation warnings.
 
-Your project will emit deprecation notices for these, although there may be nothing you can do to stop calling that code until you upgrade to the new major version. In this case you should use the deprecation notice to construct a list of what you may need to change after upgrading.
+You can suppress deprecation warnings from CLI output by setting `SS_DEPRECATION_SHOW_CLI` to a falsy value in your .env file.
 
-Once you have resolved all of the deprecation notices you can, it is recommended to turn off deprecation notices again.
+[info]
+If the `SS_DEPRECATION_SHOW_CLI` environment variable is set, this takes precedence over use of the `Deprecation::SS_DEPRECATION_SHOW_CLI()` static method.
+[info]
+
+```env
+SS_DEPRECATION_SHOW_CLI=false
+```
+
+Alternatively, add the following line to your project's `app/_config.php`.
+
+```php
+Deprecation::setShouldShowForCli(false);
+```

en/04_Changelogs/4.13.0.md

@@ -8,6 +8,7 @@ title: 4.13.0 (unreleased)
 
 - [API changes](#api-changes)
   - [Deprecated API (by module, alphabetically)](#api-deprecated)
+- [Features and enhancements](#features-and-enhancements)
 
 ## API changes {#api-changes}
 
@@ -65,3 +66,7 @@ Deprecated method [`SilverStripe\View\Parsers\Diff::getHTMLChunks()`](api:Silver
 Deprecated method [`SilverStripe\Control\Email\Email::mergeConfiguredEmails()`](api:SilverStripe\Control\Email\Email::mergeConfiguredEmails()) Will be removed without equivalent functionality to replace it
 Deprecated method [`SilverStripe\Control\HTTP::get_cache_age()`](api:SilverStripe\Control\HTTP::get_cache_age()) Will be removed without equivalent functionality to replace it
 Deprecated config [`SilverStripe\Control\Director.alternate_public_dir`](api:SilverStripe\Control\Director.alternate_public_dir) Will be removed without equivalent functionality to replace it
+
+## Features and enhancements
+
+- There is a new [`Environment::hasEnv()`](api:SilverStripe\Core\Environment::hasEnv()) method which will tell you if a given environment variable has been set. This is useful because [`Environment::getEnv()`](api:SilverStripe\Core\Environment::getEnv()) will return `false` if the variable hasn't been set, but it will also return `false` if the variable has been explicitly set to `false`! Now you can check which it is.