Fix AbstractFacade::unload() issues and improve documentation

- Fix issue where `HasFacade` doesn't remove references to cloned
  instances when unloaded
- Fix issue where service container bindings are forgotten when a
  facade's underlying instance is removed from a container
- Add service container methods `hasSingleton()` and `unbindInstance()`
- Leave `unload()`ed containers in a usable state
- Add tests

Author: lkrms

src/Toolkit/Core/AbstractFacade.php

@@ -129,7 +129,7 @@ final public static function unload(): void
                     $container->hasInstance($serviceName) &&
                     $container->get($serviceName) === $instance
                 ) {
-                    $container->unbind($serviceName);
+                    $container->unbindInstance($serviceName);
                 }
             }
         }

src/Toolkit/Core/Concern/HasFacade.php

@@ -89,7 +89,10 @@ final public function withoutFacade(string $facade, bool $unloading)
 
         // Keep a copy of the cloned instance for future reuse if the facade is
         // not being unloaded
-        if (!$unloading) {
+        if ($unloading) {
+            $instance->InstanceWithoutFacade = null;
+            $instance->InstanceWithFacade = null;
+        } else {
             $instance->InstanceWithoutFacade = $instance;
             $instance->InstanceWithFacade = $this;
         }

src/Toolkit/Core/Contract/FacadeInterface.php

@@ -7,11 +7,6 @@
 /**
  * Provides a static interface to an underlying instance
  *
- * Underlying instances that implement {@see FacadeAwareInterface} are replaced
- * with the object returned by {@see FacadeAwareInterface::withFacade()}, and
- * its {@see FacadeAwareInterface::withoutFacade()} method is used to service
- * the facade's {@see swap()}, {@see unload()} and {@see getInstance()} methods.
- *
  * @api
  *
  * @template TService of object
@@ -28,6 +23,10 @@ public static function isLoaded(): bool;
      *
      * If `$instance` is `null`, the facade creates a new underlying instance.
      *
+     * Then, if the instance implements {@see FacadeAwareInterface}, it is
+     * replaced with the return value of
+     * {@see FacadeAwareInterface::withFacade()}.
+     *
      * @param TService|null $instance
      * @throws LogicException if the facade's underlying instance is already
      * loaded.
@@ -37,12 +36,22 @@ public static function load(?object $instance = null): void;
     /**
      * Replace the facade's underlying instance
      *
+     * Equivalent to calling {@see unload()} before passing `$instance` to
+     * {@see load()}.
+     *
      * @param TService $instance
      */
     public static function swap(object $instance): void;
 
     /**
      * Remove the facade's underlying instance if loaded
+     *
+     * If the underlying instance implements {@see FacadeAwareInterface}, it is
+     * replaced with the return value of
+     * {@see FacadeAwareInterface::withoutFacade()}.
+     *
+     * Then, if the instance implements {@see Unloadable}, its
+     * {@see Unloadable::unload()} method is called.
      */
     public static function unload(): void;
 

src/Util/Container/Container.php

@@ -77,10 +77,12 @@ public function unload(): void
     {
         if (self::$GlobalContainer === $this) {
             self::setGlobalContainer(null);
-            $this->unloadFacades();
         }
 
-        unset($this->Dice);
+        $this->unloadFacades();
+
+        $this->Dice = new Dice();
+        $this->bindContainer();
     }
 
     private function bindContainer(): void
@@ -258,6 +260,17 @@ final public function has(string $id): bool
         return $this->Dice->hasRule($id) || $this->Dice->hasShared($id);
     }
 
+    /**
+     * @inheritDoc
+     */
+    final public function hasSingleton(string $id): bool
+    {
+        return $this->Dice->hasShared($id) || (
+            $this->Dice->hasRule($id) &&
+            ($this->Dice->getRule($id)['shared'] ?? false)
+        );
+    }
+
     /**
      * @inheritDoc
      */
@@ -647,6 +660,25 @@ final public function unbind(string $id): self
         return $this;
     }
 
+    /**
+     * @inheritDoc
+     */
+    final public function unbindInstance(string $id): self
+    {
+        if (!$this->Dice->hasShared($id)) {
+            return $this;
+        }
+
+        if ($this->Dice->hasRule($id)) {
+            // Reapplying the rule removes the instance
+            $this->Dice = $this->Dice->addRule($id, $this->Dice->getRule($id));
+            return $this;
+        }
+
+        $this->Dice = $this->Dice->removeRule($id);
+        return $this;
+    }
+
     /**
      * 0 if another container has the same bindings, otherwise 1
      *

src/Util/Container/ContainerInterface.php

@@ -41,12 +41,12 @@
 interface ContainerInterface extends PsrContainerInterface, Unloadable
 {
     /**
-     * Creates a new service container object
+     * Creates a new service container
      */
     public function __construct();
 
     /**
-     * True if the global container is set
+     * Check if the global container is set
      */
     public static function hasGlobalContainer(): bool;
 
@@ -117,28 +117,35 @@ public function getAs(string $id, string $service, array $args = []): object;
     public function getName(string $id): string;
 
     /**
-     * True if a service is bound to the container
+     * Check if a service is bound to the container
      *
      * @param class-string $id
      */
     public function has(string $id): bool;
 
     /**
-     * True if a service provider is registered with the container
+     * Check if a service provider is registered with the container
      *
      * @param class-string $id
      */
     public function hasProvider(string $id): bool;
 
     /**
-     * True if a service resolves to a shared instance
+     * Check if a shared service is bound to the container
+     *
+     * @param class-string $id
+     */
+    public function hasSingleton(string $id): bool;
+
+    /**
+     * Check if a service resolves to a shared instance
      *
      * @param class-string $id
      */
     public function hasInstance(string $id): bool;
 
     /**
-     * Register a binding with the container
+     * Bind a service to the container
      *
      * Subsequent requests for `$id` resolve to `$class`.
      *
@@ -162,7 +169,7 @@ public function bind(
     ): self;
 
     /**
-     * Register a binding with the container if it isn't already registered
+     * Bind a service to the container if it isn't already bound
      *
      * @template TService of object
      * @template T of TService
@@ -179,7 +186,7 @@ public function bindIf(
     ): self;
 
     /**
-     * Register a shared binding with the container
+     * Bind a shared service to the container
      *
      * Subsequent requests for `$id` resolve to the instance of `$class` created
      * when `$id` is first requested.
@@ -199,8 +206,7 @@ public function singleton(
     ): self;
 
     /**
-     * Register a shared binding with the container if it isn't already
-     * registered
+     * Bind a shared service to the container if it isn't already bound
      *
      * @template TService of object
      * @template T of TService
@@ -296,7 +302,7 @@ public function providers(
     public function getProviders(): array;
 
     /**
-     * Register an object with the container as a shared binding
+     * Bind a shared instance to the container
      *
      * @template TService of object
      * @template T of TService
@@ -308,8 +314,7 @@ public function getProviders(): array;
     public function instance(string $id, $instance): self;
 
     /**
-     * Register an object with the container as a shared binding if it isn't
-     * already registered
+     * Bind a shared instance to the container if it isn't already bound
      *
      * @template TService of object
      * @template T of TService
@@ -327,4 +332,12 @@ public function instanceIf(string $id, $instance): self;
      * @return $this
      */
     public function unbind(string $id): self;
+
+    /**
+     * Remove a shared instance from the container
+     *
+     * @param class-string $id
+     * @return $this
+     */
+    public function unbindInstance(string $id): self;
 }

src/Util/Facade/App.php

@@ -1,8 +1,9 @@
 <?php declare(strict_types=1);
 
-namespace Lkrms\Tests\Concept;
+namespace Salient\Tests\Core;
 
 use Lkrms\Container\Container;
+use Lkrms\Facade\App;
 use Lkrms\Facade\Event;
 use Lkrms\Tests\Concept\Facade\MyBrokenFacade;
 use Lkrms\Tests\Concept\Facade\MyClassFacade;
@@ -14,11 +15,12 @@
 use Lkrms\Tests\TestCase;
 use Salient\Core\AbstractFacade;
 use LogicException;
+use stdClass;
 
 /**
- * @covers \Lkrms\Concept\Facade
+ * @covers \Salient\Core\AbstractFacade
  */
-final class FacadeTest extends TestCase
+final class AbstractFacadeTest extends TestCase
 {
     public function testBrokenFacade(): void
     {
@@ -139,6 +141,66 @@ public function testLoadWithContainerBindings(): void
         $this->assertNotSame($instance1, $instance3);
     }
 
+    public function testLoadWithInvalidBinding(): void
+    {
+        $container = Container::getGlobalContainer();
+        $container->bind(MyServiceInterface::class, stdClass::class);
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage(' does not inherit ');
+        MyInterfaceFacade::load();
+    }
+
+    public function testGlobalContainerIsSetAndUnloaded(): void
+    {
+        $this->assertFalse(Container::hasGlobalContainer());
+        $this->assertFalse(App::isLoaded());
+        App::get(stdClass::class);
+        $this->assertTrue(Container::hasGlobalContainer());
+        $this->assertTrue(App::isLoaded());
+        $container = Container::getGlobalContainer();
+        $this->assertSame($container, App::getInstance());
+        App::unload();
+        $this->assertFalse(Container::hasGlobalContainer());
+        $this->assertFalse(App::isLoaded());
+    }
+
+    public function testGlobalContainerIsNotReplaced(): void
+    {
+        $container = Container::getGlobalContainer();
+        $this->assertFalse($container->has(MyServiceClass::class));
+        MyClassFacade::load();
+        $this->assertTrue($container->has(MyServiceClass::class));
+        $this->assertFalse(App::isLoaded());
+        App::get(stdClass::class);
+        $this->assertTrue(App::isLoaded());
+        $this->assertSame($container, App::getInstance());
+        App::unload();
+        $this->assertFalse(Container::hasGlobalContainer());
+        $this->assertFalse(App::isLoaded());
+        $this->assertFalse($container->has(MyServiceClass::class));
+    }
+
+    public function testGlobalContainerBindingsAreMaintained(): void
+    {
+        MyClassFacade::load();
+        $this->assertFalse(Container::hasGlobalContainer());
+        $container = Container::getGlobalContainer();
+        $container2 = new Container();
+        $this->assertTrue($container->has(MyServiceClass::class));
+        $this->assertFalse($container2->has(MyServiceClass::class));
+
+        $this->assertFalse(App::isLoaded());
+        App::get(stdClass::class);
+        $this->assertTrue(App::isLoaded());
+        $this->assertSame($container, App::getInstance());
+
+        Container::setGlobalContainer($container2);
+        $this->assertTrue(App::isLoaded());
+        $this->assertSame($container2, App::getInstance());
+        $this->assertTrue($container2->has(MyServiceClass::class));
+        $this->assertFalse($container->has(MyServiceClass::class));
+    }
+
     protected function tearDown(): void
     {
         AbstractFacade::unloadAll();