<?php
declare(strict_types=1);

namespace WebCalendar\WP\Integrations\QueryMonitor;

defined( 'ABSPATH' ) || exit;

// phpcs:ignore WordPress.DB.RestrictedClasses.mysql__PDO -- PDO wrapper for Query Monitor tracing of webcalendar-core queries.
use PDO;
// phpcs:ignore WordPress.DB.RestrictedClasses.mysql__PDO
use PDOStatement;

/**
 * PDO wrapper that records query execution for Query Monitor.
 *
 * When Query Monitor is active, PdoFactory injects this wrapper instead
 * of a plain PDO. Each prepare()/execute() pair is logged so queries
 * appear in QM's database panel.
 *
 * @codeCoverageIgnore -- Thin PDO passthrough; only exercised with Query Monitor installed.
 */
final class TracingPdo extends PDO {

	/**
	 * Recorded queries.
	 *
	 * @var array<int, array{sql: string, time: float, caller: string}>
	 */
	private array $queries = [];

	/**
	 * Prepare a statement and return a tracing wrapper.
	 *
	 * @param string $query SQL query.
	 * @param array<int, mixed> $options Driver options.
	 * @return TracingPdoStatement|false
	 */
	#[\Override]
	public function prepare( string $query, array $options = [] ): TracingPdoStatement|false {
		$stmt = parent::prepare( $query, $options );
		if ( $stmt === false ) {
			return false;
		}

		return new TracingPdoStatement( $stmt, $query, $this );
	}

	/**
	 * Record a query execution.
	 *
	 * @param string $sql    The SQL query.
	 * @param float  $time   Execution time in seconds.
	 * @param string $caller Calling function/method.
	 */
	public function record_query( string $sql, float $time, string $caller ): void {
		$this->queries[] = [
			'sql'    => $sql,
			'time'   => $time,
			'caller' => $caller,
		];
	}

	/**
	 * Get all recorded queries.
	 *
	 * @return array<int, array{sql: string, time: float, caller: string}>
	 */
	public function get_queries(): array {
		return $this->queries;
	}
}