<?php

namespace App\Framework\DateTime;

use App\Framework\DateTime\Exceptions\InvalidDateTimeException;
use App\Framework\DateTime\Exceptions\InvalidTimezoneException;
use DateTimeImmutable;
use Exception;

interface Clock
{
    /**
     * Gibt die aktuelle Zeit zurück.
     *
     * @return DateTimeImmutable
     */
    public function now(): DateTimeImmutable;

    /**
     * Erzeugt ein DateTimeImmutable-Objekt aus einem Zeitstempel.
     *
     * @param int $timestamp UNIX-Zeitstempel
     * @return DateTimeImmutable
     */
    public function fromTimestamp(int $timestamp): DateTimeImmutable;

    /**
     * Erzeugt ein DateTimeImmutable-Objekt aus einem String im angegebenen Format.
     *
     * @param string $dateTime Der zu parsende Zeitstring
     * @param string|null $format Optionales Format für die Analyse
     * @return DateTimeImmutable
     * @throws InvalidDateTimeException wenn das Parsen fehlschlägt
     * @throws InvalidTimezoneException wenn eine angegebene Zeitzone ungültig ist
     */
    public function fromString(string $dateTime, ?string $format = null): DateTimeImmutable;

    public function today(): DateTimeImmutable;

    public function yesterday(): DateTimeImmutable;

    public function tomorrow(): DateTimeImmutable;


    /**
     * Gibt den aktuellen UNIX-Zeitstempel zurück.
     *
     * @return int
     */
    public function time(): int;

    /**
     * Gibt den aktuellen Zeitstempel mit Mikrosekunden zurück.
     *
     * @param bool $asFloat Wenn true, wird ein float zurückgegeben, sonst ein Array
     * @return float|array{float, int}
     */
    public function microtime(bool $asFloat = false): float|array;
}
