<?php
declare(strict_types=1);

namespace WebCalendar\WP\Integrations\QueryMonitor;

defined( 'ABSPATH' ) || exit;

// phpcs:ignore WordPress.DB.RestrictedClasses.mysql__PDO
use PDOStatement;

/**
 * PDOStatement wrapper that records execution timing for Query Monitor.
 *
 * @codeCoverageIgnore -- Thin PDOStatement passthrough; only exercised with Query Monitor installed.
 */
final class TracingPdoStatement extends PDOStatement {

	/**
	 * Constructor.
	 *
	 * @param PDOStatement $inner The real statement.
	 * @param string       $sql   The SQL query string.
	 * @param TracingPdo   $pdo   The tracing PDO connection.
	 */
	public function __construct(
		private PDOStatement $inner,
		private string $sql,
		private TracingPdo $pdo,
	) {
	}

	/**
	 * Execute the prepared statement and record timing.
	 *
	 * @param array<string, mixed>|null $params Input parameters.
	 * @return bool
	 */
	#[\Override]
	public function execute( ?array $params = null ): bool {
		$start = microtime( true );

		$result = $this->inner->execute( $params );

		$elapsed = microtime( true ) - $start;

		// Walk up the call stack to find the caller outside this class.
		$caller = 'unknown';
		// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_debug_backtrace -- needed for Query Monitor caller attribution
		$trace = debug_backtrace( DEBUG_BACKTRACE_IGNORE_ARGS, 5 );
		foreach ( $trace as $frame ) {
			if ( isset( $frame['class'] ) && str_contains( $frame['class'], 'WebCalendar\\Core\\' ) ) {
				$caller = $frame['class'] . '::' . $frame['function'];
				break;
			}
		}

		$this->pdo->record_query( $this->sql, $elapsed, $caller );

		return $result;
	}

	/**
	 * Fetch the next row.
	 *
	 * @param int $mode Fetch mode.
	 * @param int $cursorOrientation Cursor orientation.
	 * @param int $cursorOffset Cursor offset.
	 * @return mixed
	 */
	#[\Override]
	// phpcs:ignore WordPress.DB.RestrictedClasses.mysql__PDO -- PDO constants required by PDOStatement interface
	public function fetch( int $mode = \PDO::FETCH_DEFAULT, int $cursorOrientation = \PDO::FETCH_ORI_NEXT, int $cursorOffset = 0 ): mixed {
		return $this->inner->fetch( $mode, $cursorOrientation, $cursorOffset );
	}

	/**
	 * Fetch all rows.
	 *
	 * @param int      $mode Fetch mode.
	 * @param mixed ...$args Additional arguments.
	 * @return array<int, mixed>
	 */
	#[\Override]
	// phpcs:ignore WordPress.DB.RestrictedClasses.mysql__PDO -- PDO constants required by PDOStatement interface
	public function fetchAll( int $mode = \PDO::FETCH_DEFAULT, mixed ...$args ): array {
		/** @phpstan-ignore argument.type (delegating variadic args to inner statement) */
		return $this->inner->fetchAll( $mode, ...$args );
	}

	/**
	 * Fetch a single column.
	 *
	 * @param int $column Column index.
	 * @return mixed
	 */
	#[\Override]
	public function fetchColumn( int $column = 0 ): mixed {
		return $this->inner->fetchColumn( $column );
	}

	/**
	 * Return the number of rows affected.
	 *
	 * @return int
	 */
	#[\Override]
	public function rowCount(): int {
		return $this->inner->rowCount();
	}

	/**
	 * Return the number of columns in the result set.
	 *
	 * @return int
	 */
	#[\Override]
	public function columnCount(): int {
		return $this->inner->columnCount();
	}

	/**
	 * Close the cursor.
	 *
	 * @return bool
	 */
	#[\Override]
	public function closeCursor(): bool {
		return $this->inner->closeCursor();
	}
}