Add afterInsert hook

Author: theodorejb

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+### Added
+- `afterInsert()` hook which runs after rows are inserted, before their IDs are returned.
+It receives the inserted rows and their generated IDs, enabling follow-up work
+(e.g. sending notifications) that depends on a successful insert.
+
 ## [4.0.0] - 2025-01-03
 ### Changed
 - `getMap()` is no longer abstract and returns an empty array by default,

src/Entities.php

@@ -141,6 +141,14 @@ protected function processRow(array $row, array $ids): array
         return $row;
     }
 
+    /**
+     * Runs after rows are inserted, before their IDs are returned.
+     * The arrays are parallel: $ids[$i] is the generated ID of $rows[$i].
+     * @param list<int> $ids
+     * @param list<array<string, mixed>> $rows the inserted column/value rows
+     */
+    protected function afterInsert(array $ids, array $rows): void {}
+
     /**
      * @param list<string|int> $ids
      */
@@ -214,9 +222,12 @@ public function addEntities(array $entities): array
         }
 
         $ids = $this->db->insertRows($this->getTableName(), $rows, $this->getIdentityIncrement())->ids;
+        $this->afterInsert($ids, $rows); // $ids is parallel to $rows before existing IDs are merged in
+
         foreach ($existingIds as $offset => $id) {
             array_splice($ids, $offset, 0, [$id]);
         }
+
         return $ids;
     }
 

tests/DbTestCase.php

@@ -320,6 +320,16 @@ public function testModernUsers(): void
         $ids = $entities->addEntities($users);
         $this->assertSame(-42, $ids[1]); // manually set ID in processValues
 
+        // afterInsert receives only the inserted rows, with IDs parallel to them (excluding the
+        // manually set existing ID at index 1)
+        $insertedIds = $ids;
+        array_splice($insertedIds, 1, 1);
+        $this->assertNotNull($entities->afterInsertResult);
+        $this->assertSame($insertedIds, $entities->afterInsertResult['ids']);
+        $this->assertCount(9, $entities->afterInsertResult['rows']);
+        $this->assertSame('Modern user 1', $entities->afterInsertResult['rows'][0]['name']);
+        $this->assertSame('Modern user 3 modified', $entities->afterInsertResult['rows'][1]['name']);
+
         $db->insertRow('UserThings', ['user_id' => $ids[3]]);
 
         $actual = $entities->getEntitiesByIds([$ids[2], $ids[3]], ['id', 'name', 'isDisabled', 'computed', 'thing.uid']);

tests/src/ModernUsers.php

@@ -6,6 +6,9 @@
 
 class ModernUsers extends Entities
 {
+    /** @var array{ids: list<int>, rows: list<array<string, mixed>>}|null */
+    public ?array $afterInsertResult = null;
+
     protected function getTableName(): string
     {
         return 'Users';
@@ -63,4 +66,9 @@ protected function processValues(array $data, array $ids): array
 
         return $data;
     }
+
+    protected function afterInsert(array $ids, array $rows): void
+    {
+        $this->afterInsertResult = ['ids' => $ids, 'rows' => $rows];
+    }
 }