Skip to content

Instantly share code, notes, and snippets.

@jprivet-dev

jprivet-dev/DateTimeHelper.php

Created August 8, 2025 09:15
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jprivet-dev/52dd638d6f712a804263159cb46eb3c8 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jprivet-dev/52dd638d6f712a804263159cb46eb3c8 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. jprivet-dev created this gist Aug 8, 2025.
    139 changes: 139 additions & 0 deletions DateTimeHelper.php
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,139 @@
    <?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;
    }
    }