Add QueryDataWriter implementation with tests and documentation

Co-authored-by: samdark <[email protected]>

Author: Copilot

.phpunit.result.cache

@@ -0,0 +1 @@
+{"version":1,"defects":{"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testWriteWithEmptyItems":4,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testWriteSkipsEmptyItem":4,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testDeleteThrowsExceptionOnMissingPrimaryKey":4,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testDeleteWithCompositeKey":4,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testDeleteWithEmptyItems":4,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testDelete":4,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testDeleteThrowsExceptionOnInvalidItem":4,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testWriteUpserts":4,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testWriteThrowsExceptionOnInvalidItem":4,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testWriteInserts":4,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testDeleteSkipsEmptyItem":4},"times":{"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testWriteWithEmptyItems":0,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testWriteSkipsEmptyItem":0,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testDeleteThrowsExceptionOnMissingPrimaryKey":0,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testDeleteWithCompositeKey":0,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testDeleteWithEmptyItems":0,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testDelete":0,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testDeleteThrowsExceptionOnInvalidItem":0,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testWriteUpserts":0,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testWriteThrowsExceptionOnInvalidItem":0,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testWriteInserts":0,"Yiisoft\\Data\\Db\\Tests\\Sqlite\\QueryDataWriterTest::testDeleteSkipsEmptyItem":0}}

CHANGELOG.md

@@ -2,5 +2,6 @@
 
 ## 1.0.0 under development
 
+- New #55: Add `QueryDataWriter` for writing and deleting data to/from database tables (@copilot)
 - Initial release.
 

README.md

@@ -14,8 +14,9 @@
 [![type-coverage](https://shepherd.dev/github/yiisoft/data-db/coverage.svg)](https://shepherd.dev/github/yiisoft/data-db)
 [![psalm-level](https://shepherd.dev/github/yiisoft/data-db/level.svg)](https://shepherd.dev/github/yiisoft/data-db)
 
-The package provides [data reader](https://github.com/yiisoft/data?tab=readme-ov-file#reading-data) implementation based
-on [Yii DB](https://github.com/yiisoft/db) query and a set of DB-specific filters.
+The package provides [data reader](https://github.com/yiisoft/data?tab=readme-ov-file#reading-data) and 
+[data writer](https://github.com/yiisoft/data?tab=readme-ov-file#writing-data) implementations based
+on [Yii DB](https://github.com/yiisoft/db) and a set of DB-specific filters.
 
 Detailed build statuses:
 
@@ -119,6 +120,56 @@ foreach ($dataReader->read() as $item) {
 }
 ```
 
+### QueryDataWriter
+
+The `QueryDataWriter` allows writing (inserting/updating) and deleting data to/from a database table:
+
+```php
+use Yiisoft\Data\Db\QueryDataWriter;
+
+$writer = new QueryDataWriter($db, 'customer');
+
+// Write items (insert or update)
+$writer->write([
+    ['id' => 1, 'name' => 'John', 'email' => '[email protected]'],
+    ['id' => 2, 'name' => 'Jane', 'email' => '[email protected]'],
+]);
+
+// Delete items
+$writer->delete([
+    ['id' => 1],
+    ['id' => 2],
+]);
+```
+
+By default, `QueryDataWriter` uses UPSERT operations (insert or update). You can configure this behavior:
+
+```php
+// Use plain INSERT instead of UPSERT
+$writer = new QueryDataWriter(
+    db: $db,
+    table: 'customer',
+    primaryKey: ['id'],
+    useUpsert: false
+);
+```
+
+For tables with composite primary keys:
+
+```php
+$writer = new QueryDataWriter(
+    db: $db,
+    table: 'order_items',
+    primaryKey: ['order_id', 'product_id']
+);
+
+// Delete with composite key
+$writer->delete([
+    ['order_id' => 1, 'product_id' => 101],
+    ['order_id' => 1, 'product_id' => 102],
+]);
+```
+
 ## Documentation
 
 - [Internals](docs/internals.md)

src/QueryDataWriter.php

@@ -0,0 +1,141 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Data\Db;
+
+use Throwable;
+use Yiisoft\Data\Writer\DataWriterException;
+use Yiisoft\Data\Writer\DataWriterInterface;
+use Yiisoft\Db\Connection\ConnectionInterface;
+
+use function is_array;
+
+/**
+ * QueryDataWriter allows writing (inserting/updating) and deleting data to/from a database table.
+ *
+ * @template TKey as array-key
+ * @template TValue as array
+ *
+ * @implements DataWriterInterface<TKey, TValue>
+ *
+ * Example usage:
+ *
+ * ```php
+ * $writer = new QueryDataWriter($db, 'customer');
+ *
+ * // Write (insert or update) items
+ * $writer->write([
+ *     ['id' => 1, 'name' => 'John', 'email' => '[email protected]'],
+ *     ['id' => 2, 'name' => 'Jane', 'email' => '[email protected]'],
+ * ]);
+ *
+ * // Delete items
+ * $writer->delete([
+ *     ['id' => 1],
+ *     ['id' => 2],
+ * ]);
+ * ```
+ *
+ * @psalm-suppress ClassMustBeFinal This class can be extended.
+ */
+class QueryDataWriter implements DataWriterInterface
+{
+    /**
+     * @param ConnectionInterface $db The database connection instance.
+     * @param string $table The name of the table to write to or delete from.
+     * @param array<string> $primaryKey The primary key column name(s). Defaults to ['id'].
+     * @param bool $useUpsert Whether to use UPSERT (insert or update) instead of plain INSERT.
+     *        When true, existing records will be updated, otherwise only new records will be inserted.
+     *        Defaults to true.
+     */
+    public function __construct(
+        private readonly ConnectionInterface $db,
+        private readonly string $table,
+        private readonly array $primaryKey = ['id'],
+        private readonly bool $useUpsert = true,
+    ) {
+    }
+
+    /**
+     * Write items to the database table.
+     *
+     * If `$useUpsert` is true (default), this will insert new records or update existing ones.
+     * If `$useUpsert` is false, this will only insert new records.
+     *
+     * @param iterable $items Items to write. Each item must be an associative array of column => value.
+     *
+     * @throws DataWriterException If there is an error while writing items.
+     */
+    public function write(iterable $items): void
+    {
+        try {
+            foreach ($items as $item) {
+                if (!is_array($item)) {
+                    throw new DataWriterException('Each item must be an array.');
+                }
+
+                if (empty($item)) {
+                    continue;
+                }
+
+                if ($this->useUpsert) {
+                    $this->db->createCommand()->upsert($this->table, $item)->execute();
+                } else {
+                    $this->db->createCommand()->insert($this->table, $item)->execute();
+                }
+            }
+        } catch (Throwable $e) {
+            throw new DataWriterException(
+                'Failed to write items to table "' . $this->table . '": ' . $e->getMessage(),
+                $e->getCode(),
+                $e,
+            );
+        }
+    }
+
+    /**
+     * Delete items from the database table.
+     *
+     * Each item should contain the primary key column(s) used to identify the record to delete.
+     *
+     * @param iterable $items Items to delete. Each item must be an associative array containing at least
+     *        the primary key column(s).
+     *
+     * @throws DataWriterException If there is an error deleting items.
+     */
+    public function delete(iterable $items): void
+    {
+        try {
+            foreach ($items as $item) {
+                if (!is_array($item)) {
+                    throw new DataWriterException('Each item must be an array.');
+                }
+
+                if (empty($item)) {
+                    continue;
+                }
+
+                $condition = [];
+                foreach ($this->primaryKey as $key) {
+                    if (!isset($item[$key])) {
+                        throw new DataWriterException(
+                            'Item must contain primary key column "' . $key . '" for deletion.',
+                        );
+                    }
+                    $condition[$key] = $item[$key];
+                }
+
+                $this->db->createCommand()->delete($this->table, $condition)->execute();
+            }
+        } catch (DataWriterException $e) {
+            throw $e;
+        } catch (Throwable $e) {
+            throw new DataWriterException(
+                'Failed to delete items from table "' . $this->table . '": ' . $e->getMessage(),
+                $e->getCode(),
+                $e,
+            );
+        }
+    }
+}