Sync: review provider context handling

- Add provider to `IProviderContext`
- Add `getContext()` to `IProvider`
- Simplify context propagation in `TProvidable`, `Introspector`,
  `SyncEntity`, `SyncProvider`, `SyncEntityProvider`,
  `SyncIntrospector`
- Remove unused `set()` and `get()` methods from `IProviderContext`

Also:
- Fix `SyncStore` issue where `IFacade::unload()` is not always called
  on `close()`
- Rename `SyncSerializeLinkType` to `SyncEntityLinkType`

Author: lkrms

phpstan-baseline.neon

@@ -100,31 +100,6 @@ parameters:
 			count: 1
 			path: src/Contract/IProvider.php
 
-		-
-			message: "#^Interface Lkrms\\\\Contract\\\\IProviderContext extends generic interface Lkrms\\\\Contract\\\\ReturnsContainer but does not specify its types\\: T$#"
-			count: 1
-			path: src/Contract/IProviderContext.php
-
-		-
-			message: "#^Method Lkrms\\\\Contract\\\\IProviderContext\\:\\:get\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: src/Contract/IProviderContext.php
-
-		-
-			message: "#^Method Lkrms\\\\Contract\\\\IProviderContext\\:\\:getStack\\(\\) return type with generic interface Lkrms\\\\Contract\\\\IProvidable does not specify its types\\: TProvider, TProviderContext$#"
-			count: 1
-			path: src/Contract/IProviderContext.php
-
-		-
-			message: "#^Method Lkrms\\\\Contract\\\\IProviderContext\\:\\:push\\(\\) has parameter \\$entity with generic interface Lkrms\\\\Contract\\\\IProvidable but does not specify its types\\: TProvider, TProviderContext$#"
-			count: 1
-			path: src/Contract/IProviderContext.php
-
-		-
-			message: "#^Method Lkrms\\\\Contract\\\\IProviderContext\\:\\:set\\(\\) has parameter \\$value with no type specified\\.$#"
-			count: 1
-			path: src/Contract/IProviderContext.php
-
 		-
 			message: "#^Method Lkrms\\\\Contract\\\\IReadable\\:\\:__get\\(\\) has no return type specified\\.$#"
 			count: 1
@@ -350,31 +325,6 @@ parameters:
 			count: 1
 			path: src/Store/TrashStore.php
 
-		-
-			message: "#^Method Lkrms\\\\Support\\\\ProviderContext\\:\\:get\\(\\) has no return type specified\\.$#"
-			count: 1
-			path: src/Support/ProviderContext.php
-
-		-
-			message: "#^Method Lkrms\\\\Support\\\\ProviderContext\\:\\:getStack\\(\\) return type with generic interface Lkrms\\\\Contract\\\\IProvidable does not specify its types\\: TProvider, TProviderContext$#"
-			count: 1
-			path: src/Support/ProviderContext.php
-
-		-
-			message: "#^Method Lkrms\\\\Support\\\\ProviderContext\\:\\:push\\(\\) has parameter \\$entity with generic interface Lkrms\\\\Contract\\\\IProvidable but does not specify its types\\: TProvider, TProviderContext$#"
-			count: 1
-			path: src/Support/ProviderContext.php
-
-		-
-			message: "#^Method Lkrms\\\\Support\\\\ProviderContext\\:\\:set\\(\\) has parameter \\$value with no type specified\\.$#"
-			count: 1
-			path: src/Support/ProviderContext.php
-
-		-
-			message: "#^Property Lkrms\\\\Support\\\\ProviderContext\\:\\:\\$Stack with generic interface Lkrms\\\\Contract\\\\IProvidable does not specify its types\\: TProvider, TProviderContext$#"
-			count: 1
-			path: src/Support/ProviderContext.php
-
 		-
 			message: "#^Property Lkrms\\\\Sync\\\\Support\\\\SyncEntityProvider\\:\\:\\$Offline is never read, only written\\.$#"
 			count: 1

src/Concept/Provider.php

@@ -4,8 +4,10 @@
 
 use Lkrms\Contract\IContainer;
 use Lkrms\Contract\IProvider;
+use Lkrms\Contract\IProviderContext;
 use Lkrms\Exception\MethodNotImplementedException;
 use Lkrms\Support\DateFormatter;
+use Lkrms\Support\ProviderContext;
 use Lkrms\Utility\Env;
 
 /**
@@ -46,6 +48,20 @@ public function description(): ?string
         return null;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function getContext(?IContainer $container = null): IProviderContext
+    {
+        if (!$container) {
+            $container = $this->App;
+        }
+
+        return $container
+            ->bindIf(IProviderContext::class, ProviderContext::class)
+            ->get(IProviderContext::class, [$this]);
+    }
+
     /**
      * @inheritDoc
      */

src/Concern/TProvidable.php

@@ -9,7 +9,6 @@
 use Lkrms\Support\Iterator\Contract\FluentIteratorInterface;
 use Lkrms\Support\Iterator\IterableIterator;
 use Lkrms\Support\Introspector;
-use Lkrms\Support\ProviderContext;
 use Generator;
 use LogicException;
 
@@ -151,9 +150,7 @@ final public static function provide(
 
         $context = $context
             ? $context->withContainer($container)
-            : $container
-                ->bindIf(IProviderContext::class, ProviderContext::class)
-                ->get(IProviderContext::class);
+            : $provider->getContext($container);
 
         $closure = Introspector::getService(
             $container, static::class
@@ -206,9 +203,7 @@ private static function _provideList(
         /** @var IProviderContext */
         $context = $context
             ? $context->withContainer($container)
-            : $container
-                ->bindIf(IProviderContext::class, ProviderContext::class)
-                ->get(IProviderContext::class);
+            : $provider->getContext($container);
         $context = $context->withConformity($conformity);
 
         $introspector = Introspector::getService($container, static::class);

src/Contract/IProvider.php

@@ -11,6 +11,12 @@
  */
 interface IProvider extends ReturnsContainer, ReturnsEnvironment, ReturnsDescription
 {
+    /**
+     * Get a context for instantiation of objects on the provider's behalf
+     *
+     */
+    public function getContext(?IContainer $container = null): IProviderContext;
+
     /**
      * Get a stable list of values that, together with the name of the class,
      * uniquely identifies the backend instance

src/Contract/IProviderContext.php

@@ -5,57 +5,50 @@
 use Lkrms\Support\Catalog\ArrayKeyConformity;
 
 /**
- * The context within which an IProvidable is instantiated
+ * The context within which an entity is instantiated by a provider
  *
+ * @extends ReturnsContainer<IContainer>
+ * @extends ReturnsProvider<IProvider>
  */
-interface IProviderContext extends IImmutable, ReturnsContainer
+interface IProviderContext extends IImmutable, ReturnsContainer, ReturnsProvider
 {
     /**
-     * Apply an arbitrary value to the context
+     * Apply a container to the context
      *
      * @return $this
      */
-    public function set(string $key, $value);
+    public function withContainer(IContainer $container);
 
     /**
-     * Push the entity propagating this context onto the stack
+     * Push the entity propagating the context onto the stack
      *
      * Note that although the same entity may be passed to both
      * {@see IProviderContext::push()} and {@see IProviderContext::withParent()}
-     * (e.g. when a hierarchy is being populated from a root entity), they have
-     * completely different purposes.
-     *
-     * A `Post` object, for example, would `push()` itself onto the entity stack
-     * to retrieve a `User` instance for its `Author` property. The `Post` has a
-     * reference to a `User`, but is not its parent because the reference is not
-     * hierarchical. (Also, only a `User` entity can be the parent or child of
-     * another `User` entity.)
+     * (e.g. when a hierarchy is being populated from a root entity), they serve
+     * different purposes.
      *
-     * A `Staff` object, however, would `push()` itself onto the entity stack to
-     * retrieve `Staff` instances for its `DirectReports` property, **and** pass
-     * itself to `withParent()` as the parent (a.k.a. manager) of those `Staff`.
+     * Example: a `Post` object would `push()` itself onto the entity stack to
+     * retrieve a `User` instance for its `Author` property, but a `Staff`
+     * object would `push()` itself onto the entity stack to retrieve `Staff`
+     * instances for its `DirectReports` property, **and** pass itself to
+     * `withParent()` as the parent (a.k.a. manager) of those `Staff`.
      *
+     * @param IProvidable<IProvider,IProviderContext> $entity
      * @return $this
      */
     public function push(IProvidable $entity);
 
     /**
-     * Set the context's container
-     *
-     * @return $this
-     */
-    public function withContainer(IContainer $container);
-
-    /**
-     * Set the parent of ITreeable entities instantiated within the context
+     * Apply a parent entity to the context
      *
      * @see IProviderContext::push()
+     *
      * @return $this
      */
     public function withParent(?ITreeable $parent);
 
     /**
-     * Propagate the current payload's array key conformity
+     * Apply the current payload's array key conformity to the context
      *
      * @param ArrayKeyConformity::* $conformity Use
      * {@see ArrayKeyConformity::COMPLETE} wherever possible to improve
@@ -65,20 +58,19 @@ public function withParent(?ITreeable $parent);
     public function withConformity($conformity);
 
     /**
-     * Get the value most recently passed to set($key)
-     *
+     * @inheritDoc
      */
-    public function get(string $key);
+    public function provider(): IProvider;
 
     /**
      * Get the entities responsible for propagating this context
      *
-     * @return IProvidable[]
+     * @return IProvidable<IProvider,IProviderContext>[]
      */
-    public function getStack(): array;
+    public function stack(): array;
 
     /**
-     * Get the value most recently passed to withParent()
+     * Get the parent entity applied to the context
      *
      */
     public function getParent(): ?ITreeable;

src/Support/Introspector.php

@@ -206,19 +206,23 @@ final public function getCreateProvidableFromSignatureClosure(array $keys, bool
 
         return
             static function (array $array, IProvider $provider, $context = null) use ($closure, $service) {
-                [$container, $parent] =
-                    $context instanceof IProviderContext
-                        ? [$context->container(), $context->getParent()]
-                        : [$context ?: $provider->container(), null];
+                if ($context instanceof IProviderContext) {
+                    $container = $context->container();
+                    $parent = $context->getParent();
+                } else {
+                    /** @var IContainer */
+                    $container = $context ?? $provider->container();
+                    $context = $provider->getContext($container);
+                }
 
                 return $closure(
                     $array,
                     $service,
                     $container,
                     $provider,
-                    $context ?: new ProviderContext($container, $parent),
+                    $context,
                     $provider->dateFormatter(),
-                    $parent,
+                    $parent ?? null,
                 );
             };
     }