Merge branch 'close-console-targets'

Author: lkrms

src/Concept/Builder.php

@@ -51,7 +51,7 @@ protected static function getTerminators(): array
     private array $Data = [];
 
     /**
-     * Creates a new builder
+     * Creates a new Builder object
      */
     final public function __construct(?IContainer $container = null)
     {

src/Concept/Facade.php

@@ -6,6 +6,7 @@
 use Lkrms\Container\Container;
 use Lkrms\Contract\IFacade;
 use Lkrms\Contract\ReceivesFacade;
+use Lkrms\Contract\Unloadable;
 use Lkrms\Facade\Event;
 use Lkrms\Support\EventDispatcher;
 use LogicException;
@@ -42,7 +43,8 @@ private static function _load()
     {
         $service = static::getServiceName();
 
-        if ($container = Container::maybeGetGlobalContainer()) {
+        $container = Container::maybeGetGlobalContainer();
+        if ($container) {
             $instance = $container
                 ->singletonIf($service)
                 ->get($service, func_get_args());
@@ -96,22 +98,34 @@ final public static function load()
      */
     final public static function unload(): void
     {
-        if ($id = self::$ListenerIds[static::class] ?? null) {
+        $id = self::$ListenerIds[static::class] ?? null;
+        if ($id !== null) {
             Event::removeListener($id);
             unset(self::$ListenerIds[static::class]);
         }
-        if ($container = Container::maybeGetGlobalContainer()) {
+
+        $container = Container::maybeGetGlobalContainer();
+        if ($container) {
             $container->unbind(static::getServiceName());
         }
-        unset(self::$Instances[static::class]);
+
+        $instance = self::$Instances[static::class] ?? null;
+        if ($instance) {
+            if ($instance instanceof Unloadable) {
+                $instance->unload();
+            }
+            unset(self::$Instances[static::class]);
+        }
     }
 
     /**
      * Clear the underlying instances of all facades
      */
     final public static function unloadAll(): void
     {
-        self::$Instances = [];
+        foreach (array_keys(self::$Instances) as $class) {
+            $class::unload();
+        }
     }
 
     /**

src/Concept/Provider.php

@@ -20,7 +20,7 @@ abstract class Provider implements IProvider
     private DateFormatterInterface $DateFormatter;
 
     /**
-     * Creates a new provider object
+     * Creates a new Provider object
      */
     public function __construct(IContainer $app)
     {

src/Console/Concept/ConsolePrefixTarget.php

@@ -27,6 +27,8 @@ abstract protected function writeToTarget($level, string $message, array $contex
      */
     final public function write($level, string $message, array $context = []): void
     {
+        $this->assertIsValid();
+
         if ($this->Prefix === null) {
             $this->writeToTarget($level, $message, $context);
             return;
@@ -51,6 +53,8 @@ final public function setPrefix(?string $prefix)
             return $this;
         }
 
+        $this->assertIsValid();
+
         $this->PrefixLength = strlen($prefix);
         $this->Prefix = $this->getFormatter()->getTagFormat(Tag::LOW_PRIORITY)->apply($prefix);
 
@@ -62,6 +66,8 @@ final public function setPrefix(?string $prefix)
      */
     final public function getPrefix(): ?string
     {
+        $this->assertIsValid();
+
         return $this->Prefix;
     }
 
@@ -70,6 +76,8 @@ final public function getPrefix(): ?string
      */
     public function getWidth(): ?int
     {
+        $this->assertIsValid();
+
         return 80 - $this->PrefixLength;
     }
 }

src/Console/Concept/ConsoleTarget.php

@@ -19,6 +19,8 @@ abstract class ConsoleTarget implements ConsoleTargetInterface
      */
     public function getFormatter(): Formatter
     {
+        $this->assertIsValid();
+
         return $this->Formatter ??= new Formatter(
             $this->createTagFormats(),
             $this->createMessageFormats(),
@@ -31,9 +33,18 @@ public function getFormatter(): Formatter
      */
     public function getWidth(): ?int
     {
+        $this->assertIsValid();
+
         return null;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function close(): void {}
+
+    protected function assertIsValid(): void {}
+
     protected function createTagFormats(): TagFormats
     {
         return new TagFormats();

src/Console/ConsoleWriter.php

@@ -13,6 +13,7 @@
 use Lkrms\Console\ConsoleFormatter as Formatter;
 use Lkrms\Contract\IFacade;
 use Lkrms\Contract\ReceivesFacade;
+use Lkrms\Contract\Unloadable;
 use Lkrms\Exception\Contract\ExceptionInterface;
 use Lkrms\Exception\Contract\MultipleErrorExceptionInterface;
 use Lkrms\Exception\InvalidEnvironmentException;
@@ -34,7 +35,7 @@
  * {@see Console} facade. If a {@see ConsoleWriter} instance is required, call
  * {@see Console::getInstance()}.
  */
-final class ConsoleWriter implements ReceivesFacade
+final class ConsoleWriter implements ReceivesFacade, Unloadable
 {
     /**
      * @var array<Level::*,TargetStream[]>
@@ -56,6 +57,11 @@ final class ConsoleWriter implements ReceivesFacade
      */
     private array $Targets = [];
 
+    /**
+     * @var array<int,Target>
+     */
+    private array $DeregisteredTargets = [];
+
     /**
      * @var array<int,int-mask-of<TargetTypeFlag::*>>
      */
@@ -95,6 +101,14 @@ public function setFacade(string $name)
         return $this;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function unload(): void
+    {
+        $this->deregisterAllTargets();
+    }
+
     /**
      * Register a log file to receive console output
      *
@@ -196,7 +210,8 @@ public function registerStdioTargets(bool $replace = false)
         return $this
             ->clearStdioTargets()
             ->registerTarget($stderr, $stderrLevels)
-            ->registerTarget($stdout, $stdoutLevels);
+            ->registerTarget($stdout, $stdoutLevels)
+            ->closeDeregisteredTargets();
     }
 
     /**
@@ -243,7 +258,8 @@ private function registerStdioTarget(
 
         return $this
             ->clearStdioTargets()
-            ->registerTarget($target, $levels);
+            ->registerTarget($target, $levels)
+            ->closeDeregisteredTargets();
     }
 
     /**
@@ -256,11 +272,24 @@ private function clearStdioTargets()
         }
         $targets = $this->reduceTargets($this->StdioTargetsByLevel);
         foreach ($targets as $target) {
-            $this->deregisterTarget($target);
+            $this->onlyDeregisterTarget($target);
         }
         return $this;
     }
 
+    /**
+     * Close and deregister all registered targets
+     *
+     * @return $this
+     */
+    public function deregisterAllTargets()
+    {
+        foreach ($this->Targets as $target) {
+            $this->onlyDeregisterTarget($target);
+        }
+        return $this->closeDeregisteredTargets();
+    }
+
     /**
      * Register a target to receive console output
      *
@@ -313,11 +342,19 @@ public function registerTarget(
     }
 
     /**
-     * Deregister a previously registered target
+     * Close and deregister a previously registered target
      *
      * @return $this
      */
     public function deregisterTarget(Target $target)
+    {
+        return $this->onlyDeregisterTarget($target)->closeDeregisteredTargets();
+    }
+
+    /**
+     * @return $this
+     */
+    private function onlyDeregisterTarget(Target $target)
     {
         $targetId = spl_object_id($target);
 
@@ -344,6 +381,8 @@ public function deregisterTarget(Target $target)
             $this->StdoutTarget = null;
         }
 
+        $this->DeregisteredTargets[$targetId] = $target;
+
         // Reinstate previous STDOUT and STDERR targets if possible
         if (
             $this->Targets &&
@@ -372,7 +411,24 @@ public function deregisterTarget(Target $target)
     }
 
     /**
-     * Get a list of registered output targets
+     * @return $this
+     */
+    private function closeDeregisteredTargets()
+    {
+        // Reduce `$this->DeregisteredTargets` to targets not subsequently
+        // re-registered
+        $this->DeregisteredTargets = array_diff_key(
+            $this->DeregisteredTargets, $this->Targets
+        );
+        foreach ($this->DeregisteredTargets as $i => $target) {
+            $target->close();
+            unset($this->DeregisteredTargets[$i]);
+        }
+        return $this;
+    }
+
+    /**
+     * Get a list of registered targets
      *
      * @return Target[]
      */
@@ -468,7 +524,7 @@ private function maybeGetTtyTarget($level): TargetStream
     public function getStdoutTarget(): TargetStream
     {
         if (!$this->StdoutTarget) {
-            return $this->StdoutTarget = new StreamTarget(\STDOUT);
+            return $this->StdoutTarget = StreamTarget::fromStream(\STDOUT);
         }
         return $this->StdoutTarget;
     }
@@ -479,7 +535,7 @@ public function getStdoutTarget(): TargetStream
     public function getStderrTarget(): TargetStream
     {
         if (!$this->StderrTarget) {
-            return $this->StderrTarget = new StreamTarget(\STDERR);
+            return $this->StderrTarget = StreamTarget::fromStream(\STDERR);
         }
         return $this->StderrTarget;
     }

src/Console/Contract/ConsoleTargetInterface.php

@@ -37,4 +37,9 @@ public function getWidth(): ?int;
      * @param array<string,mixed> $context
      */
     public function write($level, string $message, array $context = []): void;
+
+    /**
+     * Close the target and any underlying resources
+     */
+    public function close(): void;
 }

src/Console/Contract/ConsoleTargetStreamInterface.php

@@ -23,4 +23,9 @@ public function isStderr(): bool;
      * True if the target writes to a TTY
      */
     public function isTty(): bool;
+
+    /**
+     * Close and reopen the underlying PHP stream if possible
+     */
+    public function reopen(): void;
 }

src/Console/Exception/ConsoleInvalidTargetException.php

@@ -0,0 +1,11 @@
+<?php declare(strict_types=1);
+
+namespace Lkrms\Console\Exception;
+
+use Lkrms\Exception\Exception;
+
+/**
+ * Thrown when a console output target receives a message after closing its
+ * underlying resources
+ */
+class ConsoleInvalidTargetException extends Exception {}