<?php
/**
 * Severity-gated logging facade.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Logging;

/**
 * Severity-gated logging facade.
 *
 * Writes through `error_log()` with a `[Postlinkly]` prefix and a severity
 * tag. `debug` and `info` are gated by `WP_DEBUG` to keep production logs
 * clean. `warning` and `error` always fire.
 *
 * Format strings use printf placeholders; arguments come in the second
 * parameter to keep call sites grep-friendly:
 *
 *     Logger::debug( 'Matched %d candidates for post %d', [ $n, $post_id ] );
 *
 * @since 1.0.0
 */
final class Logger {

	private const SEVERITY_DEBUG   = 'DEBUG';
	private const SEVERITY_INFO    = 'INFO';
	private const SEVERITY_WARNING = 'WARNING';
	private const SEVERITY_ERROR   = 'ERROR';

	/**
	 * Writes a debug-severity message. Only fires when `WP_DEBUG` is true.
	 *
	 * @since 1.0.0
	 *
	 * @param string             $message Format string (printf-style).
	 * @param array<int, mixed>  $args    Optional. Arguments for the format string.
	 *
	 * @return void
	 */
	public static function debug( string $message, array $args = array() ): void {
		if ( ! self::is_debug_enabled() ) {
			return;
		}
		self::write( self::SEVERITY_DEBUG, $message, $args );
	}

	/**
	 * Writes an info-severity message. Only fires when `WP_DEBUG` is true.
	 *
	 * @since 1.0.0
	 *
	 * @param string             $message Format string (printf-style).
	 * @param array<int, mixed>  $args    Optional. Arguments for the format string.
	 *
	 * @return void
	 */
	public static function info( string $message, array $args = array() ): void {
		if ( ! self::is_debug_enabled() ) {
			return;
		}
		self::write( self::SEVERITY_INFO, $message, $args );
	}

	/**
	 * Writes a warning-severity message. Always fires.
	 *
	 * @since 1.0.0
	 *
	 * @param string             $message Format string (printf-style).
	 * @param array<int, mixed>  $args    Optional. Arguments for the format string.
	 *
	 * @return void
	 */
	public static function warning( string $message, array $args = array() ): void {
		self::write( self::SEVERITY_WARNING, $message, $args );
	}

	/**
	 * Writes an error-severity message. Always fires.
	 *
	 * @since 1.0.0
	 *
	 * @param string             $message Format string (printf-style).
	 * @param array<int, mixed>  $args    Optional. Arguments for the format string.
	 *
	 * @return void
	 */
	public static function error( string $message, array $args = array() ): void {
		self::write( self::SEVERITY_ERROR, $message, $args );
	}

	/**
	 * Returns whether debug-level logging is enabled.
	 *
	 * @since 1.0.0
	 *
	 * @return bool True when `WP_DEBUG` is defined and truthy.
	 */
	private static function is_debug_enabled(): bool {
		return defined( 'WP_DEBUG' ) && WP_DEBUG;
	}

	/**
	 * Composes the line and writes it to the PHP error log.
	 *
	 * @since 1.0.0
	 *
	 * @param string            $severity The severity tag.
	 * @param string            $message  Format string (printf-style).
	 * @param array<int, mixed> $args     Format string arguments.
	 *
	 * @return void
	 */
	private static function write( string $severity, string $message, array $args ): void {
		$formatted = empty( $args ) ? $message : vsprintf( $message, $args );
		// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- Logger is the single sanctioned wrapper for error_log.
		error_log( sprintf( '[Postlinkly][%s] %s', $severity, $formatted ) );
	}
}