Rename Collection to Scope, remove dead code, simplify API

- Rename Collection to Scope, CollectionIterator to ScopeIterator,
  move out of Collections sub-namespace
- Make Scope::$name non-null, remove all null-name guards
- Remove registerScope, __isset, derive (unused after simplification)
- Remove unused Stylable methods: realName, remoteFromIdentifier,
  isRelationProperty
- Simplify __call to a one-liner Scope factory
- Extract applyFirstMatch helper in Plural to deduplicate loops

Author: alganet

phpstan.neon.dist

@@ -4,7 +4,7 @@ parameters:
     - src/
     - tests/
   ignoreErrors:
-    - message: '/Call to an undefined (static )?method Respect\\Data\\(AbstractMapper|InMemoryMapper|Collections\\Collection)::\w+\(\)\./'
+    - message: '/Call to an undefined (static )?method Respect\\Data\\(AbstractMapper|InMemoryMapper|Scope)::\w+\(\)\./'
     - message: '/Unsafe usage of new static\(\)\./'
     -
       message: '/Property .+ is never read, only written\./'

src/AbstractMapper.php

@@ -4,7 +4,6 @@
 
 namespace Respect\Data;
 
-use Respect\Data\Collections\Collection;
 use SplObjectStorage;
 
 use function count;
@@ -15,7 +14,7 @@
 
 abstract class AbstractMapper
 {
-    /** @var SplObjectStorage<object, Collection> Maps entity → source Collection */
+    /** @var SplObjectStorage<object, Scope> Maps entity → source Scope */
     protected SplObjectStorage $tracked;
 
     /** @var SplObjectStorage<object, string> Maps entity → 'insert'|'update'|'delete' */
@@ -24,9 +23,6 @@ abstract class AbstractMapper
     /** @var array<string, array<int|string, object>> Identity-indexed map: [collectionName][idValue] → entity */
     protected array $identityMap = [];
 
-    /** @var array<string, Collection> */
-    private array $collections = [];
-
     public EntityFactory $entityFactory { get => $this->hydrator->entityFactory; }
 
     public Styles\Stylable $style { get => $this->entityFactory->style; }
@@ -40,10 +36,10 @@ public function __construct(
 
     abstract public function flush(): void;
 
-    abstract public function fetch(Collection $collection, mixed $extra = null): mixed;
+    abstract public function fetch(Scope $collection, mixed $extra = null): mixed;
 
     /** @return array<int, mixed> */
-    abstract public function fetchAll(Collection $collection, mixed $extra = null): array;
+    abstract public function fetchAll(Scope $collection, mixed $extra = null): array;
 
     public function reset(): void
     {
@@ -55,29 +51,7 @@ public function clearIdentityMap(): void
         $this->identityMap = [];
     }
 
-    public function trackedCount(): int
-    {
-        return count($this->tracked);
-    }
-
-    public function identityMapCount(): int
-    {
-        $total = 0;
-        foreach ($this->identityMap as $entries) {
-            $total += count($entries);
-        }
-
-        return $total;
-    }
-
-    public function markTracked(object $entity, Collection $collection): bool
-    {
-        $this->tracked[$entity] = $collection;
-
-        return true;
-    }
-
-    public function persist(object $object, Collection $onCollection): object
+    public function persist(object $object, Scope $onScope): object
     {
         if ($this->isTracked($object)) {
             $currentOp = $this->pending[$object] ?? null;
@@ -88,45 +62,56 @@ public function persist(object $object, Collection $onCollection): object
             return $object;
         }
 
-        $merged = $this->tryMergeWithIdentityMap($object, $onCollection);
+        $merged = $this->tryMergeWithIdentityMap($object, $onScope);
         if ($merged !== null) {
             return $merged;
         }
 
         $this->pending[$object] = 'insert';
-        $this->markTracked($object, $onCollection);
-        $this->registerInIdentityMap($object, $onCollection);
+        $this->markTracked($object, $onScope);
+        $this->registerInIdentityMap($object, $onScope);
 
         return $object;
     }
 
-    public function remove(object $object, Collection $fromCollection): bool
+    public function remove(object $object, Scope $fromScope): void
     {
         $this->pending[$object] = 'delete';
 
-        if (!$this->isTracked($object)) {
-            $this->markTracked($object, $fromCollection);
+        if ($this->isTracked($object)) {
+            return;
         }
 
-        return true;
+        $this->markTracked($object, $fromScope);
     }
 
-    public function isTracked(object $entity): bool
+    public function trackedCount(): int
     {
-        return $this->tracked->offsetExists($entity);
+        return count($this->tracked);
     }
 
-    public function registerCollection(string $alias, Collection $collection): void
+    public function identityMapCount(): int
     {
-        $this->collections[$alias] = $collection;
+        $total = 0;
+        foreach ($this->identityMap as $entries) {
+            $total += count($entries);
+        }
+
+        return $total;
     }
 
-    protected function registerInIdentityMap(object $entity, Collection $coll): void
+    public function markTracked(object $entity, Scope $collection): void
     {
-        if ($coll->name === null) {
-            return;
-        }
+        $this->tracked[$entity] = $collection;
+    }
+
+    public function isTracked(object $entity): bool
+    {
+        return $this->tracked->offsetExists($entity);
+    }
 
+    protected function registerInIdentityMap(object $entity, Scope $coll): void
+    {
         $idValue = $this->entityIdValue($entity, $coll->name);
         if ($idValue === null) {
             return;
@@ -135,12 +120,8 @@ protected function registerInIdentityMap(object $entity, Collection $coll): void
         $this->identityMap[$coll->name][$idValue] = $entity;
     }
 
-    protected function evictFromIdentityMap(object $entity, Collection $coll): void
+    protected function evictFromIdentityMap(object $entity, Scope $coll): void
     {
-        if ($coll->name === null) {
-            return;
-        }
-
         $idValue = $this->entityIdValue($entity, $coll->name);
         if ($idValue === null) {
             return;
@@ -149,9 +130,9 @@ protected function evictFromIdentityMap(object $entity, Collection $coll): void
         unset($this->identityMap[$coll->name][$idValue]);
     }
 
-    protected function findInIdentityMap(Collection $collection): object|null
+    protected function findInIdentityMap(Scope $collection): object|null
     {
-        if ($collection->name === null || !is_scalar($collection->filter) || $collection->hasChildren) {
+        if (!is_scalar($collection->filter) || $collection->hasChildren) {
             return null;
         }
 
@@ -163,12 +144,8 @@ protected function findInIdentityMap(Collection $collection): object|null
         return $this->identityMap[$collection->name][$condition] ?? null;
     }
 
-    private function tryMergeWithIdentityMap(object $entity, Collection $coll): object|null
+    private function tryMergeWithIdentityMap(object $entity, Scope $coll): object|null
     {
-        if ($coll->name === null) {
-            return null;
-        }
-
         $entityId = $this->entityIdValue($entity, $coll->name);
         $idValue = $entityId ?? $this->normalizeIdValue($coll->filter);
 
@@ -237,22 +214,9 @@ private function normalizeIdValue(mixed $value): int|string|null
         return null;
     }
 
-    public function __isset(string $alias): bool
-    {
-        return isset($this->collections[$alias]);
-    }
-
     /** @param list<mixed> $arguments */
-    public function __call(string $name, array $arguments): Collection
+    public function __call(string $name, array $arguments): Scope
     {
-        if (isset($this->collections[$name])) {
-            if (empty($arguments)) {
-                return clone $this->collections[$name];
-            }
-
-            return $this->collections[$name]->derive(...$arguments); // @phpstan-ignore argument.type
-        }
-
-        return new Collection($name, ...$arguments); // @phpstan-ignore argument.type
+        return new Scope($name, ...$arguments); // @phpstan-ignore argument.type
     }
 }

src/Hydrator.php

@@ -4,7 +4,6 @@
 
 namespace Respect\Data;
 
-use Respect\Data\Collections\Collection;
 use SplObjectStorage;
 
 /** Transforms raw backend data into entity instances mapped to their collections */
@@ -15,12 +14,12 @@ interface Hydrator
     /** Returns just the root entity */
     public function hydrate(
         mixed $raw,
-        Collection $collection,
+        Scope $collection,
     ): object|false;
 
-    /** @return SplObjectStorage<object, Collection>|false */
+    /** @return SplObjectStorage<object, Scope>|false */
     public function hydrateAll(
         mixed $raw,
-        Collection $collection,
+        Scope $collection,
     ): SplObjectStorage|false;
 }

src/Hydrators/Base.php

@@ -5,9 +5,9 @@
 namespace Respect\Data\Hydrators;
 
 use DomainException;
-use Respect\Data\Collections\Collection;
 use Respect\Data\EntityFactory;
 use Respect\Data\Hydrator;
+use Respect\Data\Scope;
 use SplObjectStorage;
 
 /** Base hydrator providing collection-tree entity wiring */
@@ -20,7 +20,7 @@ public function __construct(
 
     public function hydrate(
         mixed $raw,
-        Collection $collection,
+        Scope $collection,
     ): object|false {
         $entities = $this->hydrateAll($raw, $collection);
         if ($entities === false) {
@@ -38,7 +38,7 @@ public function hydrate(
         );
     }
 
-    /** @param SplObjectStorage<object, Collection> $entities */
+    /** @param SplObjectStorage<object, Scope> $entities */
     protected function wireRelationships(SplObjectStorage $entities): void
     {
         $style = $this->entityFactory->style;
@@ -53,7 +53,7 @@ protected function wireRelationships(SplObjectStorage $entities): void
                 }
 
                 $otherColl = $others[$other];
-                if ($otherColl->parent !== $coll || $otherColl->name === null) {
+                if ($otherColl->parent !== $coll) {
                     continue;
                 }
 

src/Hydrators/Nested.php

@@ -4,24 +4,24 @@
 
 namespace Respect\Data\Hydrators;
 
-use Respect\Data\Collections\Collection;
+use Respect\Data\Scope;
 use SplObjectStorage;
 
 use function is_array;
 
 /** Hydrates entities from a nested associative array keyed by collection name */
 final class Nested extends Base
 {
-    /** @return SplObjectStorage<object, Collection>|false */
+    /** @return SplObjectStorage<object, Scope>|false */
     public function hydrateAll(
         mixed $raw,
-        Collection $collection,
+        Scope $collection,
     ): SplObjectStorage|false {
         if (!is_array($raw)) {
             return false;
         }
 
-        /** @var SplObjectStorage<object, Collection> $entities */
+        /** @var SplObjectStorage<object, Scope> $entities */
         $entities = new SplObjectStorage();
 
         $this->hydrateNode($raw, $collection, $entities);
@@ -35,11 +35,11 @@ public function hydrateAll(
 
     /**
      * @param array<mixed, mixed> $data
-     * @param SplObjectStorage<object, Collection> $entities
+     * @param SplObjectStorage<object, Scope> $entities
      */
     private function hydrateNode(
         array $data,
-        Collection $collection,
+        Scope $collection,
         SplObjectStorage $entities,
     ): void {
         $entity = $this->entityFactory->create(
@@ -63,15 +63,15 @@ private function hydrateNode(
 
     /**
      * @param array<string, mixed> $parentData
-     * @param SplObjectStorage<object, Collection> $entities
+     * @param SplObjectStorage<object, Scope> $entities
      */
     private function hydrateChild(
         array $parentData,
-        Collection $child,
+        Scope $child,
         SplObjectStorage $entities,
     ): void {
         $key = $child->name;
-        if ($key === null || !isset($parentData[$key]) || !is_array($parentData[$key])) {
+        if (!isset($parentData[$key]) || !is_array($parentData[$key])) {
             return;
         }