feat(database): primary key improvements (#1517)

Author: brendt

docs/1-essentials/01-routing.md

@@ -103,6 +103,24 @@ final class Aircraft implements Bindable
 }
 ```
 
+By default, `Bindable` objects will be cast to strings when they are passed into the `uri()` function as a route parameter. You can override this default behaviour by tagging a public property on the object with the {b`\Tempest\Router\IsBindingValue`} attribute:
+
+```php
+use Tempest\Router\Bindable;
+use Tempest\Router\IsBindingValue;
+
+final class Aircraft implements Bindable
+{
+    #[IsBindingValue]
+    public string $callSign;
+
+    public function resolve(string $input): self
+    {
+        return self::find(id: $input);
+    }
+}
+```
+
 ### Backed enum binding
 
 You may inject string-backed enumerations to controller actions. Tempest will try to map the corresponding parameter from the URI to an instance of that enum using the [`tryFrom`](https://www.php.net/manual/en/backedenum.tryfrom.php) enum method.

packages/database/src/Builder/ModelInspector.php

@@ -6,8 +6,6 @@
 use Tempest\Database\BelongsTo;
 use Tempest\Database\Config\DatabaseConfig;
 use Tempest\Database\Eager;
-use Tempest\Database\Exceptions\ModelDidNotHavePrimaryColumn;
-use Tempest\Database\Exceptions\ModelHadMultiplePrimaryColumns;
 use Tempest\Database\HasMany;
 use Tempest\Database\HasOne;
 use Tempest\Database\PrimaryKey;
@@ -108,6 +106,14 @@ public function getPropertyValues(): array
         $values = [];
 
         foreach ($this->reflector->getProperties() as $property) {
+            if ($property->isVirtual()) {
+                continue;
+            }
+
+            if ($property->hasAttribute(Virtual::class)) {
+                continue;
+            }
+
             if (! $property->isInitialized($this->instance)) {
                 continue;
             }
@@ -247,6 +253,81 @@ public function getRelation(string|PropertyReflector $name): ?Relation
         return $this->getBelongsTo($name) ?? $this->getHasOne($name) ?? $this->getHasMany($name);
     }
 
+    /**
+     * @return \Tempest\Support\Arr\ImmutableArray<array-key, Relation>
+     */
+    public function getRelations(): ImmutableArray
+    {
+        if (! $this->isObjectModel()) {
+            return arr();
+        }
+
+        $relationFields = arr();
+
+        foreach ($this->reflector->getPublicProperties() as $property) {
+            if ($relation = $this->getRelation($property->getName())) {
+                $relationFields[] = $relation;
+            }
+        }
+
+        return $relationFields;
+    }
+
+    /**
+     * @return \Tempest\Support\Arr\ImmutableArray<array-key, PropertyReflector>
+     */
+    public function getValueFields(): ImmutableArray
+    {
+        if (! $this->isObjectModel()) {
+            return arr();
+        }
+
+        $valueFields = arr();
+
+        foreach ($this->reflector->getPublicProperties() as $property) {
+            if ($property->isVirtual()) {
+                continue;
+            }
+
+            if ($property->hasAttribute(Virtual::class)) {
+                continue;
+            }
+
+            if ($this->isRelation($property->getName())) {
+                continue;
+            }
+
+            $valueFields[] = $property;
+        }
+
+        return $valueFields;
+    }
+
+    public function isRelationLoaded(string|PropertyReflector|Relation $relation): bool
+    {
+        if (! $this->isObjectModel()) {
+            return false;
+        }
+
+        if (! ($relation instanceof Relation)) {
+            $relation = $this->getRelation($relation);
+        }
+
+        if (! $relation) {
+            return false;
+        }
+
+        if (! $relation->property->isInitialized($this->instance)) {
+            return false;
+        }
+
+        if ($relation->property->getValue($this->instance) === null) {
+            return false;
+        }
+
+        return true;
+    }
+
     public function getSelectFields(): ImmutableArray
     {
         if (! $this->isObjectModel()) {
@@ -255,6 +336,10 @@ public function getSelectFields(): ImmutableArray
 
         $selectFields = arr();
 
+        if ($primaryKey = $this->getPrimaryKeyProperty()) {
+            $selectFields[] = $primaryKey->getName();
+        }
+
         foreach ($this->reflector->getPublicProperties() as $property) {
             $relation = $this->getRelation($property->getName());
 
@@ -266,6 +351,10 @@ public function getSelectFields(): ImmutableArray
                 continue;
             }
 
+            if ($property->getType()->equals(PrimaryKey::class)) {
+                continue;
+            }
+
             if ($relation instanceof BelongsTo) {
                 $selectFields[] = $relation->getOwnerFieldName();
             } else {
@@ -417,11 +506,7 @@ public function getPrimaryKeyProperty(): ?PropertyReflector
 
         return match ($primaryKeys->count()) {
             0 => null,
-            1 => $primaryKeys->first(),
-            default => throw ModelHadMultiplePrimaryColumns::found(
-                model: $this->model,
-                properties: $primaryKeys->map(fn (PropertyReflector $property) => $property->getName())->toArray(),
-            ),
+            default => $primaryKeys->first(),
         };
     }
 

packages/database/src/Builder/QueryBuilders/InsertQueryBuilder.php

@@ -149,6 +149,14 @@ private function convertObjectToArray(object $object, array $excludeProperties =
                 continue;
             }
 
+            if ($property->isVirtual()) {
+                continue;
+            }
+
+            if ($property->isUninitialized($object)) {
+                continue;
+            }
+
             $propertyName = $property->getName();
 
             if (! in_array($propertyName, $excludeProperties, strict: true)) {

packages/database/src/Exceptions/ModelHadMultiplePrimaryColumns.php

@@ -9,14 +9,19 @@
 use Tempest\Database\Builder\QueryBuilders\SelectQueryBuilder;
 use Tempest\Database\Exceptions\RelationWasMissing;
 use Tempest\Database\Exceptions\ValueWasMissing;
-use Tempest\Database\Virtual;
 use Tempest\Reflection\ClassReflector;
 use Tempest\Reflection\PropertyReflector;
+use Tempest\Router\IsBindingValue;
+use Tempest\Validation\SkipValidation;
 
-use function Tempest\Database\query;
+use function Tempest\Support\arr;
+use function Tempest\Support\str;
 
 trait IsDatabaseModel
 {
+    #[IsBindingValue, SkipValidation]
+    public PrimaryKey $id;
+
     /**
      * Returns a builder for selecting records using this model's table.
      *
@@ -58,15 +63,15 @@ public static function new(mixed ...$params): self
     /**
      * Finds a model instance by its ID.
      */
-    public static function findById(string|int|PrimaryKey $id): static
+    public static function findById(string|int|PrimaryKey $id): self
     {
         return self::get($id);
     }
 
     /**
      * Finds a model instance by its ID.
      */
-    public static function resolve(string|int|PrimaryKey $id): static
+    public static function resolve(string|int|PrimaryKey $id): self
     {
         return query(self::class)->resolve($id);
     }
@@ -152,7 +157,6 @@ public static function findOrNew(array $find, array $update): self
      *
      * @param array<string,mixed> $find Properties to search for in the existing model.
      * @param array<string,mixed> $update Properties to update or set on the model if it is found or created.
-     * @return TModel
      */
     public static function updateOrCreate(array $find, array $update): self
     {
@@ -166,23 +170,30 @@ public function refresh(): self
     {
         $model = inspect($this);
 
-        if (! $model->hasPrimaryKey()) {
-            throw Exceptions\ModelDidNotHavePrimaryColumn::neededForMethod($this, 'refresh');
-        }
+        $loadedRelations = $model
+            ->getRelations()
+            ->filter(fn (Relation $relation) => $model->isRelationLoaded($relation));
 
-        $relations = [];
+        $primaryKeyProperty = $model->getPrimaryKeyProperty();
+        $primaryKeyValue = $primaryKeyProperty->getValue($this);
 
-        foreach (new ClassReflector($this)->getPublicProperties() as $property) {
-            if (! $property->getValue($this)) {
-                continue;
-            }
+        $new = self::select()
+            ->with(...$loadedRelations->map(fn (Relation $relation) => $relation->name))
+            ->get($primaryKeyValue);
 
-            if ($model->isRelation($property->getName())) {
-                $relations[] = $property->getName();
-            }
+        foreach ($loadedRelations as $relation) {
+            $relation->property->setValue(
+                object: $this,
+                value: $relation->property->getValue($new),
+            );
         }
 
-        $this->load(...$relations);
+        foreach ($model->getValueFields() as $property) {
+            $property->setValue(
+                object: $this,
+                value: $property->getValue($new),
+            );
+        }
 
         return $this;
     }
@@ -194,21 +205,17 @@ public function load(string ...$relations): self
     {
         $model = inspect($this);
 
-        if (! $model->hasPrimaryKey()) {
-            throw Exceptions\ModelDidNotHavePrimaryColumn::neededForMethod($this, 'load');
-        }
-
         $primaryKeyProperty = $model->getPrimaryKeyProperty();
         $primaryKeyValue = $primaryKeyProperty->getValue($this);
 
         $new = self::get($primaryKeyValue, $relations);
 
-        foreach (new ClassReflector($new)->getPublicProperties() as $property) {
-            if ($property->hasAttribute(Virtual::class)) {
-                continue;
-            }
+        $fieldsToUpdate = arr($relations)
+            ->map(fn (string $relation) => str($relation)->before('.')->toString())
+            ->unique();
 
-            $property->setValue($this, $property->getValue($new));
+        foreach ($fieldsToUpdate as $fieldToUpdate) {
+            $this->{$fieldToUpdate} = $new->{$fieldToUpdate};
         }
 
         return $this;
@@ -262,10 +269,6 @@ public function update(mixed ...$params): self
     {
         $model = inspect($this);
 
-        if (! $model->hasPrimaryKey()) {
-            throw Exceptions\ModelDidNotHavePrimaryColumn::neededForMethod($this, 'update');
-        }
-
         $model->validate(...$params);
 
         query($this)

packages/database/src/IsDatabaseModel.php

@@ -6,8 +6,10 @@
 
 use BackedEnum;
 use Psr\Http\Message\ServerRequestInterface as PsrRequest;
+use ReflectionClass;
 use Tempest\Container\Container;
 use Tempest\Core\AppConfig;
+use Tempest\Database\PrimaryKey;
 use Tempest\Http\Mappers\PsrRequestToGenericRequestMapper;
 use Tempest\Http\Request;
 use Tempest\Http\Response;
@@ -126,6 +128,15 @@ public function toUri(array|string $action, ...$params): string
 
             if ($value instanceof BackedEnum) {
                 $value = $value->value;
+            } elseif ($value instanceof Bindable) {
+                foreach (new ClassReflector($value)->getPublicProperties() as $property) {
+                    if (! $property->hasAttribute(IsBindingValue::class)) {
+                        continue;
+                    }
+
+                    $value = $property->getValue($value);
+                    break;
+                }
             }
 
             $uri = $uri->replaceRegex(

packages/router/src/GenericRouter.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Tempest\Router;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class IsBindingValue
+{
+}

packages/router/src/IsBindingValue.php

@@ -24,7 +24,7 @@ public static function fromRoute(Route $route, MethodReflector $methodReflector)
             self::getRouteParams($route->uri),
             $route->middleware,
             $methodReflector,
-            $route->without,
+            $route->without ?? [],
         );
     }
 

packages/router/src/Routing/Construction/DiscoveredRoute.php

@@ -13,8 +13,6 @@ final class A
 {
     use IsDatabaseModel;
 
-    public PrimaryKey $id;
-
     public function __construct(
         public B $b,
     ) {}

tests/Fixtures/Models/A.php

@@ -14,8 +14,6 @@ final class AWithEager
 {
     use IsDatabaseModel;
 
-    public PrimaryKey $id;
-
     public function __construct(
         #[Eager]
         public BWithEager $b,