Sync: defer registration of entity types, fix bootstrapping issues

- Add `Sync::getProviderId()`, which returns a value even if it has to
  start a run to do so
- In `DeferredSyncEntity`, register entity types before deferring them
- Update `Sync` facade

Author: lkrms

src/Facade/Sync.php

@@ -7,6 +7,7 @@
 use Lkrms\Sync\Contract\ISyncClassResolver;
 use Lkrms\Sync\Contract\ISyncEntity;
 use Lkrms\Sync\Contract\ISyncProvider;
+use Lkrms\Sync\Support\DeferredSyncEntity;
 use Lkrms\Sync\Support\SyncError;
 use Lkrms\Sync\Support\SyncErrorBuilder as ErrorBuilder;
 use Lkrms\Sync\Support\SyncErrorCollection;
@@ -21,13 +22,17 @@
  * @method static void unload() Clear the underlying SyncStore instance
  * @method static SyncStore checkHeartbeats(int $ttl = 300, bool $failEarly = true, ISyncProvider ...$providers) Throw an exception if a provider has an unreachable backend (see {@see SyncStore::checkHeartbeats()})
  * @method static SyncStore close(?int $exitStatus = 0) Terminate the current run and close the database
- * @method static SyncStore entityType(class-string<ISyncEntity> $entity) Register a sync entity type and set its ID (unless already registered)
+ * @method static SyncStore deferredEntity(int $providerId, class-string<ISyncEntity> $entityType, int|string $entityId, DeferredSyncEntity $deferred) Register a deferred sync entity (see {@see SyncStore::deferredEntity()})
+ * @method static SyncStore entity(int $providerId, class-string<ISyncEntity> $entityType, int|string $entityId, ISyncEntity $entity) Register a sync entity (see {@see SyncStore::entity()})
+ * @method static SyncStore entityType(class-string<ISyncEntity> $entity) Register a sync entity type and set its ID (unless already registered) (see {@see SyncStore::entityType()})
  * @method static SyncStore error(SyncError|ErrorBuilder $error, bool $deduplicate = false, bool $toConsole = false) Report an error that occurred during a sync operation
+ * @method static ISyncEntity|null getEntity(int $providerId, class-string<ISyncEntity> $entityType, int|string $entityId) Get a previously registered sync entity
  * @method static string|null getEntityTypeNamespace(class-string<ISyncEntity> $entity) Get the namespace of a sync entity type (see {@see SyncStore::getEntityTypeNamespace()})
  * @method static string|null getEntityTypeUri(class-string<ISyncEntity> $entity, bool $compact = true) Get the canonical URI of a sync entity type (see {@see SyncStore::getEntityTypeUri()})
  * @method static SyncErrorCollection getErrors() Get sync operation errors recorded so far
  * @method static string|null getFilename() Get the filename of the database
  * @method static class-string<ISyncClassResolver>|null getNamespaceResolver(class-string<ISyncEntity|ISyncProvider> $class) Get the class resolver for an entity or provider's namespace
+ * @method static int getProviderId(ISyncProvider $provider) Get the provider ID of a registered sync provider, starting a run if necessary
  * @method static int getRunId() Get the run ID of the current run
  * @method static string getRunUuid(bool $binary = false) Get the UUID of the current run (see {@see SyncStore::getRunUuid()})
  * @method static bool isOpen() Check if a database is open

src/Sync/Concept/SyncProvider.php

@@ -26,12 +26,12 @@
 abstract class SyncProvider extends Provider implements ISyncProvider, IService
 {
     /**
-     * Get a dependency subtitution map for the class
+     * Get a dependency subtitution map for the provider
      *
      * {@inheritDoc}
      *
-     * Bind any {@see ISyncEntity} classes customised for this provider to their
-     * generic parent classes by overriding this method, e.g.:
+     * Override this method to bind any {@see ISyncEntity} classes customised
+     * for the provider to their generic parent classes, e.g.:
      *
      * ```php
      * <?php
@@ -65,24 +65,43 @@ public static function getContextualBindings(): array
      */
     private $MagicMethodClosures = [];
 
+    /**
+     * Creates a new provider object
+     *
+     * Creating an instance of the provider registers it with the entity store
+     * injected by the container.
+     */
     public function __construct(IContainer $app, Env $env, SyncStore $store)
     {
         parent::__construct($app, $env);
         $this->Store = $store;
-
         $this->Store->provider($this);
     }
 
+    /**
+     * @inheritDoc
+     */
+    final public function store(): SyncStore
+    {
+        return $this->Store;
+    }
+
+    /**
+     * @inheritDoc
+     */
     final public function setProviderId(int $providerId)
     {
         $this->Id = $providerId;
-
         return $this;
     }
 
-    final public function store(): SyncStore
+    /**
+     * @inheritDoc
+     */
+    final public function getProviderId(): ?int
     {
-        return $this->Store;
+        return $this->Id
+            ?? $this->Store->getProviderId($this);
     }
 
     /**
@@ -108,12 +127,17 @@ final protected function buildSerializeRules(string $entity): SerializeRulesBuil
             ->entity($entity);
     }
 
+    /**
+     * @inheritDoc
+     */
     final public static function getServices(): array
     {
         return SyncIntrospector::get(static::class)->getSyncProviderInterfaces();
     }
 
     /**
+     * @inheritDoc
+     *
      * @template TEntity of ISyncEntity
      * @param class-string<TEntity> $entity
      * @return SyncEntityProvider<TEntity,static>
@@ -147,9 +171,4 @@ final public function __call(string $name, array $arguments)
 
         throw new LogicException('Call to undefined method: ' . static::class . "::$name()");
     }
-
-    final public function getProviderId(): ?int
-    {
-        return $this->Id;
-    }
 }

src/Sync/Support/DeferredSyncEntity.php

@@ -60,7 +60,9 @@ private function __construct(ISyncProvider $provider, ISyncContext $context, $en
         $this->Replace = $this;
 
         if (is_string($entity)) {
-            $this->store()->deferredEntity($this->Provider->getProviderId(), $entity, $deferred, $this);
+            $this->store()
+                ->entityType($entity)
+                ->deferredEntity($this->Provider->getProviderId(), $entity, $deferred, $this);
         }
     }
 

src/Sync/Support/SyncStore.php

@@ -136,6 +136,13 @@ final class SyncStore extends SqliteStore
      */
     private $DeferredProviders = [];
 
+    /**
+     * Deferred entity type registrations
+     *
+     * @var array<class-string<ISyncEntity>,true>
+     */
+    private $DeferredEntityTypes = [];
+
     /**
      * Deferred namespace registrations
      *
@@ -146,6 +153,8 @@ final class SyncStore extends SqliteStore
     private $DeferredNamespaces = [];
 
     /**
+     * Creates a new SyncStore object
+     *
      * @param string $command The canonical name of the command performing sync
      * operations (e.g. a qualified class and/or method name).
      * @param string[] $arguments Arguments passed to the command.
@@ -298,7 +307,9 @@ public function getRunUuid(bool $binary = false): string
     {
         $this->check();
 
-        return $binary ? $this->RunUuid : Convert::uuidToHex($this->RunUuid);
+        return $binary
+            ? $this->RunUuid
+            : Convert::uuidToHex($this->RunUuid);
     }
 
     /**
@@ -323,7 +334,7 @@ public function provider(ISyncProvider $provider)
         $hash = Compute::binaryHash($class, ...$provider->getBackendIdentifier());
 
         if (($this->ProviderMap[$hash] ?? null) !== null) {
-            throw new LogicException("Provider already registered: $class");
+            throw new LogicException(sprintf('Provider already registered: %s', $class));
         }
 
         // Update `last_seen` if the provider is already in the database
@@ -369,21 +380,61 @@ public function provider(ISyncProvider $provider)
         return $this;
     }
 
+    /**
+     * Get the provider ID of a registered sync provider, starting a run if
+     * necessary
+     */
+    public function getProviderId(ISyncProvider $provider): int
+    {
+        if ($this->RunId === null) {
+            $this->check();
+        }
+
+        $class = get_class($provider);
+        $hash = Compute::binaryHash($class, ...$provider->getBackendIdentifier());
+
+        $id = $this->ProviderMap[$hash] ?? null;
+        if ($id === null) {
+            throw new LogicException(sprintf('Provider not registered: %s', $class));
+        }
+        return $id;
+    }
+
     /**
      * Register a sync entity type and set its ID (unless already registered)
      *
+     * If a sync run has started, the entity type is registered immediately and
+     * its ID is passed to {@see ISyncEntity::setEntityTypeId()} before
+     * {@see SyncStore::entityType()} returns. Otherwise, registration is
+     * deferred until a sync run starts.
+     *
      * @param class-string<ISyncEntity> $entity
      * @return $this
      */
     public function entityType(string $entity)
     {
-        if (($this->EntityTypes[$entity] ?? null) !== null) {
+        if (isset($this->EntityTypes[$entity]) ||
+                ($this->RunId === null && isset($this->DeferredEntityTypes[$entity]))) {
             return $this;
         }
 
         $class = new ReflectionClass($entity);
+        $name = $class->getName();
+
+        if ($name !== $entity &&
+            (isset($this->EntityTypes[$name]) ||
+                ($this->RunId === null && isset($this->DeferredEntityTypes[$name])))) {
+            return $this;
+        }
+
         if (!$class->implementsInterface(ISyncEntity::class)) {
-            throw new LogicException("Does not implement ISyncEntity: $entity");
+            throw new LogicException(sprintf('Does not implement ISyncEntity: %s', $entity));
+        }
+
+        // Don't start a run just to register an entity type
+        if ($this->RunId === null) {
+            $this->DeferredEntityTypes[$name] = true;
+            return $this;
         }
 
         // Update `last_seen` if the entity type is already in the database
@@ -398,7 +449,7 @@ public function entityType(string $entity)
               last_seen = CURRENT_TIMESTAMP;
             SQL;
         $stmt = $db->prepare($sql);
-        $stmt->bindValue(':entity_type_class', $class->name, SQLITE3_TEXT);
+        $stmt->bindValue(':entity_type_class', $name, SQLITE3_TEXT);
         $stmt->execute();
         $stmt->close();
 
@@ -411,7 +462,7 @@ public function entityType(string $entity)
               entity_type_class = :entity_type_class;
             SQL;
         $stmt = $db->prepare($sql);
-        $stmt->bindValue(':entity_type_class', $class->name, SQLITE3_TEXT);
+        $stmt->bindValue(':entity_type_class', $name, SQLITE3_TEXT);
         $result = $stmt->execute();
         $row = $result->fetchArray(SQLITE3_NUM);
         $stmt->close();
@@ -421,7 +472,7 @@ public function entityType(string $entity)
         }
 
         $class->getMethod('setEntityTypeId')->invoke(null, $row[0]);
-        $this->EntityTypes[$entity] = $row[0];
+        $this->EntityTypes[$name] = $row[0];
 
         return $this;
     }
@@ -449,13 +500,13 @@ public function entityType(string $entity)
     public function namespace(string $prefix, string $uri, string $namespace, ?string $resolver = null)
     {
         if (!preg_match('/^[a-zA-Z][a-zA-Z0-9+.-]*$/', $prefix)) {
-            throw new LogicException("Invalid prefix: $prefix");
+            throw new LogicException(sprintf('Invalid prefix: %s', $prefix));
         }
 
         $prefix = strtolower($prefix);
         if (($this->RegisteredNamespaces[$prefix] ?? null) ||
                 ($this->RunId === null && ($this->DeferredNamespaces[$prefix] ?? null))) {
-            throw new LogicException("Prefix already registered: $prefix");
+            throw new LogicException(sprintf('Prefix already registered: %s', $prefix));
         }
 
         $uri = rtrim($uri, '/') . '/';
@@ -607,6 +658,10 @@ private function classToNamespace(
      */
     public function entity(int $providerId, string $entityType, $entityId, ISyncEntity $entity)
     {
+        if ($this->RunId === null) {
+            $this->check();
+        }
+
         $entityTypeId = $this->EntityTypes[$entityType];
         if (isset($this->Entities[$providerId][$entityTypeId][$entityId])) {
             throw new LogicException('Entity already registered');
@@ -651,6 +706,10 @@ public function getEntity(int $providerId, string $entityType, $entityId): ?ISyn
      */
     public function deferredEntity(int $providerId, string $entityType, $entityId, DeferredSyncEntity $deferred)
     {
+        if ($this->RunId === null) {
+            $this->check();
+        }
+
         $entityTypeId = $this->EntityTypes[$entityType];
         $entity = $this->Entities[$providerId][$entityTypeId][$entityId] ?? null;
         if ($entity !== null) {
@@ -809,6 +868,11 @@ protected function check()
         }
         unset($this->DeferredProviders);
 
+        foreach (array_keys($this->DeferredEntityTypes) as $entity) {
+            $this->entityType($entity);
+        }
+        unset($this->DeferredEntityTypes);
+
         foreach ($this->DeferredNamespaces as $prefix => [$uri, $namespace, $resolver]) {
             $this->namespace($prefix, $uri, $namespace, $resolver);
         }