<?php
/**
 * Gate for migration diagnostics.
 *
 * @package Shiftora\Logging
 */

declare(strict_types=1);

namespace Shiftora\Logging;

// Prevent direct file access.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * One answer to "should diagnostics run?", shared by the database logger, the
 * browser console and the detail a receiver returns to a sender.
 *
 * Two independent switches, both off by default: the `shiftora_debug` option
 * the Settings screen writes, and WP_DEBUG on a build not declaring itself production.
 */
final class ShiftoraDebug {

	/** Option the admin toggle writes. */
	public const OPTION = 'shiftora_debug';

	/**
	 * Memoized verdict, so a per-chunk logging path pays for the check once.
	 *
	 * @var array{on:bool,source:string}|null
	 */
	private static ?array $verdict = null;

	/**
	 * Overrides the ambient WP_DEBUG / WP_ENVIRONMENT_TYPE read.
	 *
	 * @var callable|null
	 */
	private static $probe = null;

	/** Whether diagnostics should be collected on this site. */
	public static function enabled(): bool {
		return self::verdict()['on'];
	}

	/** What turned diagnostics on: 'option', 'wp_debug', or '' when off. Logged with a trace so a verbose run can explain itself. */
	public static function source(): string {
		return self::verdict()['source'];
	}

	/** Replaces the environment probe; null restores the real one. */
	public static function set_probe( ?callable $probe ): void {
		self::$probe = $probe;
	}

	/** Drops the memoized verdict. */
	public static function flush(): void {
		self::$verdict = null;
	}

	/**
	 * @return array{on:bool,source:string}
	 */
	private static function verdict(): array {
		if ( null !== self::$verdict ) {
			return self::$verdict;
		}

		// The option comes first so an opt-in works with WP_DEBUG off and the reported source names the switch used.
		if ( (bool) get_option( self::OPTION, 0 ) ) {
			return self::$verdict = [ 'on' => true, 'source' => 'option' ];
		}

		$env = null !== self::$probe ? ( self::$probe )() : self::probe();

		$on = ! empty( $env['wp_debug'] ) && 'production' !== ( $env['env'] ?? null );

		return self::$verdict = [ 'on' => $on, 'source' => $on ? 'wp_debug' : '' ];
	}

	/**
	 * Reads the ambient build flags.
	 *
	 * @return array{wp_debug:bool,env:string|null}
	 */
	private static function probe(): array {
		return [
			'wp_debug' => defined( 'WP_DEBUG' ) && WP_DEBUG,
			'env'      => defined( 'WP_ENVIRONMENT_TYPE' ) ? (string) constant( 'WP_ENVIRONMENT_TYPE' ) : null,
		];
	}
}