Merge branch 'review-console'

Author: lkrms

CHANGELOG.md

@@ -10,6 +10,153 @@ The format is based on [Keep a Changelog][], and this project adheres to [Semant
 [Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
 [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
 
+## [v0.99.78] - 2025-03-28
+
+### Added
+
+#### `Console`
+
+- Add and implement `ConsoleInterface` methods:
+  - `getTtyTarget()`
+  - `removeEscapes()`
+  - `removeTags()`
+- Add and implement `StreamTargetInterface` method `getUri()`
+- In `ConsoleInterface`:
+  - Add optional `$debug` parameters to `registerStderrTarget()` and `registerStdioTargets()`
+  - Add optional `$escapeNewlines` parameter to `escape()`
+  - Add optional `$count` parameter to `exception()`
+
+#### `Container`
+
+- Allow closures to be bound to the container
+- Add `$container` parameter to `HasBindings` methods and allow them to return closures
+- Add `$container` parameter to `getContextualBindings()` and allow it to return parameter and unmapped services, closures and instances
+- Add and implement `ApplicationInterface` methods:
+  - `getVersion()`
+  - `getVersionString()`
+  - `reportVersion()`
+
+#### `PHPStan`
+
+- Add `ContainerRule` to report when calls to `ContainerInterface::getAs()` have an `$id` that isn't a subtype of `$service`
+
+### Changed
+
+#### `Console`
+
+- **Change default `Console::info()` prefix from `➤ ` to `> ` to address inconsistent output width on some platforms**
+- In `ConsoleLogger`, pass debug messages to `Console::debug()` so the caller is output
+- In `StreamTarget::reopen()`, don't throw an exception if the stream can't be reopened
+- Don't close targets when they are deregistered
+- Rename `ConsoleInterface` methods:
+  - `getLogger()` -> `logger()`
+  - `setTargetPrefix()` -> `setPrefix()`
+  - `printOut()` -> `printStdio()`
+  - `getErrorCount()` -> `errors()`
+  - `getWarningCount()` -> `warnings()`
+- Remove `$type` parameters from `print()` methods in `ConsoleInterface`
+- Rename `StreamTarget` method `fromPath()` to more accurate `fromFile()`
+- Rename:
+  - `ConsoleFormatInterface` -> `FormatInterface`
+  - `ConsoleFormatterInterface` -> `FormatterInterface`
+  - `ConsoleMessageAttributesInterface` -> `MessageAttributesInterface`
+  - `ConsoleMessageFormatInterface` -> `MessageFormatInterface`
+  - `ConsoleTagAttributesInterface` -> `TagAttributesInterface`
+  - `ConsoleTargetInterface` -> `TargetInterface`
+  - `ConsoleTargetPrefixInterface` -> `HasPrefix`
+  - `ConsoleTargetStreamInterface` -> `StreamTargetInterface`
+  - `ConsoleFormat` -> `TtyFormat`
+  - `ConsoleFormatter` -> `Formatter`
+  - `ConsoleLoopbackFormat` -> `LoopbackFormat`
+  - `ConsoleManPageFormat` -> `ManPageFormat`
+  - `ConsoleMarkdownFormat` -> `MarkdownFormat`
+  - `ConsoleMessageAttributes` -> `MessageAttributes`
+  - `ConsoleMessageFormat` -> `MessageFormat`
+  - `ConsoleMessageFormats` -> `MessageFormats`
+  - `ConsolePrefixTarget` -> `AbstractTargetWithPrefix`
+  - `ConsoleStreamTarget` -> `AbstractStreamTarget`
+  - `ConsoleTag` -> `HasTag` and add `TAG_` prefix to the names of its constants
+  - `ConsoleTagAttributes` -> `TagAttributes`
+  - `ConsoleTagFormats` -> `TagFormats`
+  - `ConsoleTarget` -> `AbstractTarget`
+  - `ConsoleTargetTypeFlag` -> `HasTargetFlag` and add `TARGET_` prefix to the names of its constants
+- Rename methods:
+  - `withUnescape()` -> `withRemoveEscapes()`
+  - `getUnescape()` -> `removesEscapes()`
+  - `withWrapAfterApply()` -> `withWrapAfterFormatting()`
+  - `getWrapAfterApply()` -> `wrapsAfterFormatting()`
+- Replace "dim" with "faint" in method names and documentation
+
+#### `Container`
+
+- **Remove `$args` parameters from `bind()`, `bindIf()`, `singleton()` and `singletonIf()`**
+- **Rename `getName()` -> `getClass()`**
+- In `getAs()`, throw an exception if `$id` doesn't extend or implement `$service`
+- In `providers()`, map unmapped providers to themselves
+- Rename event and exception interfaces for consistency
+- Rename `ArgumentsNotUsedException` -> `UnusedArgumentsException`
+- Rename `ServiceLifetime` -> `HasServiceLifetime` and add `LIFETIME_` prefix to the names of its constants
+- Rename `ApplicationInterface` methods:
+  - `getAppName()` -> `getName()`
+  - `isProduction()` -> `isRunningInProduction()`
+  - `registerSyncNamespace()` -> `sync()` and start the entity store implicitly when called
+  - `getWorkingDirectory()` -> `getInitialWorkingDirectory()`
+  - `setWorkingDirectory()` -> `setInitialWorkingDirectory()` and remove nullability from parameter
+- In `Application`:
+  - **Always load `.env` files (previously, they were only loaded when running from source)**
+  - **Write console messages to `STDERR` when running on the command line (previously, warnings and errors were written to `STDERR` and everything else was written to `STDOUT` by default)**
+  - Retrieve application name from configuration value `"app.name"` before falling back to script basename
+  - Only stop cache and sync store instances started by the container
+
+### Removed
+
+#### `Cli`
+
+- Remove redundant `CliApplicationInterface` methods `reportVersion()` and `getVersionString()`
+
+#### `Console`
+
+- Remove `ConsoleInterface` methods:
+  - `getFormatter()` (retrieve via `getTtyTarget()`)
+  - `getWidth()` (retrieve via `getTtyTarget()`)
+  - `printStderr()` (unused)
+- Remove `FormatterInterface::withSpinnerState()`
+- Remove `StreamTargetInterface::getEol()`
+- Remove `StreamTarget::fromStream()` in favour of a public constructor
+- Remove unused `StreamTarget` method `getPath()`
+
+#### `Container`
+
+- Remove unused `unbind()` method
+- Remove implementation-specific `resumeCache()` method from `ApplicationInterface`
+- Remove implementation-specific arguments from `startSync()` method in `ApplicationInterface`
+
+### Fixed
+
+#### `Console`
+
+- Fix issue where `$msg2` is not indented when prefix width is 2
+- Fix issue where trailing carriage returns may not be preserved in `LoopbackFormat`, `ManPageFormat` and `MarkdownFormat`
+
+#### `Container`
+
+- Fix issue where calling `bind()` with `$class = null` does not replace an existing binding to a different class
+- Fix issue where parameter bindings only work for untyped and scalar constructor parameters
+- Fix issue where objects cannot be bound to constructor parameters via contextual bindings
+- Fix `addContextualBinding()` issue where `$class` cannot be `null`
+- Fix `inContextOf()` issue where contextual callbacks are not used
+- Fix issue where `Application::logOutput()` can be called repeatedly
+
+#### `Core`
+
+- Fix issue where methods that return `$this` from behind a facade return a facade-bound instance
+
+### Security
+
+#### `Console`
+
+- Fix issue where `StreamTarget::reopen()` may not apply file permissions correctly in some log rotation scenarios
+
 ## [v0.99.77] - 2025-03-04
 
 ### Added
@@ -4770,6 +4917,7 @@ This is the final release of `lkrms/util`. It is moving to [Salient](https://git
 
 - Allow `CliOption` value names to contain arbitrary characters
 
+[v0.99.78]: https://github.com/salient-labs/toolkit/compare/v0.99.77...v0.99.78
 [v0.99.77]: https://github.com/salient-labs/toolkit/compare/v0.99.76...v0.99.77
 [v0.99.76]: https://github.com/salient-labs/toolkit/compare/v0.99.75...v0.99.76
 [v0.99.75]: https://github.com/salient-labs/toolkit/compare/v0.99.74...v0.99.75

docs/Console.md

@@ -46,7 +46,7 @@ To override these defaults:
 | `error()`, `errorOnce()`           | `LEVEL_ERROR` = `3`   | ` !  `                     |
 | `warn()`, `warnOnce()`             | `LEVEL_WARNING` = `4` | ` ^  `                     |
 | `group()`,`groupEnd()`             | `LEVEL_NOTICE` = `5`  | ` »  `, ` «  `             |
-| `info()`, `infoOnce()`             | `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`   | ` :  `                     |

scripts/check-coverage.php

@@ -29,7 +29,7 @@
     'Core' => ['Core', true, true, '2025-02-14: code review finalised, replacement of `Legacy` classes still pending'],
     'Iterator' => ['Iterators', true, true, '2025-02-26: code review finalised'],
     'Cache' => ['Cache', true, true, '2025-02-23: code review finalised'],
-    'Console' => ['Console', null, null, null],
+    'Console' => ['Console', true, true, '2025-03-28: code review finalised except `Formatter` rewrite'],
     'Container' => ['Container', true, true, '2025-03-11: code review finalised except `Container` rewrite sans Dice'],
     'Http' => ['HTTP', null, null, null],
     'Db' => ['Db', null, null, null],

src/Toolkit/Cli/CliApplication.php

@@ -3,7 +3,6 @@
 namespace Salient\Cli;
 
 use Salient\Cli\Exception\CliInvalidArgumentsException;
-use Salient\Console\Format\Formatter;
 use Salient\Console\Format\ManPageFormat;
 use Salient\Console\Format\MarkdownFormat;
 use Salient\Container\Application;
@@ -233,7 +232,7 @@ private function getHelp(string $name, $node, ?CliHelpStyle $style = null): ?str
         foreach ($node as $childName => $childNode) {
             $command = $this->getNodeCommand(trim("$name $childName"), $childNode);
             if ($command) {
-                $synopses[] = '__' . $childName . '__ - ' . Formatter::escapeTags($command->getDescription());
+                $synopses[] = '__' . $childName . '__ - ' . Console::escape($command->getDescription());
             } elseif (is_array($childNode)) {
                 $synopses[] = '__' . $childName . '__';
             }
@@ -260,7 +259,7 @@ private function getUsage(string $name, $node): ?string
 
         if ($command) {
             return $command->getSynopsis($style)
-                . Formatter::escapeTags("\n\nSee '"
+                . Console::escape("\n\nSee '"
                     . ($name === '' ? "$progName --help" : "$progName help $name")
                     . "' for more information.");
         }
@@ -279,15 +278,15 @@ private function getUsage(string $name, $node): ?string
                 $synopsis = $command->getSynopsis($style);
             } elseif (is_array($childNode)) {
                 $synopsis = "$fullName $childName <command>";
-                $synopsis = Formatter::escapeTags($synopsis);
+                $synopsis = Console::escape($synopsis);
             } else {
                 continue;
             }
             $synopses[] = $synopsis;
         }
 
         return implode("\n", $synopses)
-            . Formatter::escapeTags("\n\nSee '"
+            . Console::escape("\n\nSee '"
                 . Arr::implode(' ', ["$progName help", $name, '<command>'])
                 . "' for more information.");
     }

src/Toolkit/Cli/CliCommand.php

@@ -4,7 +4,6 @@
 
 use Salient\Cli\Exception\CliInvalidArgumentsException;
 use Salient\Cli\Exception\CliUnknownValueException;
-use Salient\Console\Format\Formatter;
 use Salient\Contract\Cli\CliApplicationInterface;
 use Salient\Contract\Cli\CliCommandInterface;
 use Salient\Contract\Cli\CliHelpSectionName;
@@ -314,7 +313,7 @@ final public function getHelp(?CliHelpStyleInterface $style = null): array
                 ) {
                     foreach ($option->AllowedValues ?: [true, false] as $optionValue) {
                         $optionValue = $option->normaliseValueForHelp($optionValue);
-                        $allowed[] = $em . Formatter::escapeTags($optionValue) . $em;
+                        $allowed[] = $em . Console::escape($optionValue) . $em;
                     }
                     if (!$option->AllowedValues) {
                         $booleanValue = true;
@@ -382,7 +381,7 @@ final public function getHelp(?CliHelpStyleInterface $style = null): array
                         $booleanValue
                         || mb_strlen($formatter->wrapsAfterFormatting()
                             ? $formatter->format($indent . $_line)
-                            : Formatter::removeTags($indent . $_line)) <= ($width ?: 76)
+                            : Console::removeTags($indent . $_line)) <= ($width ?: 76)
                     ) {
                         $allowed = null;
                     } else {
@@ -428,7 +427,7 @@ final public function getHelp(?CliHelpStyleInterface $style = null): array
                         continue;
                     }
                     $value = $option->normaliseValueForHelp($value);
-                    $default[] = $em . Formatter::escapeTags($value) . $em;
+                    $default[] = $em . Console::escape($value) . $em;
                 }
                 $default = implode(Str::coalesce($option->Delimiter, ' '), $default);
                 if ($default !== '') {
@@ -445,8 +444,8 @@ final public function getHelp(?CliHelpStyleInterface $style = null): array
                 . ($lines ? $descriptionPrefix . ltrim(implode("\n\n", $lines)) : '');
         }
 
-        $name = Formatter::escapeTags($this->getNameWithProgram());
-        $summary = Formatter::escapeTags($this->getDescription());
+        $name = Console::escape($this->getNameWithProgram());
+        $summary = Console::escape($this->getDescription());
         $synopsis = $this->getSynopsis($style);
 
         $description = $this->getLongDescription() ?? '';

src/Toolkit/Cli/CliHelpStyle.php

@@ -2,7 +2,6 @@
 
 namespace Salient\Cli;
 
-use Salient\Console\Format\Formatter;
 use Salient\Console\Format\LoopbackFormat;
 use Salient\Console\Format\ManPageFormat;
 use Salient\Console\Format\MarkdownFormat;
@@ -262,7 +261,7 @@ public function maybeEscapeTags(string $string): string
         if ($this->HasMarkup) {
             return $string;
         }
-        return Formatter::escapeTags($string);
+        return Console::escape($string);
     }
 
     public static function getConsoleWidth(): ?int

src/Toolkit/Console/Console.php

@@ -3,7 +3,6 @@
 namespace Salient\Console;
 
 use Psr\Log\LoggerInterface;
-use Salient\Console\Format\Formatter;
 use Salient\Console\Target\StreamTarget;
 use Salient\Contract\Console\Target\HasPrefix;
 use Salient\Contract\Console\Target\StreamTargetInterface;
@@ -224,7 +223,23 @@ public function getTtyTarget(): StreamTargetInterface
      */
     public function escape(string $string, bool $escapeNewlines = false): string
     {
-        return Formatter::escapeTags($string, $escapeNewlines);
+        return ConsoleUtil::escape($string, $escapeNewlines);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function removeEscapes(string $string): string
+    {
+        return ConsoleUtil::removeEscapes($string);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function removeTags(string $string): string
+    {
+        return ConsoleUtil::removeTags($string);
     }
 
     /**

src/Toolkit/Console/ConsoleLogger.php

@@ -10,7 +10,7 @@
 use Throwable;
 
 /**
- * A PSR-3 logger backed by a console service
+ * @api
  */
 class ConsoleLogger implements LoggerInterface
 {
@@ -27,6 +27,9 @@ class ConsoleLogger implements LoggerInterface
 
     private Console $Console;
 
+    /**
+     * @api
+     */
     public function __construct(Console $console)
     {
         $this->Console = $console;
@@ -93,7 +96,8 @@ public function info($message, array $context = [])
      */
     public function debug($message, array $context = [])
     {
-        $this->log(LogLevel::DEBUG, $message, $context);
+        $msg1 = $this->applyContext((string) $message, $context, $ex);
+        $this->Console->debug($msg1, null, $ex, 1);
     }
 
     /**
@@ -105,6 +109,16 @@ public function log($level, $message, array $context = [])
             throw new InvalidArgumentException('Invalid log level');
         }
 
+        $msg1 = $this->applyContext((string) $message, $context, $ex);
+        $level = self::LOG_LEVEL_MAP[$level];
+        $this->Console->message($msg1, null, $level, Console::TYPE_STANDARD, $ex);
+    }
+
+    /**
+     * @param mixed[] $context
+     */
+    private function applyContext(string $message, array $context, ?Throwable &$ex): string
+    {
         if ($context) {
             foreach ($context as $key => $value) {
                 $replace['{' . $key . '}'] = Format::value($value);
@@ -115,16 +129,10 @@ public function log($level, $message, array $context = [])
                 isset($context['exception'])
                 && $context['exception'] instanceof Throwable
             ) {
-                $exception = $context['exception'];
+                $ex = $context['exception'];
             }
         }
 
-        $this->Console->message(
-            (string) $message,
-            null,
-            self::LOG_LEVEL_MAP[$level],
-            Console::TYPE_STANDARD,
-            $exception ?? null,
-        );
+        return $message;
     }
 }