Esi\Utility\Dates

Complexity

Total Complexity

13

Size/Duplication

Total Lines	132
Duplicated Lines	0 %

Test Coverage

Coverage

100%

Importance

Changes

0

<?php
final class Dates
{
    /**
     * Regex used to validate a given timestamp.
     *
     * @var string VALIDATE_TIMESTAMP_REGEX
     */
    public const VALIDATE_TIMESTAMP_REGEX = '/^\d{8,11}$/';

    /**
     * timeDifference()
     *
     * Formats the difference between two timestamps to be human-readable.
     *
     * @param   int     $timestampFrom  Starting unix timestamp.
     * @param   int     $timestampTo    Ending unix timestamp.
     * @param   string  $timezone       The timezone to use. Must be a valid timezone:
     *                                  {@see http://www.php.net/manual/en/timezones.php}
     * @param   string  $append         The string to append to the difference.
     *
     * @throws  InvalidArgumentException|RuntimeException|Exception
     */
    public static function timeDifference(int $timestampFrom, int $timestampTo = 0, string $timezone = 'UTC', string $append = ' old'): string
    {
        if ($timezone === '') {
            $timezone = 'UTC';
        }

        if (!Dates::validTimezone($timezone)) {
            throw new RuntimeException('$timezone appears to be invalid.');
        }

        // Normalize timestamps
        $timestampTo   = (Dates::validateTimestamp($timestampTo)) ? $timestampTo : time();
        $timestampFrom = (Dates::validateTimestamp($timestampFrom)) ? $timestampFrom : time();

        // This will generally only happen if the $timestampFrom was 0, or if it's invalid, as it is set to time();
        // as is $timestampTo if left at 0
        if ($timestampFrom >= $timestampTo) {
            throw new InvalidArgumentException('$timestampFrom needs to be less than $timestampTo.');
        }

        // Create DateTime objects and set timezone
        $timestampFrom = (new DateTime('@' . $timestampFrom))->setTimezone(new DateTimeZone($timezone));
        $timestampTo   = (new DateTime('@' . $timestampTo))->setTimezone(new DateTimeZone($timezone));

        // Calculate difference
        $difference = $timestampFrom->diff($timestampTo);

        // Format the difference
        $string = match (true) {
            $difference->y > 0  => $difference->y . ' year(s)',
            $difference->m > 0  => $difference->m . ' month(s)',
            $difference->d >= 7 => ceil($difference->d / 7) . ' week(s)',
            $difference->d > 0  => $difference->d . ' day(s)',
            $difference->h > 0  => $difference->h . ' hour(s)',
            $difference->i > 0  => $difference->i . ' minute(s)',
            $difference->s > 0  => $difference->s . ' second(s)',
            default             => ''
        };

        return $string . $append;
    }

    /**
     * timezoneInfo()
     *
     * Retrieves information about a timezone.
     *
     * Note: Must be a valid timezone recognized by PHP.
     *
     * @see http://www.php.net/manual/en/timezones.php
     *
     * @param   string  $timezone  The timezone to return information for.
     * @return  array<string, bool|float|int|string|null>
     *
     * @throws  InvalidArgumentException|RuntimeException|Exception
     */
    public static function timezoneInfo(string $timezone = 'UTC'): array
    {
        if ($timezone === '') {
            $timezone = 'UTC';
        }

        if (!Dates::validTimezone($timezone)) {
            throw new RuntimeException('$timezone appears to be invalid.');
        }

        $dateTimeZone = new DateTimeZone($timezone);

        $location = $dateTimeZone->getLocation();

        return [
            'offset'    => $dateTimeZone->getOffset(new DateTime('now', new DateTimeZone('GMT'))) / 3_600,

A parse error occurred: Syntax error, unexpected T_STRING, expecting ',' or ']' on line 145 at column 101

            'country'   => $location['country_code'] ?? 'N/A',
            'latitude'  => $location['latitude'] ?? 'N/A',
            'longitude' => $location['longitude'] ?? 'N/A',
            'dst'       => $dateTimeZone->getTransitions(time(), time())[0]['isdst'] ?? null,
        ];
    }

    /**
     * Determines if a given timezone is valid, according to
     * {@link http://www.php.net/manual/en/timezones.php}.
     *
     * @param   string  $timezone  The timezone to validate.
     */
    public static function validTimezone(string $timezone): bool
    {
        static $validTimezones;

        $validTimezones ??= DateTimeZone::listIdentifiers();
        return Arrays::exists($validTimezones, $timezone);
    }

    /**
     * Determines if a given timestamp matches the valid range that is typically
     * found in a unix timestamp (at least in PHP).
     *
     * Typically, a timestamp for PHP can be valid if it is either 0 or between 8 and 11 digits in length.
     *
     * @param   int   $timestamp  The timestamp to validate.
     */
    public static function validateTimestamp(int $timestamp): bool
    {
        if ($timestamp === 0 || $timestamp < 0) {
            return false;
        }
        return (preg_match(self::VALIDATE_TIMESTAMP_REGEX, (string) $timestamp) === 1);
    }
}