<?php
/**
 * Stored times, as the REST API hands them out.
 *
 * @package AgentFirewall
 */

declare(strict_types=1);

namespace AgentFirewall\Support;

use DateTimeImmutable;
use DateTimeZone;

defined( 'ABSPATH' ) || exit; // @codeCoverageIgnore

/**
 * The plugin stores times as UTC wall-clock values (`Y-m-d H:i:s`). The
 * admin showed those strings as they were, so a site in New York read times
 * four hours off with nothing saying so (AF-23.2). Each displayed time now
 * also travels as ISO 8601 with its offset, which the admin converts to the
 * site's own timezone.
 */
final class Time {

	/**
	 * A stored time as ISO 8601, marked UTC.
	 *
	 * The wall-clock value is taken as UTC whatever timezone the object or
	 * PHP's default carries: WordPress sets UTC, but a value hydrated under
	 * another default would otherwise be shifted.
	 *
	 * @param DateTimeImmutable|string $stored A hydrated time, or the raw
	 *                                         database value.
	 * @return string ISO 8601, or '' when the value is not a stored time.
	 */
	public static function iso( DateTimeImmutable|string $stored ): string {
		$wall = $stored instanceof DateTimeImmutable ? $stored->format( 'Y-m-d H:i:s' ) : $stored;
		$utc  = DateTimeImmutable::createFromFormat( '!Y-m-d H:i:s', $wall, new DateTimeZone( 'UTC' ) );

		return false === $utc ? '' : $utc->format( DATE_ATOM );
	}
}