<?php
/**
 * Debug-gated diagnostic logger.
 *
 * @package EncypherProvenance
 */

namespace EncypherProvenance;

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

/**
 * Single chokepoint around error_log().
 *
 * The plugin emits diagnostics ONLY when debugging is explicitly enabled, via
 * either the standard WP_DEBUG constant or the plugin-specific
 * ENCYPHER_PROVENANCE_DEBUG constant. With debugging off (the production
 * default) nothing is written. This keeps the plugin clear of the
 * WordPress-VIP-Go "no error_log in production" rule while preserving developer
 * diagnostics behind one greppable helper: every call site routes here instead
 * of calling error_log() directly.
 */
class Logger
{
    /**
     * Whether diagnostic logging is currently enabled.
     */
    public static function enabled(): bool
    {
        if (defined('ENCYPHER_PROVENANCE_DEBUG') && ENCYPHER_PROVENANCE_DEBUG) {
            return true;
        }

        return defined('WP_DEBUG') && WP_DEBUG;
    }

    /**
     * Write a diagnostic line, but only when logging is enabled.
     *
     * The message is passed through verbatim so existing call sites keep their
     * exact wording (and their own source prefixes) unchanged.
     *
     * @param string $message Fully-formed message to log.
     */
    public static function log(string $message): void
    {
        if (! self::enabled()) {
            return;
        }

        // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- single debug-gated logger chokepoint; only emits when WP_DEBUG or ENCYPHER_PROVENANCE_DEBUG is truthy.
        error_log($message);
    }
}
