<?php
/**
 * Database helper wrappers for direct $wpdb calls.
 *
 * Centralizes phpcs:ignore for WordPress.DB.DirectDatabaseQuery so individual
 * call sites don't need inline suppression comments.
 *
 * All query parameters are expected to be already sanitized via $wpdb->prepare()
 * at the call site before being passed to these wrappers.
 *
 * @package MyTrailCamera
 * @since 8.3.0
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Wrapper for $wpdb->get_var().
 *
 * @param string|null $query SQL query (already prepared via $wpdb->prepare()).
 * @return string|null Database query result.
 */
function mtcam_db_get_var( $query = null ) {
	global $wpdb;
	// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- $query is prepared by the caller via $wpdb->prepare().
	return $wpdb->get_var( $query );
}

/**
 * Wrapper for $wpdb->get_row().
 *
 * @param string|null $query  SQL query (already prepared via $wpdb->prepare()).
 * @param string      $output Output type (OBJECT, ARRAY_A, ARRAY_N).
 * @return object|array|null Database query result.
 */
function mtcam_db_get_row( $query = null, $output = OBJECT ) {
	global $wpdb;
	// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- $query is prepared by the caller via $wpdb->prepare().
	return $wpdb->get_row( $query, $output );
}

/**
 * Wrapper for $wpdb->get_results().
 *
 * @param string $query  SQL query (already prepared via $wpdb->prepare()).
 * @param string $output Output type (OBJECT, ARRAY_A, ARRAY_N).
 * @return array|object|null Database query results.
 */
function mtcam_db_get_results( $query = null, $output = OBJECT ) {
	global $wpdb;
	// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- $query is prepared by the caller via $wpdb->prepare().
	return $wpdb->get_results( $query, $output );
}

/**
 * Wrapper for $wpdb->get_col().
 *
 * @param string|null $query SQL query (already prepared via $wpdb->prepare()).
 * @return array Database query result as array of column values.
 */
function mtcam_db_get_col( $query = null ) {
	global $wpdb;
	// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- $query is prepared by the caller via $wpdb->prepare().
	return $wpdb->get_col( $query );
}

/**
 * Wrapper for $wpdb->query().
 *
 * @param string $query SQL query (already prepared via $wpdb->prepare()).
 * @return int|bool Number of rows affected/selected or false on error.
 */
function mtcam_db_query( $query ) {
	global $wpdb;
	// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- $query is prepared by the caller via $wpdb->prepare().
	return $wpdb->query( $query );
}

/**
 * Wrapper for $wpdb->insert().
 *
 * @param string       $table  Table name.
 * @param array        $data   Column => value pairs.
 * @param array|string $format Optional format array.
 * @return int|false Number of rows inserted or false on error.
 */
function mtcam_db_insert( $table, $data, $format = null ) {
	global $wpdb;
	// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
	return $wpdb->insert( $table, $data, $format );
}

/**
 * Get the ID generated by the last INSERT query.
 *
 * @return int Last insert ID.
 */
function mtcam_db_insert_id() {
	global $wpdb;
	return $wpdb->insert_id;
}

/**
 * Wrapper for $wpdb->update().
 *
 * @param string       $table        Table name.
 * @param array        $data         Column => value pairs to update.
 * @param array        $where        WHERE clause column => value pairs.
 * @param array|string $format       Optional data format array.
 * @param array|string $where_format Optional WHERE format array.
 * @return int|false Number of rows updated or false on error.
 */
function mtcam_db_update( $table, $data, $where, $format = null, $where_format = null ) {
	global $wpdb;
	// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Write operation, caching not applicable.
	return $wpdb->update( $table, $data, $where, $format, $where_format );
}

/**
 * Wrapper for $wpdb->delete().
 *
 * @param string       $table        Table name.
 * @param array        $where        WHERE clause column => value pairs.
 * @param array|string $where_format Optional format array.
 * @return int|false Number of rows deleted or false on error.
 */
function mtcam_db_delete( $table, $where, $where_format = null ) {
	global $wpdb;
	// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Write operation, caching not applicable.
	return $wpdb->delete( $table, $where, $where_format );
}
