RowWriter.php

<?php
/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
/**
 * Italix Testing - RowWriter
 *
 * @package Italix\Testing
 */

declare(strict_types=1);

namespace Italix\Testing;

/**
 * The one thing a factory needs from a database: put this row in that table.
 *
 * Declared here rather than in `Italix\Contracts` because nothing else in the
 * framework consumes it. `Contracts` is the seam between libraries (house rule
 * 6); an interface with a single consumer belongs with its consumer, where it
 * can change without a compatibility event.
 *
 * `PdoRowWriter` is the shipped implementation. Anything else — a fake that
 * records rows in memory, a writer that routes through an application's own
 * persistence layer — is three lines.
 */
interface RowWriter
{
    /**
     * Insert one row and return the generated primary key, if there is one.
     *
     * @param  array<string, mixed> $row Column name => value
     * @return string|null               Last insert id, or null when the table
     *                                   has no auto-generated key
     */
    public function insert(string $table_name, array $row): ?string;
}