Merge branch 'invalid-sync-entity-exception'

lkrms · lkrms · commit d9a0ff3e0d0a · 2023-10-28T20:14:59.000+11:00
diff --git a/lib/lk-util/Command/Generate/GenerateBuilder.php b/lib/lk-util/Command/Generate/GenerateBuilder.php
@@ -43,6 +43,7 @@ class GenerateBuilder extends GenerateCommand
     ];
 
     private ?string $ClassFqcn;
+
     private ?string $BuilderFqcn;
 
     /**
@@ -59,6 +60,16 @@ class GenerateBuilder extends GenerateCommand
      */
     private ?array $Skip;
 
+    // --
+
+    /**
+     * camelCase name => parameter received by reference, or
+     * parameter/property/method with a generic template type
+     *
+     * @var array<string,ReflectionParameter|ReflectionProperty|ReflectionMethod>
+     */
+    private array $ToDeclare = [];
+
     public function description(): string
     {
         return 'Generate a builder that creates instances of a class via a fluent interface';
@@ -124,6 +135,7 @@ protected function run(string ...$args)
     {
         $this->reset();
         $this->Skip = array_merge($this->Skip, self::SKIP);
+        $this->ToDeclare = [];
 
         $classFqcn = $this->getRequiredFqcnOptionValue(
             'class',
@@ -177,14 +189,6 @@ protected function run(string ...$args)
          */
         $_params = [];
 
-        /**
-         * camelCase name => parameter received by reference or with a generic
-         * template type
-         *
-         * @var array<string,ReflectionParameter|ReflectionProperty|ReflectionMethod>
-         */
-        $toDeclare = [];
-
         /** @var array<string,array<string,PhpDocTemplateTag>> */
         $declareTemplates = [];
 
@@ -210,7 +214,7 @@ protected function run(string ...$args)
                 // Variables can't be passed to __call by reference, so this
                 // parameter needs to be received via a declared method
                 if ($_param->isPassedByReference()) {
-                    $toDeclare[$name] = $_param;
+                    $this->ToDeclare[$name] = $_param;
                 }
             }
         }
@@ -301,12 +305,9 @@ protected function run(string ...$args)
                         $propertyFile,
                         $templates
                     );
-                    if ($templates &&
-                        count($templates) === 1 &&
-                        ($type === 'class-string<' . ($key = array_keys($templates)[0]) . '>' ||
-                            $type === $key)) {
+                    if (count($templates) === 1) {
                         $declareTemplates[$name] = $templates;
-                        $toDeclare[$name] = $toDeclare[$name] ?? $_property;
+                        $this->ToDeclare[$name] = $this->ToDeclare[$name] ?? $_property;
                     }
                 } else {
                     $type = $_property->hasType()
@@ -370,7 +371,7 @@ protected function run(string ...$args)
             $propertyFile = $_constructor->getFileName();
             $propertyNamespace = $_constructor->getDeclaringClass()->getNamespaceName();
             $declaringClass = $this->getTypeAlias($_constructor->getDeclaringClass()->getName());
-            $declare = array_key_exists($name, $toDeclare);
+            $declare = array_key_exists($name, $this->ToDeclare);
 
             // If the parameter has a matching property, retrieve its DocBlock
             if ($_property = $_allProperties[$name] ?? null) {
@@ -401,13 +402,10 @@ protected function run(string ...$args)
                     $propertyFile,
                     $templates
                 );
-                if ($templates &&
-                    count($templates) === 1 &&
-                    ($type === 'class-string<' . ($key = array_keys($templates)[0]) . '>' ||
-                        $type === $key)) {
+                if (count($templates) === 1) {
                     $declareTemplates[$name] = $templates;
                     if (!$declare) {
-                        $toDeclare[$name] = $_param;
+                        $this->ToDeclare[$name] = $_param;
                         $declare = true;
                     }
                 }
@@ -561,7 +559,7 @@ protected function run(string ...$args)
                 $returnsVoid = false;
 
                 if ($declare) {
-                    $toDeclare[$name] = $_method;
+                    $this->ToDeclare[$name] = $_method;
                 }
 
                 $_type = $phpDoc->Return->Type ?? null;
@@ -580,7 +578,7 @@ protected function run(string ...$args)
                             $type === $key)) {
                         $declareTemplates[$name] = $templates;
                         if (!$declare) {
-                            $toDeclare[$name] = $_method;
+                            $this->ToDeclare[$name] = $_method;
                             $declare = true;
                         }
                     }
@@ -784,7 +782,7 @@ protected function run(string ...$args)
             ),
         );
 
-        foreach ($toDeclare as $name => $_param) {
+        foreach ($this->ToDeclare as $name => $_param) {
             if ($_param instanceof ReflectionMethod) {
                 $_params = $_param->getParameters();
                 $return = $returnsValue[$name] ? 'return ' : '';
@@ -856,13 +854,23 @@ private function getSummary(
         if ($summary !== null) {
             $summary = rtrim($summary, '.');
         }
+        $byRef = false;
+        if ($declare && $name !== null) {
+            $declaring = $this->ToDeclare[$name] ?? null;
+            if ($declaring instanceof ReflectionParameter) {
+                $byRef = $declaring->isPassedByReference();
+            }
+        }
         if ($member) {
             $class = $typeNameCallback($member->getDeclaringClass()->getName());
             $name = $member->getName();
             $param = '';
-            $see = $member instanceof ReflectionMethod ? $class . '::' . $name . '()' : $class . '::$' . $name;
+            $see =
+                $member instanceof ReflectionMethod
+                    ? $class . '::' . $name . '()'
+                    : $class . '::$' . $name;
         } else {
-            $param = "`\$$name` in ";
+            $param = $declare ? "\$$name in " : "`\$$name` in ";
             $see = $class . '::__construct()';
         }
         if ($default !== null) {
@@ -872,15 +880,27 @@ private function getSummary(
             $defaultSuffix = $defaultPrefix = '';
         }
 
-        return $summary !== null
-            ? ($declare
-                ? $summary . $defaultSuffix
-                : " $summary" . ($link ? " ({$defaultPrefix}see {@see $see})" : $defaultSuffix))
-            : (($declare
-                ? ($member instanceof ReflectionMethod ? "Call $see on a new instance" : "Pass a variable to $param$see by reference")
-                : ($link
-                    ? " See {@see $see}"
-                    : ($member instanceof ReflectionMethod ? " Call $see on a new instance" : ($param !== '' ? " Pass \$value to $param$see" : " Set $see"))))
-                . $defaultSuffix);
+        return
+            $summary !== null
+                ? ($declare
+                    ? $summary . $defaultSuffix
+                    : " $summary"
+                        . ($link
+                            ? " ({$defaultPrefix}see {@see $see})"
+                            : $defaultSuffix))
+                : (($declare
+                    ? ($member instanceof ReflectionMethod
+                        ? "Call $see on a new instance"
+                        : ($byRef
+                            ? "Pass a variable to $param$see by reference"
+                            : "Pass a value to $param$see"))
+                    : ($link
+                        ? " See {@see $see}"
+                        : ($member instanceof ReflectionMethod
+                            ? " Call $see on a new instance"
+                            : ($param !== ''
+                                ? " Pass \$value to $param$see"
+                                : " Set $see"))))
+                    . $defaultSuffix);
     }
 }
diff --git a/src/Sync/Exception/SyncInvalidEntityException.php b/src/Sync/Exception/SyncInvalidEntityException.php
@@ -0,0 +1,53 @@
+<?php declare(strict_types=1);
+
+namespace Lkrms\Sync\Exception;
+
+use Lkrms\Sync\Contract\ISyncEntity;
+use Lkrms\Sync\Contract\ISyncProvider;
+use Throwable;
+
+/**
+ * Thrown when an entity has invalid data or is not the droid you're looking for
+ */
+class SyncInvalidEntityException extends SyncException
+{
+    protected ISyncProvider $Provider;
+
+    protected string $EntityType;
+
+    /**
+     * @var int|string|null
+     */
+    protected $EntityId;
+
+    protected ?ISyncEntity $Entity;
+
+    /**
+     * Creates a new SyncInvalidEntityException object
+     *
+     * @template T of ISyncEntity
+     *
+     * @param class-string<T> $entityType
+     * @param T|int|string|null $entityOrId
+     */
+    public function __construct(
+        string $message,
+        ISyncProvider $provider,
+        string $entityType,
+        $entityOrId,
+        ?Throwable $previous = null
+    ) {
+        $this->Provider = $provider;
+        $this->EntityType = $entityType;
+
+        if ($entityOrId instanceof ISyncEntity) {
+            $this->Entity = $entityOrId;
+            $this->EntityId = $this->Entity->id();
+        } else {
+            $this->EntityId = $entityOrId;
+            $this->Entity = null;
+        }
+
+        parent::__construct($message, $previous);
+    }
+}
diff --git a/src/Sync/Support/DbSyncDefinitionBuilder.php b/src/Sync/Support/DbSyncDefinitionBuilder.php
@@ -28,8 +28,6 @@
  * @method $this overrides(array<int-mask-of<OP::*>,Closure(DbSyncDefinition<TEntity,TProvider>, OP::*, ISyncContext, mixed...): (iterable<TEntity>|TEntity)> $value) An array that maps sync operations to closures that override other implementations (see {@see SyncDefinition::$Overrides})
  * @method $this keyMap(array<array-key,array-key|array-key[]>|null $value) An array that maps provider (backend) keys to one or more entity keys (see {@see SyncDefinition::$KeyMap})
  * @method $this keyMapFlags(int-mask-of<ArrayMapperFlag::*> $value) Passed to the array mapper if `$keyMap` is provided
- * @method $this pipelineFromBackend(IPipeline<mixed[],TEntity,array{0:OP::*,1:ISyncContext,2?:int|string|TEntity|TEntity[]|null,...}>|null $value) A pipeline that maps data from the provider to entity-compatible associative arrays, or `null` if mapping is not required
- * @method $this pipelineToBackend(IPipeline<TEntity,mixed[],array{0:OP::*,1:ISyncContext,2?:int|string|TEntity|TEntity[]|null,...}>|null $value) A pipeline that maps serialized entities to data compatible with the provider, or `null` if mapping is not required
  * @method $this readFromReadList(bool $value = true) If true, perform READ operations by iterating over entities returned by READ_LIST (default: false; see {@see SyncDefinition::$ReadFromReadList})
  * @method $this returnEntitiesFrom(SyncEntitySource::*|null $value) Where to acquire entity data for the return value of a successful CREATE, UPDATE or DELETE operation
  *
@@ -78,4 +76,28 @@ public function provider(DbSyncProvider $value)
     {
         return $this->getWithValue(__FUNCTION__, $value);
     }
+
+    /**
+     * A pipeline that maps data from the provider to entity-compatible associative arrays, or `null` if mapping is not required
+     *
+     * @template T of ISyncEntity
+     * @param IPipeline<mixed[],T,array{0:OP::*,1:ISyncContext,2?:int|string|T|T[]|null,...}>|null $value
+     * @return $this<T,TProvider>
+     */
+    public function pipelineFromBackend(?IPipeline $value)
+    {
+        return $this->getWithValue(__FUNCTION__, $value);
+    }
+
+    /**
+     * A pipeline that maps serialized entities to data compatible with the provider, or `null` if mapping is not required
+     *
+     * @template T of ISyncEntity
+     * @param IPipeline<T,mixed[],array{0:OP::*,1:ISyncContext,2?:int|string|T|T[]|null,...}>|null $value
+     * @return $this<T,TProvider>
+     */
+    public function pipelineToBackend(?IPipeline $value)
+    {
+        return $this->getWithValue(__FUNCTION__, $value);
+    }
 }
diff --git a/src/Sync/Support/HttpSyncDefinitionBuilder.php b/src/Sync/Support/HttpSyncDefinitionBuilder.php
@@ -40,8 +40,6 @@
  * @method $this overrides(array<int-mask-of<OP::*>,Closure(HttpSyncDefinition<TEntity,TProvider>, OP::*, ISyncContext, mixed...): (iterable<TEntity>|TEntity)> $value) An array that maps sync operations to closures that override other implementations (see {@see SyncDefinition::$Overrides})
  * @method $this keyMap(array<array-key,array-key|array-key[]>|null $value) An array that maps provider (backend) keys to one or more entity keys (see {@see SyncDefinition::$KeyMap})
  * @method $this keyMapFlags(int-mask-of<ArrayMapperFlag::*> $value) Passed to the array mapper if `$keyMap` is provided
- * @method $this pipelineFromBackend(IPipeline<mixed[],TEntity,array{0:OP::*,1:ISyncContext,2?:int|string|TEntity|TEntity[]|null,...}>|null $value) A pipeline that maps data from the provider to entity-compatible associative arrays, or `null` if mapping is not required
- * @method $this pipelineToBackend(IPipeline<TEntity,mixed[],array{0:OP::*,1:ISyncContext,2?:int|string|TEntity|TEntity[]|null,...}>|null $value) A pipeline that maps serialized entities to data compatible with the provider, or `null` if mapping is not required
  * @method $this readFromReadList(bool $value = true) If true, perform READ operations by iterating over entities returned by READ_LIST (default: false; see {@see SyncDefinition::$ReadFromReadList})
  * @method $this returnEntitiesFrom(SyncEntitySource::*|null $value) Where to acquire entity data for the return value of a successful CREATE, UPDATE or DELETE operation
  *
@@ -90,4 +88,28 @@ public function provider(HttpSyncProvider $value)
     {
         return $this->getWithValue(__FUNCTION__, $value);
     }
+
+    /**
+     * A pipeline that maps data from the provider to entity-compatible associative arrays, or `null` if mapping is not required
+     *
+     * @template T of ISyncEntity
+     * @param IPipeline<mixed[],T,array{0:OP::*,1:ISyncContext,2?:int|string|T|T[]|null,...}>|null $value
+     * @return $this<T,TProvider>
+     */
+    public function pipelineFromBackend(?IPipeline $value)
+    {
+        return $this->getWithValue(__FUNCTION__, $value);
+    }
+
+    /**
+     * A pipeline that maps serialized entities to data compatible with the provider, or `null` if mapping is not required
+     *
+     * @template T of ISyncEntity
+     * @param IPipeline<T,mixed[],array{0:OP::*,1:ISyncContext,2?:int|string|T|T[]|null,...}>|null $value
+     * @return $this<T,TProvider>
+     */
+    public function pipelineToBackend(?IPipeline $value)
+    {
+        return $this->getWithValue(__FUNCTION__, $value);
+    }
 }
diff --git a/src/Sync/Support/SyncSerializeRules.php b/src/Sync/Support/SyncSerializeRules.php
@@ -229,7 +229,7 @@ final class SyncSerializeRules implements ISyncSerializeRules, IReadable, IImmut
      * @param class-string<TEntity> $entity
      * @param array<array<array<string|Closure>|string>|array<string|Closure>|string> $remove
      * @param array<array<array<string|Closure>|string>|array<string|Closure>|string> $replace
-     * @param SyncSerializeRules<TEntity>|null $inherit
+     * @param SyncSerializeRules<TEntity>|null $inherit Inherit rules from another instance
      */
     public function __construct(
         string $entity,
diff --git a/src/Sync/Support/SyncSerializeRulesBuilder.php b/src/Sync/Support/SyncSerializeRulesBuilder.php
@@ -22,7 +22,6 @@
  * @method $this replace(array<array<array<string|Closure>|string>|array<string|Closure>|string> $value) Values to replace with IDs (see {@see SyncSerializeRules::$Replace})
  * @method $this recurseRules(?bool $value = true) Apply path-based rules to every instance of $Entity? (default: true)
  * @method $this flags(?int $value) Set SyncSerializeRules::$Flags
- * @method $this inherit(SyncSerializeRules<TEntity>|null $value) Pass $value to `$inherit` in SyncSerializeRules::__construct()
  *
  * @uses SyncSerializeRules
  *
@@ -57,4 +56,16 @@ public function entity(string $value)
     {
         return $this->getWithValue(__FUNCTION__, $value);
     }
+
+    /**
+     * Inherit rules from another instance
+     *
+     * @template T of ISyncEntity
+     * @param SyncSerializeRules<T>|null $value
+     * @return $this<T>
+     */
+    public function inherit(?SyncSerializeRules $value)
+    {
+        return $this->getWithValue(__FUNCTION__, $value);
+    }
 }

Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,6 @@`
`22`	`22`	`* @method $this replace(array<array<array<string\|Closure>\|string>\|array<string\|Closure>\|string> $value) Values to replace with IDs (see {@see SyncSerializeRules::$Replace})`
`23`	`23`	`* @method $this recurseRules(?bool $value = true) Apply path-based rules to every instance of $Entity? (default: true)`
`24`	`24`	`* @method $this flags(?int $value) Set SyncSerializeRules::$Flags`
`25`		- * @method $this inherit(SyncSerializeRules<TEntity>\|null $value) Pass $value to `$inherit` in SyncSerializeRules::__construct()
`26`	`25`	`*`
`27`	`26`	`* @uses SyncSerializeRules`
`28`	`27`	`*`
`@@ -57,4 +56,16 @@ public function entity(string $value)`
`57`	`56`	`{`
`58`	`57`	`return $this->getWithValue(__FUNCTION__, $value);`
`59`	`58`	`}`
	`59`	`+`
	`60`	`+ /**`
	`61`	`+ * Inherit rules from another instance`
	`62`	`+ *`
	`63`	`+ * @template T of ISyncEntity`
	`64`	`+ * @param SyncSerializeRules<T>\|null $value`
	`65`	`+ * @return $this<T>`
	`66`	`+ */`
	`67`	`+ public function inherit(?SyncSerializeRules $value)`
	`68`	`+ {`
	`69`	`+ return $this->getWithValue(__FUNCTION__, $value);`
	`70`	`+ }`
`60`	`71`	`}`