Console: Update documentation to describe new default behaviour

lkrms · lkrms · commit 9d7225edb301 · 2025-03-21T18:07:42.000+11:00
diff --git a/docs/Console.md b/docs/Console.md
@@ -1,71 +1,57 @@
-## Terminal output and logging
+# Console
 
-With a similar API to the `console` object provided by web browsers, the
-[Console][] class[^1] provides:
+The Console component provides terminal output and message logging via an API
+similar to `console` in web browsers.
 
-- Familiar methods like `Console::log()` and `Console::error()`
-- Variants like `Console::logOnce()` and `Console::errorOnce()` to output
-  messages once per run
+- Familiar methods like [Console::log()][log()] and [Console::error()][error()]
+- Variants like [Console::logOnce()][logOnce()] and
+  [Console::errorOnce()][errorOnce()] to output messages once per run
 - Output to multiple targets
 - Messages filtered by log level
-- Formatting to reflect message priority and improve readability
+- Formatting that reflects message priority and improves readability
+- Optional Markdown-like syntax for additional formatting
 - Colour output to TTYs
+- [PSR-3 (Logger Interface)][PSR-3] support via [Console::logger()][logger()]
 
-### Default targets
+## Default targets
 
-By default, [Console][] output is appended to a file in the default temporary
-directory, created with mode `0600` if it doesn't already exist:
+If no targets are registered to receive [Console][] output when a message is
+written:
 
-```php
-<?php
-sys_get_temp_dir() . '/<script_basename>-<realpath_hash>-<user_id>.log'
-```
-
-If the value of environment variable `console_target` is `stderr` or `stdout`,
-[Console][] output is also written to `STDERR` or `STDOUT` respectively.
+1. Output is appended to a log file in PHP's default temporary directory,
+   created with mode `0600` if it doesn't already exist:
 
-If `console_target` is not set and the script is running on the command line:
+   ```php
+   sys_get_temp_dir() . '/<script_basename>-<realpath_hash>-<user_id>.log'
+   ```
 
-- If `STDERR` is a TTY and `STDOUT` is not, console messages are written to
-  `STDERR` so output to `STDOUT` isn't tainted
-- Otherwise, errors and warnings are written to `STDERR`, and informational
-  messages are written to `STDOUT`
+2. If the script is running on the command line, output is also written to
+   `STDERR`.
 
-Debug messages are written to the output log but are not written to `STDOUT` or
-`STDERR` if environment variable `DEBUG` is empty or not set.
+Debug messages are suppressed unless debug mode is enabled in the environment,
+e.g. by setting `DEBUG=1`.
 
-To override these defaults, register at least one [Console][] output target,
-e.g. by calling [registerTarget()][], before any other `Console` methods are
-called, preferably while bootstrapping your application.
+To override these defaults:
 
-> [Application][] and [CliApplication][] always call [registerStderrTarget()][],
-> which registers the default `STDOUT` and `STDERR` targets and prevents
-> creation of the default output log. To create a log file that persists between
-> reboots (in your project's `var/log` directory by default), call the app
-> container's [logOutput()][] method.
+- register at least one [Console][] output target while bootstrapping your
+  application, or
+- create an [Application][] or [CliApplication][] and optionally use
+  [logOutput()][] to write output a persistent log file
 
-### Output methods
+## Message methods
 
 <!-- prettier-ignore -->
-| Method          | Message level         | Default prefix   | Default output target     |
-| --------------- | --------------------- | ---------------- | ------------------------- |
-| `error[Once]()` | `LEVEL_ERROR` = `3`   | ` !  `           | `STDERR`                  |
-| `warn[Once]()`  | `LEVEL_WARNING` = `4` | ` ^  `           | `STDERR`                  |
-| `info[Once]()`  | `LEVEL_NOTICE` = `5`  | ` ➤  `           | `STDOUT`                  |
-| `log[Once]()`   | `LEVEL_INFO` = `6`    | ` -  `           | `STDOUT`                  |
-| `debug[Once]()` | `LEVEL_DEBUG` = `7`   | ` :  `           | `STDOUT` (if `DEBUG` set) |
-| `group()`[^2]   | `LEVEL_NOTICE` = `5`  | ` »  `           | `STDOUT`                  |
-| `logProgress()` | `LEVEL_INFO` = `6`    | ` ⠋  ` (spinner) | `STDOUT`                  |
-
-[^1]:
-    Actually a facade for [ConsoleInterface][], which is backed by a shared
-    instance of [Console][ConsoleService] by default.
-
-[^2]:
-    `Console::group()` adds a level of indentation to all `Console` output until
-    `Console::groupEnd()` is called.
-
-### Formatting
+| Method                             | Message level         | Default prefix             |
+| ---------------------------------- | --------------------- | -------------------------- |
+| `error()`, `errorOnce()`           | `LEVEL_ERROR` = `3`   | ` !  `                     |
+| `warn()`, `warnOnce()`             | `LEVEL_WARNING` = `4` | ` ^  `                     |
+| `group()`,`groupEnd()`             | `LEVEL_NOTICE` = `5`  | ` »  `, ` «  `             |
+| `info()`, `infoOnce()`             | `LEVEL_NOTICE` = `5`  | ` ➤  `                     |
+| `log()`, `logOnce()`               | `LEVEL_INFO` = `6`    | ` -  `                     |
+| `logProgress()`, `clearProgress()` | `LEVEL_INFO` = `6`    | ` ⠋  ` (spinner, TTY only) |
+| `debug()`, `debugOnce()`           | `LEVEL_DEBUG` = `7`   | ` :  `                     |
+
+## Formatting
 
 The following Markdown-like syntax is supported in [Console][] messages:
 
@@ -98,13 +84,16 @@ hard line break.
   https://salient-labs.github.io/toolkit/Salient.Cli.CliApplication.html
 [Console]:
   https://salient-labs.github.io/toolkit/Salient.Core.Facade.Console.html
-[ConsoleInterface]:
-  https://salient-labs.github.io/toolkit/Salient.Contract.Console.ConsoleInterface.html
-[ConsoleService]:
-  https://salient-labs.github.io/toolkit/Salient.Console.Console.html
+[error()]:
+  https://salient-labs.github.io/toolkit/Salient.Core.Facade.Console.html#_error
+[errorOnce()]:
+  https://salient-labs.github.io/toolkit/Salient.Core.Facade.Console.html#_errorOnce
+[log()]:
+  https://salient-labs.github.io/toolkit/Salient.Core.Facade.Console.html#_log
+[logger()]:
+  https://salient-labs.github.io/toolkit/Salient.Core.Facade.Console.html#_logger
+[logOnce()]:
+  https://salient-labs.github.io/toolkit/Salient.Core.Facade.Console.html#_logOnce
 [logOutput()]:
   https://salient-labs.github.io/toolkit/Salient.Container.Application.html#_logOutput
-[registerStderrTarget()]:
-  https://salient-labs.github.io/toolkit/Salient.Console.Console.html#_registerStderrTarget
-[registerTarget()]:
-  https://salient-labs.github.io/toolkit/Salient.Console.Console.html#_registerTarget
+[PSR-3]: https://www.php-fig.org/psr/psr-3/
diff --git a/src/Toolkit/Console/Console.php b/src/Toolkit/Console/Console.php
@@ -25,6 +25,8 @@
 use Throwable;
 
 /**
+ * @api
+ *
  * @implements FacadeAwareInterface<ConsoleInterface>
  */
 class Console implements ConsoleInterface, FacadeAwareInterface, Unloadable
diff --git a/src/Toolkit/Console/README.md b/src/Toolkit/Console/README.md
@@ -14,25 +14,25 @@
 `salient/console` provides terminal output and message logging via an API
 similar to `console` in web browsers.
 
-- Familiar methods like [Console::log()][log] and [Console::error()][error]
-- Variants like [Console::logOnce()][logOnce] and
-  [Console::errorOnce()][errorOnce] to output messages once per run
+- Familiar methods like [Console::log()][log()] and [Console::error()][error()]
+- Variants like [Console::logOnce()][logOnce()] and
+  [Console::errorOnce()][errorOnce()] to output messages once per run
 - Output to multiple targets
 - Messages filtered by log level
 - Formatting that reflects message priority and improves readability
 - Optional Markdown-like syntax for additional formatting
 - Colour output to TTYs
-- [PSR-3 (Logger Interface)][PSR-3] support via [Console::logger()][logger]
+- [PSR-3 (Logger Interface)][PSR-3] support via [Console::logger()][logger()]
 
-[error]:
+[error()]:
   https://salient-labs.github.io/toolkit/Salient.Core.Facade.Console.html#_error
-[errorOnce]:
+[errorOnce()]:
   https://salient-labs.github.io/toolkit/Salient.Core.Facade.Console.html#_errorOnce
-[log]:
+[log()]:
   https://salient-labs.github.io/toolkit/Salient.Core.Facade.Console.html#_log
-[logger]:
+[logger()]:
   https://salient-labs.github.io/toolkit/Salient.Core.Facade.Console.html#_logger
-[logOnce]:
+[logOnce()]:
   https://salient-labs.github.io/toolkit/Salient.Core.Facade.Console.html#_logOnce
 [PSR-3]: https://www.php-fig.org/psr/psr-3/
 
diff --git a/src/Toolkit/Contract/Console/ConsoleInterface.php b/src/Toolkit/Contract/Console/ConsoleInterface.php
@@ -291,7 +291,7 @@ public function debugOnce(
     );
 
     /**
-     * Print "$msg1 $msg2" or similar with level- and type-base formatting
+     * Print "$msg1 $msg2" or similar with level- and type-based formatting
      *
      * @param string $msg1 May use inline formatting tags (see {@see escape()}).
      * @param string|null $msg2 Inline formatting tags have no special meaning.
@@ -309,7 +309,7 @@ public function message(
     );
 
     /**
-     * Print "$msg1 $msg2" or similar with level- and type-base formatting once
+     * Print "$msg1 $msg2" or similar with level- and type-based formatting once
      * per run
      *
      * @param string $msg1 May use inline formatting tags (see {@see escape()}).
diff --git a/src/Toolkit/Core/Facade/Console.php b/src/Toolkit/Core/Facade/Console.php
