Add validateEntity hook

Add an optional validateEntity() hook, which receives every writable property in getMap() with the values that will be saved, along with the existing entity when updating (null when inserting). For partial updates, the patch is merged into the existing entity, so rules involving multiple properties can be validated without looking up the existing row. When updating, both arrays also include the ID property.

When the hook is implemented, every property in getMap() must be selectable, and updateEntities() only updates rows that can be selected, so rows hidden by processFilter() or the base query can't be updated without being validated.

processEntity() now only handles inserts, since updates validate each existing row before running processRow() with the validated IDs.

Author: theodorejb

CHANGELOG.md

@@ -11,8 +11,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   when `$partial` is true.
 - Protected `processEntity()` and `insertRows()` methods, so an overridden `addEntities()` can access
   the processed rows without calling `processValues()` twice. `processEntity()` runs `processValues()`,
-  converts the properties to a column/value row, then runs `processRow()`. `insertRows()` inserts
-  the rows and returns their IDs.
+  converts the properties to a column/value row, runs `validateEntity()`, then runs `processRow()`.
+  `insertRows()` inserts the rows and returns their IDs.
+- `validateEntity()` hook for validating the complete set of writable properties that will be saved.
+  When updating, it is called for each row with the patch merged into the existing entity, along with
+  the existing entity, and both include the ID property. If implemented, every property in `getMap()`
+  must be selectable, and `updateEntities()` only updates rows that can be selected.
 
 ### Changed
 - `addEntities()` no longer ignores an `id` property in the posted entities. If `getMap()` includes

README.md

@@ -102,6 +102,24 @@ protected function getBaseSelect(QueryOptions $options): SqlParams
 // ...
 ```
 
+To validate entities before they are inserted or updated, implement `validateEntity()`. `$entity` contains
+every property from `getMap()` with the values that will be saved. For partial updates, this is the existing
+entity with the patch merged in. When updating, `$entity` and `$existing` also contain the ID property.
+`$existing` is null when inserting.
+Every property in `getMap()` must also be selectable, so the existing entities can be retrieved.
+
+```php
+use Teapot\{HttpException, StatusCode};
+// ...
+protected function validateEntity(array $entity, ?array $existing): void
+{
+    if ($existing !== null && $existing['isDisabled'] && $entity['username'] !== $existing['username']) {
+        throw new HttpException('Disabled users cannot be renamed', StatusCode::BAD_REQUEST);
+    }
+}
+// ...
+```
+
 ```php
 <?php
 

src/Entities.php

@@ -15,6 +15,9 @@ abstract class Entities
     private array $fullPropMap;
     /** @var array<string, mixed> */
     private array $map;
+    private bool $validatesEntities;
+    /** @var list<string> */
+    private array $writableFields = [];
 
     public function __construct(PeachySql $db)
     {
@@ -38,6 +41,20 @@ public function __construct(PeachySql $db)
         $this->idColumn = $idParts[array_key_last($idParts)];
         $this->fullPropMap = $propMap;
         $this->map = $this->getMap();
+        $this->validatesEntities = (new \ReflectionMethod($this, 'validateEntity'))->class !== self::class;
+
+        if ($this->validatesEntities) {
+            // the existing entities are selected when updating, so every writable property must be selectable
+            $writableFields = array_keys(Helpers::selectMapToPropMap($this->map));
+
+            foreach ($writableFields as $field) {
+                if (!isset($propMap[$field])) {
+                    throw new \Exception("Writable {$field} property must be selectable to validate entities");
+                }
+            }
+
+            $this->writableFields = array_values(array_unique([$this->idField, ...$writableFields]));
+        }
     }
 
     /**
@@ -141,6 +158,20 @@ protected function processRow(array $row, array $ids): array
         return $row;
     }
 
+    /**
+     * Validate an entity before it is inserted or updated, by throwing an HttpException if it is invalid.
+     * $entity contains every writable property in getMap(), with the values that will be saved after
+     * processValues() runs. For partial updates, it is the existing entity with the patch merged in.
+     * When updating, this is called for each row, with the existing values of its writable properties
+     * (selected the same way as getEntities()), and both arrays also contain the row's ID property.
+     * $existing is null when inserting.
+     * Since the existing entities are selected before the update query runs, rules which must hold
+     * when rows are updated concurrently should also be enforced by database constraints.
+     * @param array<string, mixed> $entity
+     * @param array<string, mixed>|null $existing
+     */
+    protected function validateEntity(array $entity, ?array $existing): void {}
+
     /**
      * @param list<string|int> $ids
      */
@@ -154,7 +185,9 @@ public function deleteByIds(array $ids): int
     }
 
     /**
-     * Replace one or more rows, or update them via a JSON Merge Patch (https://tools.ietf.org/html/rfc7396) if $partial is true
+     * Replace one or more rows, or update them via a JSON Merge Patch (https://tools.ietf.org/html/rfc7396) if $partial is true.
+     * All mapped properties are required unless $partial is true.
+     * If validateEntity() is implemented, only rows which can be selected are validated and updated.
      * @param list<string|int> $ids
      * @param mixed[] $data
      */
@@ -164,36 +197,77 @@ public function updateEntities(array $ids, array $data, bool $partial = false):
             return 0;
         }
 
-        $row = $this->processEntity($data, $ids, $partial);
+        $data = $this->processValues($data, $ids);
+        $row = $partial
+            ? self::propertiesToColumns($this->map, $data, complexValues: false)
+            : Helpers::allPropertiesToColumns($this->map, $data);
+
+        if ($this->validatesEntities) {
+            $ids = $this->validateUpdates($ids, $data, $partial);
+
+            if (count($ids) === 0) {
+                return 0;
+            }
+        }
+
+        $row = $this->processRow($row, $ids);
 
         return $this->db->updateRows($this->getTableName(), $row, [$this->idColumn => $ids]);
     }
 
+    /**
+     * Calls validateEntity() for each existing row, and returns the IDs of the rows that were validated.
+     * @param list<string|int> $ids
+     * @param mixed[] $data
+     * @return list<string|int>
+     */
+    private function validateUpdates(array $ids, array $data, bool $partial): array
+    {
+        $validatedIds = [];
+
+        // select in batches, so the IDs don't exceed the database's bound parameter limit
+        foreach (array_chunk(array_values(array_unique($ids)), 1000) as $batch) {
+            foreach ($this->getEntitiesByIds($batch, $this->writableFields) as $entity) {
+                /** @var int|string $id */
+                $id = $entity[$this->idField];
+                // the ID is first, but a mapped ID property overrides its value
+                $existing = [$this->idField => $id, ...Helpers::getMappedValues($this->map, $entity)];
+                $updated = $partial ? array_replace_recursive($existing, $data) : $data;
+                $updated = [$this->idField => $id, ...Helpers::getMappedValues($this->map, $updated)];
+                $this->validateEntity($updated, $existing);
+                $validatedIds[] = $id;
+            }
+        }
+
+        return $validatedIds;
+    }
+
     /**
      * Returns an array containing the IDs of the inserted rows
      * @param list<array> $entities
      * @return list<int>
      */
     public function addEntities(array $entities): array
     {
-        return $this->insertRows(array_map(fn($e) => $this->processEntity($e, []), $entities));
+        return $this->insertRows(array_map(fn($e) => $this->processEntity($e), $entities));
     }
 
     /**
-     * Runs processValues(), converts the properties to a column/value row, then runs processRow().
-     * All mapped properties are required unless $partial is true.
+     * Runs processValues(), converts the properties to a column/value row, runs validateEntity(),
+     * then runs processRow() to return the row to insert. All mapped properties are required.
      * @param mixed[] $data
-     * @param list<string|int> $ids
      * @return array<string, mixed>
      */
-    final protected function processEntity(array $data, array $ids, bool $partial = false): array
+    final protected function processEntity(array $data): array
     {
-        $data = $this->processValues($data, $ids);
-        $row = $partial
-            ? self::propertiesToColumns($this->map, $data, complexValues: false)
-            : Helpers::allPropertiesToColumns($this->map, $data);
+        $data = $this->processValues($data, []);
+        $row = Helpers::allPropertiesToColumns($this->map, $data);
+
+        if ($this->validatesEntities) {
+            $this->validateEntity(Helpers::getMappedValues($this->map, $data), null);
+        }
 
-        return $this->processRow($row, $ids);
+        return $this->processRow($row, []);
     }
 
     /**

src/Helpers.php

@@ -278,6 +278,31 @@ public static function allPropertiesToColumns(array $map, array $properties): ar
         return self::propsToColumns($map, $properties, true, false, true);
     }
 
+    /**
+     * Returns the values of the properties in the map, in the same nested structure.
+     * Properties without a value are set to null.
+     * @param array<string, mixed> $map
+     * @param mixed[] $properties
+     * @return array<string, mixed>
+     */
+    public static function getMappedValues(array $map, array $properties): array
+    {
+        $values = [];
+
+        foreach ($map as $property => $val) {
+            $value = $properties[$property] ?? null;
+
+            if (is_array($val)) {
+                /** @var array<string, mixed> $val */
+                $values[$property] = self::getMappedValues($val, is_array($value) ? $value : []);
+            } else {
+                $values[$property] = $value;
+            }
+        }
+
+        return $values;
+    }
+
     /**
      * @param mixed[] $map
      * @param mixed[] $properties

tests/DbTestCase.php

@@ -3,9 +3,10 @@
 namespace DevTheorem\Phaster\Test;
 
 use DevTheorem\PeachySQL\PeachySql;
-use DevTheorem\Phaster\Test\src\{ConcurrentRows, LegacyUsers, ModernUsers, Users};
+use DevTheorem\Phaster\Test\src\{ConcurrentRows, LegacyUsers, ModernUsers, Users, ValidatedUsers};
 use PDO;
 use PHPUnit\Framework\TestCase;
+use Teapot\HttpException;
 
 abstract class DbTestCase extends TestCase
 {
@@ -120,6 +121,86 @@ public function testUpdateEntities(): void
         $this->assertSame([], $entities->getEntitiesByIds($ids));
     }
 
+    public function testValidateEntity(): void
+    {
+        $db = static::dbProvider();
+        $entities = new ValidatedUsers($db);
+        $weight = fn(float $w) => $db->options->floatSelectedAsString ? (string) $w : $w;
+
+        try {
+            $entities->addEntities([
+                ['name' => 'Validated 1', 'birthday' => '2019-01-02', 'weight' => 20.0],
+                ['name' => 'Validated 2', 'birthday' => '2018-03-04', 'weight' => 0.0],
+            ]);
+
+            throw new \Exception('Failed to throw validation exception');
+        } catch (HttpException $e) {
+            $this->assertSame('Weight must be positive', $e->getMessage());
+        }
+
+        // no rows are inserted if any entity is invalid
+        $this->assertSame(0, $entities->countEntities(['name' => ['lk' => 'Validated %']]));
+
+        // inserted entities are validated after processValues() sets defaults, without unmapped properties
+        $entities->validated = [];
+        $ids = $entities->addEntities([
+            ['name' => 'Validated 1', 'birthday' => '2019-01-02', 'weight' => 20.0, 'extra' => 1],
+            ['name' => 'Validated 2', 'birthday' => '2018-03-04', 'weight' => 30.0, 'isDisabled' => true],
+        ]);
+
+        $expected = [
+            ['entity' => ['name' => 'Validated 1', 'birthday' => '2019-01-02', 'weight' => 20.0, 'isDisabled' => false], 'existing' => null],
+            ['entity' => ['name' => 'Validated 2', 'birthday' => '2018-03-04', 'weight' => 30.0, 'isDisabled' => true], 'existing' => null],
+        ];
+        $this->assertSame($expected, $entities->validated);
+
+        // a partial update validates each existing row with the patch merged in, and skips missing rows
+        $entities->validated = [];
+        $this->assertSame(2, $entities->updateEntities([(string) $ids[0], $ids[1], 0], ['weight' => 25.0], partial: true));
+
+        $existing1 = ['id' => $ids[0], 'name' => 'Validated 1', 'birthday' => '2019-01-02', 'weight' => $weight(20.0), 'isDisabled' => false];
+        $existing2 = ['id' => $ids[1], 'name' => 'Validated 2', 'birthday' => '2018-03-04', 'weight' => $weight(30.0), 'isDisabled' => true];
+        $expected = [
+            ['entity' => [...$existing1, 'weight' => 25.0], 'existing' => $existing1],
+            ['entity' => [...$existing2, 'weight' => 25.0], 'existing' => $existing2],
+        ];
+        $this->assertSame($expected, $entities->validated);
+
+        try {
+            $entities->updateEntities($ids, ['name' => 'Renamed'], partial: true);
+            throw new \Exception('Failed to throw validation exception');
+        } catch (HttpException $e) {
+            $this->assertSame('Disabled users cannot be renamed', $e->getMessage());
+        }
+
+        // neither row is updated if any is invalid
+        $names = array_column($entities->getEntitiesByIds($ids, ['name']), 'name');
+        $this->assertSame(['Validated 1', 'Validated 2'], $names);
+
+        // a replacement is validated along with the existing entity, and an unmapped posted ID is ignored
+        $entities->validated = [];
+        $replacement = ['name' => 'Validated 3', 'birthday' => '2017-05-06', 'weight' => 40.0, 'isDisabled' => true];
+        $this->assertSame(1, $entities->updateEntities([$ids[0]], ['id' => -1, ...$replacement]));
+        $expected = [['entity' => ['id' => $ids[0], ...$replacement], 'existing' => [...$existing1, 'weight' => $weight(25.0)]]];
+        $this->assertSame($expected, $entities->validated);
+
+        $entities->validated = [];
+        $this->assertSame(0, $entities->updateEntities([0], ['weight' => 10.0], partial: true));
+        $this->assertSame([], $entities->validated);
+
+        try {
+            new class ($db) extends ModernUsers {
+                protected function validateEntity(array $entity, ?array $existing): void {}
+            };
+
+            throw new \Exception('Failed to throw exception for unselectable property');
+        } catch (\Exception $e) {
+            $this->assertSame('Writable birthday property must be selectable to validate entities', $e->getMessage());
+        }
+
+        $this->assertSame(2, $entities->deleteByIds($ids));
+    }
+
     public function testEmptyQueries(): void
     {
         $entities = static::entitiesProvider();

tests/HelpersTest.php

@@ -342,4 +342,31 @@ public function testAllPropertiesToColumns(): void
 
         $this->assertSame($expected, Helpers::allPropertiesToColumns($map, $valid));
     }
+
+    public function testGetMappedValues(): void
+    {
+        $properties = [
+            'extra' => 'unmapped properties are excluded',
+            'name' => 'Test Name',
+            'client' => ['name' => 'Client Name', 'id' => 123, 'extra' => true],
+            'group' => null, // null groups are expanded to null properties
+        ];
+
+        $expected = [
+            'name' => 'Test Name',
+            'client' => [
+                'id' => 123,
+                'name' => 'Client Name',
+                'isDisabled' => null,
+            ],
+            'group' => [
+                'type' => [
+                    'id' => null,
+                    'name' => null,
+                ],
+            ],
+        ];
+
+        $this->assertSame($expected, Helpers::getMappedValues($this->propertyMap, $properties));
+    }
 }

tests/src/ModernUsers.php

@@ -63,7 +63,7 @@ public function addEntities(array $entities): array
             if (($entity['name'] ?? null) === 'Modern user 2') {
                 $existingIds[$key] = -42; // don't insert row for this item
             } else {
-                $rows[] = $this->processEntity($entity, []);
+                $rows[] = $this->processEntity($entity);
             }
         }
 

tests/src/ValidatedUsers.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace DevTheorem\Phaster\Test\src;
+
+use Teapot\{HttpException, StatusCode};
+
+class ValidatedUsers extends Users
+{
+    /** @var list<array{entity: array<string, mixed>, existing: array<string, mixed>|null}> */
+    public array $validated = [];
+
+    protected function getTableName(): string
+    {
+        return 'Users';
+    }
+
+    protected function validateEntity(array $entity, ?array $existing): void
+    {
+        $this->validated[] = ['entity' => $entity, 'existing' => $existing];
+
+        if ($entity['weight'] <= 0) {
+            throw new HttpException('Weight must be positive', StatusCode::BAD_REQUEST);
+        }
+
+        if ($existing !== null && $existing['isDisabled'] === true && $entity['name'] !== $existing['name']) {
+            throw new HttpException('Disabled users cannot be renamed', StatusCode::BAD_REQUEST);
+        }
+    }
+}