<?php
/**
 * Base repository.
 *
 * @package HostKhata
 */

namespace HostKhata\Database\Repositories;

defined( 'ABSPATH' ) || exit;

use wpdb;

/**
 * Shared plumbing for repositories. Repositories are the only classes that
 * write SQL; every value reaches the database through placeholders.
 *
 * @since 0.1.0
 */
abstract class AbstractRepository {

	/**
	 * Database object.
	 *
	 * @var wpdb
	 */
	protected $wpdb;

	/**
	 * Constructor.
	 *
	 * @param wpdb $wpdb WordPress database object.
	 */
	public function __construct( wpdb $wpdb ) {
		$this->wpdb = $wpdb;
	}

	/**
	 * Prepares a query. Queries without placeholders are returned as they are,
	 * because `wpdb::prepare()` rejects them.
	 *
	 * @param string            $sql    SQL with placeholders. Table names are interpolated by the caller from the Tables whitelist.
	 * @param array<int, mixed> $params Values for the placeholders.
	 * @return string
	 */
	protected function prepare( string $sql, array $params = array() ): string {
		if ( array() === $params ) {
			return $sql;
		}

		return $this->wpdb->prepare( $sql, $params ); // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared,WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare -- Placeholders are built by the calling repository.
	}

	/**
	 * Placeholder formats in the same order as the keys of a row.
	 *
	 * @param array<string, string> $columns Column to format map, for example `array( 'name' => '%s' )`.
	 * @param array<string, mixed>  $row     Column values.
	 * @return string[]
	 */
	protected function formats( array $columns, array $row ): array {
		return array_map(
			static function ( string $column ) use ( $columns ) {
				return $columns[ $column ] ?? '%s';
			},
			array_keys( $row )
		);
	}

	/**
	 * Runs a SELECT that returns rows.
	 *
	 * @param string            $sql    SQL with placeholders.
	 * @param array<int, mixed> $params Values.
	 * @return array<int, array<string, mixed>>
	 */
	protected function rows( string $sql, array $params = array() ): array {
		$rows = $this->wpdb->get_results( $this->prepare( $sql, $params ), ARRAY_A ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.NotPrepared,PluginCheck.Security.DirectDB.UnescapedDBParameter -- Prepared by prepare().

		return is_array( $rows ) ? $rows : array();
	}

	/**
	 * Runs a SELECT that returns one row.
	 *
	 * @param string            $sql    SQL with placeholders.
	 * @param array<int, mixed> $params Values.
	 * @return array<string, mixed>|null
	 */
	protected function row( string $sql, array $params = array() ): ?array {
		$row = $this->wpdb->get_row( $this->prepare( $sql, $params ), ARRAY_A ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.NotPrepared,PluginCheck.Security.DirectDB.UnescapedDBParameter -- Prepared by prepare().

		return is_array( $row ) ? $row : null;
	}

	/**
	 * Runs a SELECT that returns one value.
	 *
	 * @param string            $sql    SQL with placeholders.
	 * @param array<int, mixed> $params Values.
	 * @return string|null
	 */
	protected function value( string $sql, array $params = array() ): ?string {
		return $this->wpdb->get_var( $this->prepare( $sql, $params ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.NotPrepared,PluginCheck.Security.DirectDB.UnescapedDBParameter -- Prepared by prepare().
	}

	/**
	 * Inserts a row and returns its id, or 0 on failure.
	 *
	 * @param string               $table   Full table name.
	 * @param array<string, mixed> $data    Column values.
	 * @param string[]             $formats Placeholder formats in the order of `$data`.
	 * @return int
	 */
	protected function insert_row( string $table, array $data, array $formats ): int {
		$ok = $this->wpdb->insert( $table, $data, $formats ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching

		return false === $ok ? 0 : (int) $this->wpdb->insert_id;
	}
}