<?php
/**
 * Date and time helpers.
 *
 * @package Kordiam
 */

declare( strict_types=1 );

namespace Kordiam\Support;

use DateTimeImmutable;
use DateTimeZone;

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Every timestamp the plugin produces goes through here.
 *
 * Never call date(): UTC values come from gmdate(), site-local ones from current_time().
 */
final class Dates {

	/**
	 * MySQL datetime format.
	 *
	 * @var string
	 */
	public const MYSQL = 'Y-m-d H:i:s';

	/**
	 * Format Kordiam uses for the date part of a story schedule.
	 *
	 * @var string
	 */
	public const KORDIAM_DATE = 'Y-m-d';

	/**
	 * Format Kordiam uses for the time part of a story schedule.
	 *
	 * @var string
	 */
	public const KORDIAM_TIME = 'H:i';

	/**
	 * Site-local time that stands for "no time set" on a story.
	 *
	 * @var string
	 */
	public const END_OF_DAY = '23:59';

	/**
	 * Blocking instantiation: this class is a namespaced function group.
	 */
	private function __construct() {
	}

	/**
	 * Getting the current UTC time.
	 *
	 * @param string $format Date format.
	 *
	 * @return string Formatted UTC time.
	 */
	public static function now_utc( string $format = self::MYSQL ): string {
		return gmdate( $format );
	}

	/**
	 * Getting the current site-local time.
	 *
	 * @param string $format Date format.
	 *
	 * @return string Formatted local time.
	 */
	public static function now_local( string $format = self::MYSQL ): string {
		return (string) current_time( $format );
	}

	/**
	 * Getting a UTC timestamp a number of seconds into the future.
	 *
	 * @param int $seconds Offset from now.
	 *
	 * @return string Formatted UTC time.
	 */
	public static function utc_in( int $seconds ): string {
		return gmdate( self::MYSQL, time() + $seconds );
	}

	/**
	 * Formatting a Unix timestamp as UTC.
	 *
	 * @param int    $timestamp Unix timestamp.
	 * @param string $format    Date format.
	 *
	 * @return string Formatted UTC time.
	 */
	public static function format_utc( int $timestamp, string $format = self::MYSQL ): string {
		return gmdate( $format, $timestamp );
	}

	/**
	 * Converting a UTC datetime string into site-local time.
	 *
	 * @param string $utc_datetime UTC datetime in MySQL format.
	 *
	 * @return string Site-local datetime in MySQL format, or an empty string when unparseable.
	 */
	public static function utc_to_local( string $utc_datetime ): string {
		return self::convert( $utc_datetime, new DateTimeZone( 'UTC' ), wp_timezone() );
	}

	/**
	 * Converting a site-local datetime string into UTC.
	 *
	 * @param string $local_datetime Site-local datetime in MySQL format.
	 *
	 * @return string UTC datetime in MySQL format, or an empty string when unparseable.
	 */
	public static function local_to_utc( string $local_datetime ): string {
		return self::convert( $local_datetime, wp_timezone(), new DateTimeZone( 'UTC' ) );
	}

	/**
	 * Moving a MySQL datetime from one timezone to another.
	 *
	 * @param string       $datetime Datetime in MySQL format.
	 * @param DateTimeZone $from     Zone the value is in.
	 * @param DateTimeZone $to       Zone wanted.
	 *
	 * @return string Converted datetime, or an empty string when unparseable.
	 */
	private static function convert( string $datetime, DateTimeZone $from, DateTimeZone $to ): string {
		if ( ! self::matches_format( $datetime, self::MYSQL ) ) {
			return '';
		}

		$parsed = DateTimeImmutable::createFromFormat( '!' . self::MYSQL, $datetime, $from );

		return false === $parsed ? '' : $parsed->setTimezone( $to )->format( self::MYSQL );
	}

	/**
	 * Checking a string against a date format, strictly.
	 *
	 * PHP createFromFormat() accepts '2025-02-31' as 3 March, so the round trip is compared too.
	 *
	 * @param string $value  Value to check.
	 * @param string $format Expected format.
	 *
	 * @return bool Whether the value matches the format and denotes a real date.
	 */
	public static function matches_format( string $value, string $format ): bool {
		$date = DateTimeImmutable::createFromFormat( '!' . $format, $value, new DateTimeZone( 'UTC' ) );

		if ( false === $date ) {
			return false;
		}

		$errors = DateTimeImmutable::getLastErrors();

		if ( is_array( $errors ) && ( $errors['warning_count'] > 0 || $errors['error_count'] > 0 ) ) {
			return false;
		}

		return $date->format( $format ) === $value;
	}

	/**
	 * Parsing a date and optional time into a UTC MySQL datetime.
	 *
	 * @param string      $date Date in Kordiam's Y-m-d format.
	 * @param string|null $time Time in Kordiam's H:i format, when the story has one.
	 *
	 * @return string|null UTC datetime, or null when the input is not a real date.
	 */
	public static function from_kordiam( string $date, ?string $time = null ): ?string {
		if ( ! self::matches_format( $date, self::KORDIAM_DATE ) ) {
			return null;
		}

		if ( null === $time || '' === trim( $time ) ) {
			$utc = self::local_to_utc( $date . ' ' . self::END_OF_DAY . ':00' );

			return '' === $utc ? null : $utc;
		}

		if ( ! self::matches_format( $time, self::KORDIAM_TIME ) ) {
			return null;
		}

		$parsed = DateTimeImmutable::createFromFormat(
			'!' . self::KORDIAM_DATE . ' ' . self::KORDIAM_TIME,
			$date . ' ' . $time,
			new DateTimeZone( 'UTC' )
		);

		return false === $parsed ? null : $parsed->format( self::MYSQL );
	}
}