Merge branch 'refactor-facade'

Author: lkrms

lk-util/Command/Generate/GenerateFacade.php

@@ -23,10 +23,12 @@ final class GenerateFacade extends GenerateCommand
     private const SKIP_METHODS = [
         'getReadable',
         'getWritable',
-        'setFacade',
+        'withFacade',
+        'withoutFacade',
         // These are displaced by Facade
         'isLoaded',
         'load',
+        'swap',
         'unload',
         'unloadAll',
         'getInstance',
@@ -123,10 +125,11 @@ protected function run(string ...$args)
                         : $a->getName() <=> $b->getName())
         );
         $facadeMethods = [
-            " * @method static $service load() Load and return an instance of the underlying $classClass class",
-            " * @method static $service getInstance() Get the underlying $classClass instance",
-            " * @method static bool isLoaded() True if an underlying $classClass instance has been loaded",
-            " * @method static void unload() Clear the underlying $classClass instance",
+            " * @method static bool isLoaded() True if the facade's underlying instance is loaded",
+            " * @method static void load($service|null \$instance = null) Load the facade's underlying instance",
+            " * @method static void swap($service \$instance) Replace the facade's underlying instance",
+            " * @method static void unload() Remove the facade's underlying instance if loaded",
+            " * @method static $service getInstance() Get the facade's underlying instance, loading it if necessary",
         ];
         $methods = [];
         $toDeclare = [];
@@ -153,10 +156,7 @@ protected function run(string ...$args)
             $returnsVoid = false;
 
             if ($_method->isConstructor()) {
-                $method = 'load';
-                $type = $service;
-                $summary = "Load and return an instance of the underlying $classClass class";
-                unset($facadeMethods[0]);
+                continue;
             } else {
                 if (isset($phpDoc->TagsByName['deprecated'])) {
                     continue;
@@ -251,7 +251,7 @@ protected function run(string ...$args)
                         );
             }
 
-            if (!$methods && !$_method->isConstructor()) {
+            if (!$methods) {
                 array_push($methods, ...$facadeMethods);
             }
 
@@ -289,10 +289,6 @@ protected function run(string ...$args)
                     . str_replace(\PHP_EOL, \PHP_EOL . ' * ', implode(', ', $params)) . ')'
                     . " $summary";
             }
-
-            if ($_method->isConstructor()) {
-                array_push($methods, ...$facadeMethods);
-            }
         }
         $methods = implode(\PHP_EOL, $methods);
 
@@ -338,7 +334,7 @@ protected function run(string ...$args)
         array_push(
             $lines,
             ...$this->indent($this->generateGetter(
-                'getServiceName',
+                'getService',
                 "$service::class",
                 '@inheritDoc',
                 'string',

src/Concept/Facade.php

@@ -2,95 +2,88 @@
 
 namespace Lkrms\Concept;
 
+use Lkrms\Concern\ResolvesServiceLists;
 use Lkrms\Container\Event\GlobalContainerSetEvent;
 use Lkrms\Container\Container;
-use Lkrms\Contract\IFacade;
-use Lkrms\Contract\ReceivesFacade;
+use Lkrms\Contract\FacadeAwareInterface;
+use Lkrms\Contract\FacadeInterface;
+use Lkrms\Contract\IContainer;
 use Lkrms\Contract\Unloadable;
 use Lkrms\Facade\Event;
 use Lkrms\Support\EventDispatcher;
+use Lkrms\Utility\Get;
 use LogicException;
 
 /**
  * Base class for facades
  *
- * @template TClass of object
- * @implements IFacade<TClass>
+ * @template TService of object
+ *
+ * @implements FacadeInterface<TService>
  */
-abstract class Facade implements IFacade
+abstract class Facade implements FacadeInterface
 {
+    /** @use ResolvesServiceLists<TService> */
+    use ResolvesServiceLists;
+
     /**
-     * Get the name of the underlying class
+     * Get the facade's underlying class, or an array that maps its underlying
+     * class to compatible implementations
+     *
+     * At least one of the values returned should be an instantiable class that
+     * is guaranteed to exist.
      *
-     * @return class-string<TClass>
+     * @return class-string<TService>|array<class-string<TService>,class-string<TService>|array<class-string<TService>>>
      */
-    abstract protected static function getServiceName(): string;
+    abstract protected static function getService();
 
     /**
-     * @var array<string,object>
+     * @var array<class-string<static>,TService>
      */
-    private static $Instances = [];
+    private static array $Instances = [];
 
     /**
-     * @var array<string,int>
+     * @var array<class-string<static>,int>
      */
-    private static $ListenerIds = [];
+    private static array $ListenerIds = [];
 
     /**
-     * @return TClass
+     * @internal
      */
-    private static function _load()
+    final public static function isLoaded(): bool
     {
-        $service = static::getServiceName();
-
-        $container = Container::maybeGetGlobalContainer();
-        if ($container) {
-            $instance = $container
-                ->singletonIf($service)
-                ->get($service, func_get_args());
-        } else {
-            $instance = new $service(...func_get_args());
-        }
+        return isset(self::$Instances[static::class]);
+    }
 
-        if ($instance instanceof ReceivesFacade) {
-            $instance->setFacade(static::class);
+    /**
+     * @internal
+     */
+    final public static function load(?object $instance = null): void
+    {
+        if (isset(self::$Instances[static::class])) {
+            throw new LogicException(sprintf('Already loaded: %s', static::class));
         }
 
-        $dispatcher = $instance instanceof EventDispatcher
-            ? $instance
-            : Event::getInstance();
-        $id = $dispatcher->listen(
-            function (GlobalContainerSetEvent $event) use ($service, $instance): void {
-                $container = $event->container();
-                if ($container) {
-                    $container->instanceIf($service, $instance);
-                }
-            }
-        );
-        self::$ListenerIds[static::class] = $id;
-
-        return self::$Instances[static::class] = $instance;
+        self::$Instances[static::class] = self::doLoad($instance);
     }
 
     /**
      * @internal
      */
-    final public static function isLoaded(): bool
+    final public static function swap(object $instance): void
     {
-        return isset(self::$Instances[static::class]);
+        self::unload();
+        self::$Instances[static::class] = self::doLoad($instance);
     }
 
     /**
-     * @internal
-     * @return TClass
+     * Remove the underlying instances of all facades
      */
-    final public static function load()
+    final public static function unloadAll(): void
     {
-        if (isset(self::$Instances[static::class])) {
-            throw new LogicException(static::class . ' already loaded');
+        foreach (array_keys(self::$Instances) as $class) {
+            $class::unload();
         }
-
-        return self::_load(...func_get_args());
     }
 
     /**
@@ -104,37 +97,46 @@ final public static function unload(): void
             unset(self::$ListenerIds[static::class]);
         }
 
+        $instance = self::$Instances[static::class] ?? null;
+        if (!$instance) {
+            return;
+        }
+
         $container = Container::maybeGetGlobalContainer();
         if ($container) {
-            $container->unbind(static::getServiceName());
+            $serviceName = self::getServiceName();
+            if (
+                $container->hasInstance($serviceName) &&
+                $container->get($serviceName) === $instance
+            ) {
+                $container->unbind($serviceName);
+            }
         }
 
-        $instance = self::$Instances[static::class] ?? null;
-        if ($instance) {
-            if ($instance instanceof Unloadable) {
-                $instance->unload();
-            }
-            unset(self::$Instances[static::class]);
+        if ($instance instanceof FacadeAwareInterface) {
+            $instance = $instance->withoutFacade(static::class, true);
         }
-    }
 
-    /**
-     * Clear the underlying instances of all facades
-     */
-    final public static function unloadAll(): void
-    {
-        foreach (array_keys(self::$Instances) as $class) {
-            $class::unload();
+        if ($instance instanceof Unloadable) {
+            $instance->unload();
         }
+
+        unset(self::$Instances[static::class]);
     }
 
     /**
      * @internal
-     * @return TClass
      */
     final public static function getInstance()
     {
-        return self::$Instances[static::class] ?? self::_load();
+        $instance = self::$Instances[static::class]
+            ??= self::doLoad();
+
+        if ($instance instanceof FacadeAwareInterface) {
+            return $instance->withoutFacade(static::class, false);
+        }
+
+        return $instance;
     }
 
     /**
@@ -144,6 +146,109 @@ final public static function getInstance()
      */
     final public static function __callStatic(string $name, array $arguments)
     {
-        return (self::$Instances[static::class] ?? self::_load())->$name(...$arguments);
+        return (self::$Instances[static::class]
+            ??= self::doLoad())->$name(...$arguments);
+    }
+
+    /**
+     * @param TService|null $instance
+     * @return TService
+     */
+    private static function doLoad($instance = null)
+    {
+        $serviceName = self::getServiceName();
+
+        if ($instance !== null && (
+            !is_object($instance) || !is_a($instance, $serviceName)
+        )) {
+            throw new LogicException(sprintf(
+                '%s does not inherit %s',
+                Get::type($instance),
+                $serviceName,
+            ));
+        }
+
+        $container = Container::maybeGetGlobalContainer();
+
+        $instance ??= $container
+            ? self::getInstanceFromContainer($container, $serviceName)
+            : self::createInstance();
+
+        if ($container) {
+            $container->instanceIf($serviceName, $instance);
+        }
+
+        $dispatcher = $instance instanceof EventDispatcher
+            ? $instance
+            : Event::getInstance();
+
+        $id = $dispatcher->listen(
+            static function (GlobalContainerSetEvent $event) use ($serviceName, $instance): void {
+                $container = $event->container();
+                if ($container) {
+                    $container->instanceIf($serviceName, $instance);
+                }
+            }
+        );
+        self::$ListenerIds[static::class] = $id;
+
+        if ($instance instanceof FacadeAwareInterface) {
+            $instance = $instance->withFacade(static::class);
+        }
+
+        return $instance;
+    }
+
+    /**
+     * @return TService
+     */
+    private static function getInstanceFromContainer(
+        IContainer $container,
+        string $serviceName
+    ) {
+        // If one of the services returned by the facade has been bound to the
+        // container, resolve it to an instance
+        foreach (self::getServiceList() as $service) {
+            if ($container->has($service)) {
+                $instance = $container->getAs($service, $serviceName);
+                if (!is_a($instance, $serviceName)) {
+                    throw new LogicException(sprintf(
+                        '%s does not inherit %s: %s::getService()',
+                        get_class($instance),
+                        $serviceName,
+                        static::class,
+                    ));
+                }
+                return $instance;
+            }
+        }
+
+        // Otherwise, use the container to resolve the first instantiable class
+        $service = self::getInstantiableService();
+        if ($service !== null) {
+            return $container->getAs($service, $serviceName);
+        }
+
+        throw new LogicException(sprintf(
+            'Service not bound to container: %s::getService()',
+            static::class,
+        ));
+    }
+
+    /**
+     * @return TService
+     */
+    private static function createInstance()
+    {
+        // Create an instance of the first instantiable class
+        $service = self::getInstantiableService();
+        if ($service !== null) {
+            return new $service();
+        }
+
+        throw new LogicException(sprintf(
+            'Service not instantiable: %s::getService()',
+            static::class,
+        ));
     }
 }