bfw-systems / bfw

src/Helpers/Dates.php

<?php

namespace BFW\Helpers;

use \DateTime;
use \Exception;

/**
 * Class to have shortcuts to DateTime(Zone) methods and to display a date
 * with words and not only numbers (today, yesterday, since... etc).
 */
class Dates extends DateTime
{
    /**
     * @var string[] $humanReadableI18n Words used in method to transform
     *  date difference to human readable.
     */
    protected static $humanReadableI18n = [
        'now'          => 'now',
        'today_past'   => '{time} ago',
        'today_future' => 'in {time}',
        'yesterday'    => 'yesterday',
        'tomorrow'     => 'tomorrow',
        'others'       => 'the {date}',
        'time_part'    => ' at {time}'
    ];

    /**
     * @var string[] $humanReadableFormats Date and time formats used in
     *  method to transform date difference to human readable.
     */
    protected static $humanReadableFormats = [
        'dateSameYear'      => 'm-d',
        'dateDifferentYear' => 'Y-m-d',
        'time'              => 'H:i'
    ];

    /**
     * Return the value of the humanReadableI18n property
     * 
     * @return string[]
     */
    public static function getHumanReadableI18n(): array
    {
        return self::$humanReadableI18n;
    }

    /**
     * Define a new value for a key of the humanReadableI18n property
     * 
     * @param string $key The key in humanReadableI18n
     * @param string $value The new value for the key
     * 
     * @return void
     */
    public static function setHumanReadableI18nKey(string $key, string $value)
    {
        self::$humanReadableI18n[$key] = $value;
    }

    /**
     * Define a new value to the property humanReadableI18n
     * 
     * @param string[] $value The new value for the property
     * 
     * @return void
     */
    public static function setHumanReadableI18n(array $value)
    {
        self::$humanReadableI18n = $value;
    }

    /**
     * Return the value of the humanReadableFormats property
     * 
     * @return string[]
     */
    public static function getHumanReadableFormats(): array
    {
        return self::$humanReadableFormats;
    }

    /**
     * Define a new value for a key of the humanReadableFormats property
     * 
     * @param string $key The key in humanReadableFormats
     * @param string $value The new value for the key
     * 
     * @return void
     */
    public static function setHumanReadableFormatsKey(
        string $key,
        string $value
    ) {
        self::$humanReadableFormats[$key] = $value;
    }

    /**
     * Define a new value to the property humanReadableFormats
     * 
     * @param string[] $value The new value for the property
     * 
     * @return void
     */
    public static function setHumanReadableFormats(array $value)
    {
        self::$humanReadableFormats = $value;
    }

    /**
     * Return the date. Format is Y-m-d H:i:sO
     * 
     * @return string
     */
    public function getDate(): string
    {
        return parent::format('Y-m-d H:i:sO');
    }

    /**
     * Return a numeric representation of a year, 4 digits.
     * 
     * @return int
     */
    public function getYear(): int
    {
        return (int) parent::format('Y');
    }

    /**
     * Return the numeric representation of a month, without leading zeros.
     * The returned int format can not have leading zeros.
     * 
     * @return int
     */
    public function getMonth(): int
    {
        return (int) parent::format('m');
    }

    /**
     * Return the day of the month without leading zeros.
     * The returned int format can not have leading zeros.
     * 
     * @return int
     */
    public function getDay(): int
    {
        return (int) parent::format('d');
    }

    /**
     * Return 24-hour format without leading zeros.
     * The returned int format can not have leading zeros.
     * 
     * @return int
     */
    public function getHour(): int
    {
        return (int) parent::format('H');
    }

    /**
     * Return minutes, without leading zeros.
     * The returned int format can not have leading zeros.
     * 
     * @return int
     */
    public function getMinute(): int
    {
        return (int) parent::format('i');
    }

    /**
     * Return second, without leading zeros.
     * The returned int format can not have leading zeros.
     * 
     * @return int
     */
    public function getSecond(): int
    {
        return (int) parent::format('s');
    }

    /**
     * Return the difference to Greenwich time (GMT)
     * with colon between hours and minutes
     * 
     * @return string
     */
    public function getZone(): string
    {
        return parent::format('P');
    }
    
    /**
     * Return date's SQL format (postgresql format).
     * The return can be an array or a string.
     * 
     * @param boolean $returnArray (default false) True to return an array.
     * @param boolean $withZone (default false) True to include the timezone
     *  into the time returned data.
     * 
     * @return string[]|string
     */
    public function getSqlFormat(
        bool $returnArray = false,
        bool $withZone = false
    ) {
        $date = $this->format('Y-m-d');
        $time = $this->format('H:i:s');
        
        if ($withZone === true) {
            $time .= $this->format('O');
        }

        if ($returnArray) {
            return [$date, $time];
        }

        return $date.' '.$time;
    }

    /**
     * List all timezone existing in current php version
     * 
     * @return string[]
     */
    public function lstTimeZone(): array
    {
        return parent::getTimezone()->listIdentifiers();
    }

    /**
     * List all continent define in php DateTimeZone.
     * 
     * @return string[]
     */
    public function lstTimeZoneContinent(): array
    {
        return [
            'Africa',
            'America',
            'Antartica',
            'Arctic',
            'Asia',
            'Atlantic',
            'Australia',
            'Europe',
            'Indian',
            'Pacific'
        ];
    }

    /**
     * List all available country for a continent
     * 
     * @param string $continent The continent for which we want
     *  the countries list
     * 
     * @return string[]
     */
    public function lstTimeZoneCountries(string $continent): array
    {
        $allCountries = $this->lstTimeZone();
        $countries    = [];

        foreach ($allCountries as $country) {
            if (strpos($country, $continent) !== false) {
                $countries[] = $country;
            }
        }

        return $countries;
    }

    /**
     * Transform a date to a human readable format
     * 
     * @param boolean $returnDateAndTime (default true) True to return date and
     *  time concatenated with a space. False to have only date.
     * 
     * @return string
     */
    public function humanReadable(bool $returnDateAndTime = true): string
    {
        $current = new Dates;
        $diff    = parent::diff($current);
        
        $parsedTxt = new class {
            public $date = '';
            public $time = '';
        };

        if ($current == $this) {
            //Now
            $this->humanDateNow($parsedTxt);
        } elseif (
            $this->humanDateIsYesterdayOrTomorrow($diff, $current) === true

It seems like $diff can also be of type false; however, parameter $diff of BFW\Helpers\Dates::humanDateIsYesterdayOrTomorrow() does only seem to accept DateInterval, maybe add an additional type check?

        ) {
            if ($diff->invert === 0) {
                $this->humanDateYesterday($parsedTxt); //Yesterday
            } else {
                $this->humanDateTomorrow($parsedTxt); //Tomorrow
            }
        } elseif ($diff->days === 0) {
            //Today
            $this->humanDateToday($parsedTxt, $diff);

It seems like $diff can also be of type false; however, parameter $diff of BFW\Helpers\Dates::humanDateToday() does only seem to accept DateInterval, maybe add an additional type check?

        } else {
            $this->humanDateOther($parsedTxt, $current);
        }

        $txtReturned = $parsedTxt->date;
        if ($returnDateAndTime === true && $parsedTxt->time !== '') {
            $txtReturned .= $parsedTxt->time;
        }

        return $txtReturned;
    }
    
    /**
     * Check if the date to read for humanReadable is yesterday or tomorrow.
     * 
     * We cannot only check the property "d" of DateInterval because it's a
     * range of +/- 24 to 48 hours. If we are at 48h before, it's not ok.
     * 
     * @param \DateInterval $diff Interval between now and date to read
     * @param DateTime $current DateTime object for now
     * 
     * @return bool
     */
    protected function humanDateIsYesterdayOrTomorrow(
        \DateInterval $diff,
        \DateTime $current
    ): bool {
        //To check the range from 24h to 48h
        if (($diff->d === 1 && $diff->m === 0 && $diff->y === 0) === false) {
            return false;
        }
        
        /**
         * With $diff->d === 1, we know if we are in range from 24h to 48h.
         * But yesterday or tomorrow day can finish into the range.
         * 
         * Example :
         * 
         *    [---03/10---][---04/10---][---05/10---]
         * ---|----|-------|----|-------|----|------
         *       -48h         -24h         $this
         *         [ $diff->d=1 ]
         * 
         * Like we can see, the $diff->d=1 is not only on the 04/10, but also
         * on 03/10 because the range is from 24h to 48h before the date.
         * So we need a check to not display "yesterday" for the 03/10.
         */
        
        $twoDays = clone $current;
        if ($diff->invert === 0) {
            $twoDays->modify('-2 days');
        } else {
            $twoDays->modify('+2 days');
        }
        
        if ($this->format('d') === $twoDays->format('d')) {
            return false;
        }
        
        return true;
    }
    
    /**
     * Format date to human readable when the date is now
     * 
     * @param object $parsedTxt Texts returned by humanReadable method
     * 
     * @return void
     */
    protected function humanDateNow($parsedTxt)
    {
        $currentClass    = get_called_class();
        $parsedTxt->date = $currentClass::$humanReadableI18n['now'];

The property humanReadableI18n does not exist on string.

    }
    
    /**
     * Format date to human readable when date is today
     * 
     * @param object $parsedTxt Texts returned by humanReadable method
     * @param \DateInterval $diff Interval between now and date to read
     * 
     * @return void
     */
    protected function humanDateToday($parsedTxt, \DateInterval $diff)
    {
        $textKey = 'today_past';
        if ($diff->invert === 1) {
            $textKey = 'today_future';
        }
        
        $time = '';
        if ($diff->h === 0 && $diff->i === 0) {
            $time .= $diff->s.'s';
        } elseif ($diff->h === 0) {
            $time .= $diff->i.'min';
        } else {
            $time .= $diff->h.'h';
        }
        
        $currentClass    = get_called_class();
        $parsedTxt->date = $currentClass::$humanReadableI18n[$textKey];

The property humanReadableI18n does not exist on string.

        
        $this->humanParseDateAndTimeText($parsedTxt, '', $time);
    }
    
    /**
     * Format date to human readable when date is yesterday
     * 
     * @param object $parsedTxt Texts returned by humanReadable method
     * 
     * @return void
     */
    protected function humanDateYesterday($parsedTxt)
    {
        $currentClass    = get_called_class();
        $parsedTxt->date = $currentClass::$humanReadableI18n['yesterday'];

The property humanReadableI18n does not exist on string.

        $parsedTxt->time = $currentClass::$humanReadableI18n['time_part'];
        
        $time = $this->format($currentClass::$humanReadableFormats['time']);

The property humanReadableFormats does not exist on string.

        
        $this->humanParseDateAndTimeText($parsedTxt, '', $time);
    }
    
    /**
     * Format date to human readable when date is tomorrow
     * 
     * @param object $parsedTxt Texts returned by humanReadable method
     * 
     * @return void
     */
    protected function humanDateTomorrow($parsedTxt)
    {
        $currentClass    = get_called_class();
        $parsedTxt->date = $currentClass::$humanReadableI18n['tomorrow'];

The property humanReadableI18n does not exist on string.

        $parsedTxt->time = $currentClass::$humanReadableI18n['time_part'];
        
        $time = $this->format($currentClass::$humanReadableFormats['time']);

The property humanReadableFormats does not exist on string.

        
        $this->humanParseDateAndTimeText($parsedTxt, '', $time);
    }
    
    /**
     * Format date to human readable when date is not now, today or yesterday
     * 
     * @param object $parsedTxt Texts returned by humanReadable method
     * @param \DateTime $current DateTime object for now
     * 
     * @return void
     */
    protected function humanDateOther($parsedTxt, \DateTime $current)
    {
        $currentClass = get_called_class();
        
        $dateFormat = $currentClass::$humanReadableFormats['dateDifferentYear'];

The property humanReadableFormats does not exist on string.

        if ($current->format('Y') === $this->format('Y')) {
            $dateFormat = $currentClass::$humanReadableFormats['dateSameYear'];
        }
        
        $parsedTxt->date = $currentClass::$humanReadableI18n['others'];

The property humanReadableI18n does not exist on string.

        $parsedTxt->time = $currentClass::$humanReadableI18n['time_part'];
        
        $date = $this->format($dateFormat);
        $time = $this->format($currentClass::$humanReadableFormats['time']);
        
        $this->humanParseDateAndTimeText($parsedTxt, $date, $time);
    }
    
    /**
     * Replace the expression "{date}" by the $date value and the expression
     * "{time}" by the $time value into properties "date" and "time" of the
     * $parsedTxt object.
     * 
     * @param object $parsedTxt Texts returned by humanReadable method
     * @param string $date The date value used to replace "{date}" into texts
     * @param string $time The time value used to replace "{time}" into texts
     * 
     * @return void
     */
    protected function humanParseDateAndTimeText(
        $parsedTxt,
        string $date,
        string $time
    ) {
        $parsedTxt->date = str_replace('{date}', $date, $parsedTxt->date);
        $parsedTxt->date = str_replace('{time}', $time, $parsedTxt->date);
        
        $parsedTxt->time = str_replace('{date}', $date, $parsedTxt->time);
        $parsedTxt->time = str_replace('{time}', $time, $parsedTxt->time);
    }
}