Separate FK fields from relation properties in hydration

wireRelationships() now sets related entities on a dedicated relation
property (e.g. $comment->post) instead of overwriting the FK field
($comment->post_id stays as the int). This is driven by two new Style
methods: relationProperty() derives the property name from an FK field,
and isRelationProperty() identifies relation properties for filtering.

Flat hydrator gains an isEntityBoundary() hook so FlatNum can detect
table transitions via column metadata, fixing hydration of join tables
without a standalone id column.

Author: alganet

src/Hydrators/Base.php

@@ -9,6 +9,8 @@
 use Respect\Data\Hydrator;
 use SplObjectStorage;
 
+use function is_object;
+
 /** Base hydrator providing FK-to-entity wiring shared by all strategies */
 abstract class Base implements Hydrator
 {
@@ -25,6 +27,10 @@ protected function wireRelationships(SplObjectStorage $entities, EntityFactory $
                 }
 
                 foreach ($entitiesClone as $sub) {
+                    if ($sub === $instance) {
+                        continue;
+                    }
+
                     $tableName = (string) $entities[$sub]->name;
                     $primaryName = $style->identifier($tableName);
 
@@ -38,6 +44,15 @@ protected function wireRelationships(SplObjectStorage $entities, EntityFactory $
                     $v = $sub;
                 }
 
+                if (is_object($v)) {
+                    $relationName = $style->relationProperty($field);
+                    if ($relationName !== null) {
+                        $entityFactory->set($instance, $relationName, $v);
+
+                        continue;
+                    }
+                }
+
                 $entityFactory->set($instance, $field, $v);
             }
         }

src/Hydrators/Flat.php

@@ -56,7 +56,7 @@ public function hydrate(
                 $value,
             );
 
-            if ($primaryName != $columnName) {
+            if ($primaryName != $columnName && !$this->isEntityBoundary($col, $raw)) {
                 continue;
             }
 
@@ -75,6 +75,12 @@ public function hydrate(
     /** Resolve the column name for a given reference (numeric index, namespaced key, etc.) */
     abstract protected function resolveColumnName(mixed $reference, mixed $raw): string;
 
+    /** Check if this column is the last one for the current entity (table boundary without PK) */
+    protected function isEntityBoundary(mixed $col, mixed $raw): bool
+    {
+        return false;
+    }
+
     /**
      * @param SplObjectStorage<object, Collection> $entities
      *

src/Styles/NorthWind.php

@@ -44,4 +44,14 @@ public function remoteFromIdentifier(string $name): string|null
     {
         return $this->isRemoteIdentifier($name) ? $this->singularToPlural(substr($name, 0, -2)) : null;
     }
+
+    public function relationProperty(string $field): string|null
+    {
+        return $this->isRemoteIdentifier($field) ? substr($field, 0, -2) : null;
+    }
+
+    public function isRelationProperty(string $name): bool
+    {
+        return !$this->isRemoteIdentifier($name) && $this->isRemoteIdentifier($name . 'ID');
+    }
 }

src/Styles/Standard.php

@@ -56,4 +56,14 @@ public function remoteFromIdentifier(string $name): string|null
     {
         return $this->isRemoteIdentifier($name) ? substr($name, 0, -3) : null;
     }
+
+    public function relationProperty(string $field): string|null
+    {
+        return $this->isRemoteIdentifier($field) ? substr($field, 0, -3) : null;
+    }
+
+    public function isRelationProperty(string $name): bool
+    {
+        return !$this->isRemoteIdentifier($name) && $this->isRemoteIdentifier($name . '_id');
+    }
 }

src/Styles/Stylable.php

@@ -22,5 +22,9 @@ public function remoteFromIdentifier(string $name): string|null;
 
     public function isRemoteIdentifier(string $name): bool;
 
+    public function relationProperty(string $remoteIdentifierField): string|null;
+
+    public function isRelationProperty(string $name): bool;
+
     public function composed(string $left, string $right): string;
 }

tests/AbstractMapperTest.php

@@ -243,7 +243,9 @@ public function hydrationWiresFkWithMatchingEntity(): void
 
         $comment = $mapper->comment->post->fetch();
         $this->assertIsObject($comment);
-        $post = $mapper->entityFactory->get($comment, 'post_id');
+        // FK stays as int, relation goes to derived property
+        $this->assertEquals(5, $mapper->entityFactory->get($comment, 'post_id'));
+        $post = $mapper->entityFactory->get($comment, 'post');
         $this->assertIsObject($post);
         $this->assertEquals(5, $mapper->entityFactory->get($post, 'id'));
         $this->assertEquals('Post', $mapper->entityFactory->get($post, 'title'));
@@ -278,7 +280,9 @@ public function hydrationMatchesIntFkToStringPk(): void
 
         $comment = $mapper->comment->post->fetch();
         $this->assertIsObject($comment);
-        $post = $mapper->entityFactory->get($comment, 'post_id');
+        // FK stays as int, relation goes to derived property
+        $this->assertEquals(5, $mapper->entityFactory->get($comment, 'post_id'));
+        $post = $mapper->entityFactory->get($comment, 'post');
         $this->assertIsObject($post);
         $this->assertEquals('5', $mapper->entityFactory->get($post, 'id'));
     }

tests/Styles/AbstractStyleTest.php

@@ -61,6 +61,16 @@ public function remoteFromIdentifier(string $name): string|null
             {
                 return null;
             }
+
+            public function relationProperty(string $field): string|null
+            {
+                return null;
+            }
+
+            public function isRelationProperty(string $name): bool
+            {
+                return false;
+            }
         };
     }
 

tests/Styles/CakePHP/CakePHPIntegrationTest.php

@@ -59,16 +59,16 @@ public function testFetchingAllEntityTyped(): void
 
         $categories = $mapper->post_categories->categories->fetch();
         $this->assertInstanceOf(PostCategory::class, $categories);
-        $this->assertInstanceOf(Category::class, $categories->category_id);
+        $this->assertInstanceOf(Category::class, $categories->category);
     }
 
     public function testFetchingAllEntityTypedNested(): void
     {
         $mapper = $this->mapper;
         $comment = $mapper->comments->posts->authors->fetchAll();
         $this->assertInstanceOf(Comment::class, $comment[0]);
-        $this->assertInstanceOf(Post::class, $comment[0]->post_id);
-        $this->assertInstanceOf(Author::class, $comment[0]->post_id->author_id);
+        $this->assertInstanceOf(Post::class, $comment[0]->post);
+        $this->assertInstanceOf(Author::class, $comment[0]->post->author);
     }
 
     public function testPersistingEntityTyped(): void

tests/Styles/CakePHP/Comment.php

@@ -10,5 +10,7 @@ class Comment
 
     public mixed $post_id = null;
 
+    public mixed $post = null;
+
     public string|null $text = null;
 }

tests/Styles/CakePHP/Post.php

@@ -13,4 +13,6 @@ class Post
     public string|null $text = null;
 
     public mixed $author_id = null;
+
+    public mixed $author = null;
 }