DateTimeHelper.php

<?php

use DateTimeImmutable;
use DateTimeZone;
use Exception;

final class DateTimeHelper
{
    /**
     * Timezone for Paris.
     */
    public const TIMEZONE_EUROPE_PARIS = 'Europe/Paris';

    /**
     * Default timezone.
     */
    public const DEFAULT_TIMEZONE = self::TIMEZONE_EUROPE_PARIS;

    /**
     * Common database format (e.g., MySQL DATETIME).
     * Example: 2025-07-03 14:30:00
     */
    public const DB_DATETIME = 'Y-m-d H:i:s';

    /**
     * Common date format.
     * Example: 2025-07-03
     */
    public const DB_DATE = 'Y-m-d';

    /**
     * Timestamp format for filenames, including milliseconds for uniqueness.
     * Example: 20250703-143000-123456
     */
    public const FILE_TIMESTAMP = 'Ymd-His-v';

    /**
     * Prevents the instantiation of this helper class.
     */
    private function __construct()
    {
    }

    /**
     * Returns the current date and time in a DateTimeImmutable object.
     *
     * @throws Exception
     */
    public static function now(string $timezone = self::DEFAULT_TIMEZONE): DateTimeImmutable
    {
        return new DateTimeImmutable('now', new DateTimeZone($timezone));
    }

    /**
     * Formats a DateTimeImmutable object to a database-friendly DATETIME string.
     */
    public static function getDbDatetime(DateTimeImmutable $date): string
    {
        return $date->format(self::DB_DATETIME);
    }

    /**
     * Formats a DateTimeImmutable object to a database-friendly DATE string.
     */
    public static function getDbDate(DateTimeImmutable $date): string
    {
        return $date->format(self::DB_DATE);
    }

    /**
     * Gets the hour from a DateTimeImmutable object (00-23).
     */
    public static function getHour(DateTimeImmutable $date): string
    {
        return $date->format('H');
    }

    /**
     * Gets the week number from a DateTimeImmutable object (01-53).
     */
    public static function getWeekNumber(DateTimeImmutable $date): string
    {
        return $date->format('W');
    }

    /**
     * Gets the day number of the year from a DateTimeImmutable object (0-365).
     */
    public static function getDayOfYear(DateTimeImmutable $date): string
    {
        return $date->format('z');
    }

    /**
     * Gets the day of the week from a DateTimeImmutable object (1 for Monday, 7 for Sunday).
     */
    public static function getDayOfWeek(DateTimeImmutable $date): string
    {
        return $date->format('N');
    }

    /**
     * Checks if the given date falls on a weekend (Saturday or Sunday).
     */
    public static function isWeekend(DateTimeImmutable $date): bool
    {
        return (int) $date->format('N') >= 6;
    }

    /**
     * Gets a formatted timestamp for file names, including milliseconds.
     */
    public static function getFileTimestamp(DateTimeImmutable $date): string
    {
        return $date->format(self::FILE_TIMESTAMP);
    }

    /**
     * Inserts a timestamp into a filename before its extension.
     *
     * @throws Exception
     */
    public static function insertTimestampToFileName(string $fileName): string
    {
        $info = pathinfo($fileName);
        $timestamp = self::getFileTimestamp(self::now());

        $baseName = $info['filename'] ?? '';
        $extension = $info['extension'] ?? '';

        $newFileName = $baseName . '-' . $timestamp;

        if (!empty($extension)) {
            $newFileName .= '.' . $extension;
        }

        return $newFileName;
    }
}