<?php
/**
 * Debug Utility Class
 *
 * Provides debugging functionality for development and troubleshooting.
 *
 * @package Gatewell
 * @subpackage Utilities
 * @since 1.0.0
 */

namespace Gatewell;

defined( 'ABSPATH' ) || exit;

/**
 * Class Debug
 *
 * The plugin's only logging sink. Every method here bails out unless
 * is_enabled() returns true, so nothing is written on a normal production site;
 * the site owner opts in by defining GATEWELL_DEBUG (or by running with
 * WP_DEBUG on). No other file in the plugin calls error_log() directly -- they
 * all go through Debug::log(), so debug output can never escape this gate.
 *
 * @since 1.0.0
 */
class Debug {

	/**
	 * Check if debug mode is enabled.
	 *
	 * Debug mode can be enabled via:
	 * 1. GATEWELL_DEBUG constant set to true
	 * 2. WP_DEBUG constant set to true (fallback)
	 *
	 * @return bool True if debug mode is enabled, false otherwise.
	 * @since 1.0.0
	 */
	public static function is_enabled() {
		// Check for plugin-specific debug constant.
		if ( defined( 'GATEWELL_DEBUG' ) && GATEWELL_DEBUG ) {
			return true;
		}

		// Fallback to WordPress debug mode.
		if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
			return true;
		}

		return false;
	}

	/**
	 * Log a message if debug mode is enabled.
	 *
	 * @param string $message Message to log.
	 * @param string $prefix Optional prefix for the log message (default: 'Gatewell').
	 * @since 1.0.0
	 */
	public static function log( $message, $prefix = 'Gatewell' ) {
		if ( ! self::is_enabled() ) {
			return;
		}

		if ( ! empty( $prefix ) ) {
			$message = '[' . $prefix . '] ' . $message;
		}

		// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- This class is the plugin's single logging sink and every public method returns early unless is_enabled() is true, i.e. unless the site owner set GATEWELL_DEBUG or WP_DEBUG. error_log() is the only way to write to the site's configured PHP error log, and nothing in the plugin calls it directly.
		error_log( $message );
	}

	/**
	 * Log a variable dump if debug mode is enabled.
	 *
	 * @param mixed  $var Variable to dump.
	 * @param string $label Optional label for the dump (default: empty).
	 * @since 1.0.0
	 */
	public static function dump( $var, $label = '' ) {
		if ( ! self::is_enabled() ) {
			return;
		}

		$output = '';
		if ( ! empty( $label ) ) {
			$output = '[Gatewell] ' . $label . ': ';
		} else {
			$output = '[Gatewell] Dump: ';
		}

		// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_print_r -- Debug-only variable dump, behind the same is_enabled() gate; print_r() is the point of the method.
		$output .= print_r( $var, true );

		// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- This class is the plugin's single logging sink and every public method returns early unless is_enabled() is true, i.e. unless the site owner set GATEWELL_DEBUG or WP_DEBUG. error_log() is the only way to write to the site's configured PHP error log, and nothing in the plugin calls it directly.
		error_log( $output );
	}

	/**
	 * Log an exception if debug mode is enabled.
	 *
	 * @param \Exception $exception Exception to log.
	 * @since 1.0.0
	 */
	public static function log_exception( \Exception $exception ) {
		if ( ! self::is_enabled() ) {
			return;
		}

		// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- This class is the plugin's single logging sink and every public method returns early unless is_enabled() is true, i.e. unless the site owner set GATEWELL_DEBUG or WP_DEBUG. error_log() is the only way to write to the site's configured PHP error log, and nothing in the plugin calls it directly.
		error_log( '[Gatewell] Exception: ' . $exception->getMessage() );
		// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- This class is the plugin's single logging sink and every public method returns early unless is_enabled() is true, i.e. unless the site owner set GATEWELL_DEBUG or WP_DEBUG. error_log() is the only way to write to the site's configured PHP error log, and nothing in the plugin calls it directly.
		error_log( '[Gatewell] Stack trace: ' . $exception->getTraceAsString() );
	}
}