[CMSP-791] Document changes to stderr in WP-CLI

source/content/guides/wp-cli/07-wp-cli-troubleshoot.md

@@ -58,7 +58,64 @@ ini_set('arg_separator.output', '&');
 
 Actions or filters that require CLI tools like WP-CLI might fail from `wp-config.php`, because the functions required are not yet accessible. Put these directives in an [MU Plugin](/guides/wordpress-configurations/mu-plugin) to resolve this issue.
 
+## Changes to WP-CLI on the Platform (January 15th 2024)
+
+<Alert title="What's the TL;DR?"  type="info" >
+The appearance of PHP errors is changing when invoking WP-CLI. This is unlikely to affect you unless you have shell scripts that are specifically expecting to handle or parse PHP errors as part of the output of a WP-CLI command.
+</Alert>
+
+### Before January 15th
+When a command is invoked in WP-CLI in a non-live environment, errors are sent to STDOUT as part of the output. When invoked over Terminus, errors are printed before the command output. In this example, I have called `trigger_error()` for a warning and notice in my `wp-config.php` file.
+```bash
+$ terminus wp <site>.<env> -- config get table_prefix
+
+Notice: A Notice. in phar:///opt/pantheon/wpcli/wp-cli-2.8.1.phar/vendor/wp-cli/config-command/src/Config_Command.php(444) : eval()'d code on line 78
+
+Warning: A Warning. in phar:///opt/pantheon/wpcli/wp-cli-2.8.1.phar/vendor/wp-cli/config-command/src/Config_Command.php(444) : eval()'d code on line 79
+wp_
+ [notice] Command: <site>.<env> -- wp config get table_prefix [Exit: 0]
+```
+
+This makes it especially difficult to script something that relies on capturing the value of a given command (i.e. `config get` or `plugin list`), as the errors also end up captured, and it takes convoluted shell gymnastics to work around.
+```bash
+$ PREFIX=$(terminus remote:wp <site>.<env> -- config get table_prefix)
+ [notice] Command: <site>.<env> -- wp config get table_prefix [Exit: 0]
+$ echo $PREFIX
+
+Notice: A Notice. in phar:///opt/pantheon/wpcli/wp-cli-2.8.1.phar/vendor/wp-cli/config-command/src/Config_Command.php(444) : eval()'d code on line 78
+
+Warning: A Warning. in phar:///opt/pantheon/wpcli/wp-cli-2.8.1.phar/vendor/wp-cli/config-command/src/Config_Command.php(444) : eval()'d code on line 79
+wp_
+```
+
+### Starting January 15th
+When running WP-CLI, `display_errors` will be changed to `stderr` in `php.ini`, so that errors can be handled separate from the actual command output. Three changes are notable here:
+
+#### Errors go to STDERR
+The obvious and intentional change. With errors going to `stderr`, it is now possible to capture the output of a WP-CLI command with no extra steps.
+```bash
+$ PREFIX=$(terminus remote:wp <site>.<env> -- config get table_prefix)
+Notice: A Notice. in phar:///opt/pantheon/wpcli/wp-cli-2.8.1.phar/vendor/wp-cli/config-command/src/Config_Command.php(444) : eval()'d code on line 78
+Warning: A Warning. in phar:///opt/pantheon/wpcli/wp-cli-2.8.1.phar/vendor/wp-cli/config-command/src/Config_Command.php(444) : eval()'d code on line 79
+ [notice] Command: <site>.<env> -- wp config get table_prefix [Exit: 0]
+$ echo $PREFIX
+wp_
+```
+
+#### Live errors will display in WP-CLI
+The change to WP-CLI’s error handling is environment-agnostic, so while `display_errors` remains `off` (i.e. unchanged) on Live PHP-FPM configuration (i.e. in the browser), it will be `stderr` only for CLI interactions.
+
+#### Terminus now displays error messages after the command output
+Because of Terminus’ specific handling of STDOUT and STDERR, PHP errors now display after the command output instead of before.
+```bash
+$ terminus remote:wp <site>.<env> -- config get table_prefix
+wp_
+Notice: A Notice. in phar:///opt/pantheon/wpcli/wp-cli-2.8.1.phar/vendor/wp-cli/config-command/src/Config_Command.php(444) : eval()'d code on line 78
+Warning: A Warning. in phar:///opt/pantheon/wpcli/wp-cli-2.8.1.phar/vendor/wp-cli/config-command/src/Config_Command.php(444) : eval()'d code on line 79
+ [notice] Command: <site>.<env> -- wp config get table_prefix [Exit: 0]
+```
+
 ## More Resources
 
 - [Configure Your wp-config.php File](/guides/php/wp-config-php)
-- [WordPress and PHP Sessions](/guides/php/wordpress-sessions)
+- [WordPress and PHP Sessions](/guides/php/wordpress-sessions)