Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Datetime;
Chris@0: 
Chris@0: /**
Chris@0:  * Defines Gregorian Calendar date values.
Chris@0:  *
Chris@0:  * Lots of helpful functions for use in massaging dates, specific to the
Chris@0:  * Gregorian calendar system. The values include both translated and
Chris@0:  * untranslated values.
Chris@0:  *
Chris@0:  * Untranslated values are useful as array keys and as css identifiers, and
Chris@0:  * should be listed in English.
Chris@0:  *
Chris@0:  * Translated values are useful for display to the user. All values that need
Chris@0:  * translation should be hard-coded and wrapped in t() so the translation system
Chris@0:  * will be able to process them.
Chris@0:  */
Chris@0: class DateHelper {
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs an untranslated array of month names.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of month names.
Chris@0:    */
Chris@0:   public static function monthNamesUntranslated() {
Chris@0:     // Force the key to use the correct month value, rather than
Chris@0:     // starting with zero.
Chris@0:     return [
Chris@0:       1  => 'January',
Chris@0:       2  => 'February',
Chris@0:       3  => 'March',
Chris@0:       4  => 'April',
Chris@0:       5  => 'May',
Chris@0:       6  => 'June',
Chris@0:       7  => 'July',
Chris@0:       8  => 'August',
Chris@0:       9  => 'September',
Chris@0:       10 => 'October',
Chris@0:       11 => 'November',
Chris@0:       12 => 'December',
Chris@0:     ];
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs an untranslated array of abbreviated month names.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of month names.
Chris@0:    */
Chris@0:   public static function monthNamesAbbrUntranslated() {
Chris@0:     // Force the key to use the correct month value, rather than
Chris@0:     // starting with zero.
Chris@0:     return [
Chris@0:       1  => 'Jan',
Chris@0:       2  => 'Feb',
Chris@0:       3  => 'Mar',
Chris@0:       4  => 'Apr',
Chris@0:       5  => 'May',
Chris@0:       6  => 'Jun',
Chris@0:       7  => 'Jul',
Chris@0:       8  => 'Aug',
Chris@0:       9  => 'Sep',
Chris@0:       10 => 'Oct',
Chris@0:       11 => 'Nov',
Chris@0:       12 => 'Dec',
Chris@0:     ];
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a translated array of month names.
Chris@0:    *
Chris@0:    * @param bool $required
Chris@0:    *   (optional) If FALSE, the returned array will include a blank value.
Chris@0:    *   Defaults to FALSE.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of month names.
Chris@0:    */
Chris@0:   public static function monthNames($required = FALSE) {
Chris@0:     // Force the key to use the correct month value, rather than
Chris@0:     // starting with zero.
Chris@0:     $monthnames = [
Chris@0:       1  => t('January', [], ['context' => 'Long month name']),
Chris@0:       2  => t('February', [], ['context' => 'Long month name']),
Chris@0:       3  => t('March', [], ['context' => 'Long month name']),
Chris@0:       4  => t('April', [], ['context' => 'Long month name']),
Chris@0:       5  => t('May', [], ['context' => 'Long month name']),
Chris@0:       6  => t('June', [], ['context' => 'Long month name']),
Chris@0:       7  => t('July', [], ['context' => 'Long month name']),
Chris@0:       8  => t('August', [], ['context' => 'Long month name']),
Chris@0:       9  => t('September', [], ['context' => 'Long month name']),
Chris@0:       10 => t('October', [], ['context' => 'Long month name']),
Chris@0:       11 => t('November', [], ['context' => 'Long month name']),
Chris@0:       12 => t('December', [], ['context' => 'Long month name']),
Chris@0:     ];
Chris@0:     $none = ['' => ''];
Chris@0:     return !$required ? $none + $monthnames : $monthnames;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs a translated array of month name abbreviations
Chris@0:    *
Chris@0:    * @param bool $required
Chris@0:    *   (optional) If FALSE, the returned array will include a blank value.
Chris@0:    *   Defaults to FALSE.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of month abbreviations.
Chris@0:    */
Chris@0:   public static function monthNamesAbbr($required = FALSE) {
Chris@0:     // Force the key to use the correct month value, rather than
Chris@0:     // starting with zero.
Chris@0:     $monthnames = [
Chris@0:       1  => t('Jan', [], ['context' => 'Abbreviated month name']),
Chris@0:       2  => t('Feb', [], ['context' => 'Abbreviated month name']),
Chris@0:       3  => t('Mar', [], ['context' => 'Abbreviated month name']),
Chris@0:       4  => t('Apr', [], ['context' => 'Abbreviated month name']),
Chris@0:       5  => t('May', [], ['context' => 'Abbreviated month name']),
Chris@0:       6  => t('Jun', [], ['context' => 'Abbreviated month name']),
Chris@0:       7  => t('Jul', [], ['context' => 'Abbreviated month name']),
Chris@0:       8  => t('Aug', [], ['context' => 'Abbreviated month name']),
Chris@0:       9  => t('Sep', [], ['context' => 'Abbreviated month name']),
Chris@0:       10 => t('Oct', [], ['context' => 'Abbreviated month name']),
Chris@0:       11 => t('Nov', [], ['context' => 'Abbreviated month name']),
Chris@0:       12 => t('Dec', [], ['context' => 'Abbreviated month name']),
Chris@0:     ];
Chris@0:     $none = ['' => ''];
Chris@0:     return !$required ? $none + $monthnames : $monthnames;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs an untranslated array of week days.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of week day names
Chris@0:    */
Chris@0:   public static function weekDaysUntranslated() {
Chris@0:     return [
Chris@0:       'Sunday',
Chris@0:       'Monday',
Chris@0:       'Tuesday',
Chris@0:       'Wednesday',
Chris@0:       'Thursday',
Chris@0:       'Friday',
Chris@0:       'Saturday',
Chris@0:     ];
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns a translated array of week names.
Chris@0:    *
Chris@0:    * @param bool $required
Chris@0:    *   (optional) If FALSE, the returned array will include a blank value.
Chris@0:    *   Defaults to FALSE.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of week day names
Chris@0:    */
Chris@0:   public static function weekDays($required = FALSE) {
Chris@0:     $weekdays = [
Chris@0:       t('Sunday'),
Chris@0:       t('Monday'),
Chris@0:       t('Tuesday'),
Chris@0:       t('Wednesday'),
Chris@0:       t('Thursday'),
Chris@0:       t('Friday'),
Chris@0:       t('Saturday'),
Chris@0:     ];
Chris@0:     $none = ['' => ''];
Chris@0:     return !$required ? $none + $weekdays : $weekdays;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs a translated array of week day abbreviations.
Chris@0:    *
Chris@0:    * @param bool $required
Chris@0:    *   (optional) If FALSE, the returned array will include a blank value.
Chris@0:    *   Defaults to FALSE.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of week day abbreviations
Chris@0:    */
Chris@0:   public static function weekDaysAbbr($required = FALSE) {
Chris@0:     $weekdays = [
Chris@0:       t('Sun', [], ['context' => 'Abbreviated weekday']),
Chris@0:       t('Mon', [], ['context' => 'Abbreviated weekday']),
Chris@0:       t('Tue', [], ['context' => 'Abbreviated weekday']),
Chris@0:       t('Wed', [], ['context' => 'Abbreviated weekday']),
Chris@0:       t('Thu', [], ['context' => 'Abbreviated weekday']),
Chris@0:       t('Fri', [], ['context' => 'Abbreviated weekday']),
Chris@0:       t('Sat', [], ['context' => 'Abbreviated weekday']),
Chris@0:     ];
Chris@0:     $none = ['' => ''];
Chris@0:     return !$required ? $none + $weekdays : $weekdays;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs a translated array of 2-letter week day abbreviations.
Chris@0:    *
Chris@0:    * @param bool $required
Chris@0:    *   (optional) If FALSE, the returned array will include a blank value.
Chris@0:    *   Defaults to FALSE.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of week day 2 letter abbreviations
Chris@0:    */
Chris@0:   public static function weekDaysAbbr2($required = FALSE) {
Chris@0:     $weekdays = [
Chris@0:       t('Su', [], ['context' => 'Abbreviated weekday']),
Chris@0:       t('Mo', [], ['context' => 'Abbreviated weekday']),
Chris@0:       t('Tu', [], ['context' => 'Abbreviated weekday']),
Chris@0:       t('We', [], ['context' => 'Abbreviated weekday']),
Chris@0:       t('Th', [], ['context' => 'Abbreviated weekday']),
Chris@0:       t('Fr', [], ['context' => 'Abbreviated weekday']),
Chris@0:       t('Sa', [], ['context' => 'Abbreviated weekday']),
Chris@0:     ];
Chris@0:     $none = ['' => ''];
Chris@0:     return !$required ? $none + $weekdays : $weekdays;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs a translated array of 1-letter week day abbreviations.
Chris@0:    *
Chris@0:    * @param bool $required
Chris@0:    *   (optional) If FALSE, the returned array will include a blank value.
Chris@0:    *   Defaults to FALSE.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of week day 1 letter abbreviations
Chris@0:    */
Chris@0:   public static function weekDaysAbbr1($required = FALSE) {
Chris@0:     $weekdays = [
Chris@0:       t('S', [], ['context' => 'Abbreviated 1 letter weekday Sunday']),
Chris@0:       t('M', [], ['context' => 'Abbreviated 1 letter weekday Monday']),
Chris@0:       t('T', [], ['context' => 'Abbreviated 1 letter weekday Tuesday']),
Chris@0:       t('W', [], ['context' => 'Abbreviated 1 letter weekday Wednesday']),
Chris@0:       t('T', [], ['context' => 'Abbreviated 1 letter weekday Thursday']),
Chris@0:       t('F', [], ['context' => 'Abbreviated 1 letter weekday Friday']),
Chris@0:       t('S', [], ['context' => 'Abbreviated 1 letter weekday Saturday']),
Chris@0:     ];
Chris@0:     $none = ['' => ''];
Chris@0:     return !$required ? $none + $weekdays : $weekdays;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Reorders weekdays to match the first day of the week.
Chris@0:    *
Chris@0:    * @param array $weekdays
Chris@0:    *   An array of weekdays.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of weekdays reordered to match the first day of the week. The
Chris@0:    *   keys will remain unchanged. For example, if the first day of the week is
Chris@0:    *   set to be Monday, the array keys will be [1, 2, 3, 4, 5, 6, 0].
Chris@0:    */
Chris@0:   public static function weekDaysOrdered($weekdays) {
Chris@0:     $first_day = \Drupal::config('system.date')->get('first_day');
Chris@0:     if ($first_day > 0) {
Chris@0:       for ($i = 1; $i <= $first_day; $i++) {
Chris@0:         // Reset the array to the first element.
Chris@0:         reset($weekdays);
Chris@0:         // Retrieve the first week day value.
Chris@0:         $last = current($weekdays);
Chris@0:         // Store the corresponding key.
Chris@0:         $key = key($weekdays);
Chris@0:         // Remove this week day from the beginning of the array.
Chris@0:         unset($weekdays[$key]);
Chris@0:         // Add this week day to the end of the array.
Chris@0:         $weekdays[$key] = $last;
Chris@0:       }
Chris@0:     }
Chris@0:     return $weekdays;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs an array of years in a specified range.
Chris@0:    *
Chris@0:    * @param int $min
Chris@0:    *   (optional) The minimum year in the array. Defaults to zero.
Chris@0:    * @param int $max
Chris@0:    *   (optional) The maximum year in the array. Defaults to zero.
Chris@0:    * @param bool $required
Chris@0:    *   (optional) If FALSE, the returned array will include a blank value.
Chris@0:    *   Defaults to FALSE.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of years in the selected range.
Chris@0:    */
Chris@0:   public static function years($min = 0, $max = 0, $required = FALSE) {
Chris@0:     // Ensure $min and $max are valid values.
Chris@0:     if (empty($min)) {
Chris@0:       $min = intval(date('Y', REQUEST_TIME) - 3);
Chris@0:     }
Chris@0:     if (empty($max)) {
Chris@0:       $max = intval(date('Y', REQUEST_TIME) + 3);
Chris@0:     }
Chris@0:     $none = ['' => ''];
Chris@0:     $range = range($min, $max);
Chris@0:     $range = array_combine($range, $range);
Chris@0:     return !$required ? $none + $range : $range;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs an array of days in a month.
Chris@0:    *
Chris@0:    * @param bool $required
Chris@0:    *   (optional) If FALSE, the returned array will include a blank value.
Chris@0:    *   Defaults to FALSE.
Chris@0:    * @param int $month
Chris@0:    *   (optional) The month in which to find the number of days. Defaults to
Chris@0:    *   NULL.
Chris@0:    * @param int $year
Chris@0:    *   (optional) The year in which to find the number of days. Defaults to
Chris@0:    *   NULL.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of days for the selected month.
Chris@0:    */
Chris@0:   public static function days($required = FALSE, $month = NULL, $year = NULL) {
Chris@0:     // If we have a month and year, find the right last day of the month.
Chris@0:     if (!empty($month) && !empty($year)) {
Chris@0:       $date = new DrupalDateTime($year . '-' . $month . '-01 00:00:00', 'UTC');
Chris@0:       $max = $date->format('t');
Chris@0:     }
Chris@0:     // If there is no month and year given, default to 31.
Chris@0:     if (empty($max)) {
Chris@0:       $max = 31;
Chris@0:     }
Chris@0:     $none = ['' => ''];
Chris@0:     $range = range(1, $max);
Chris@0:     $range = array_combine($range, $range);
Chris@0:     return !$required ? $none + $range : $range;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs an array of hours.
Chris@0:    *
Chris@0:    * @param string $format
Chris@0:    *   (optional) A date format string that indicates the format to use for the
Chris@0:    *   hours. Defaults to 'H'.
Chris@0:    * @param bool $required
Chris@0:    *   (optional) If FALSE, the returned array will include a blank value.
Chris@0:    *   Defaults to FALSE.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of hours in the selected format.
Chris@0:    */
Chris@0:   public static function hours($format = 'H', $required = FALSE) {
Chris@0:     $hours = [];
Chris@0:     if ($format == 'h' || $format == 'g') {
Chris@0:       $min = 1;
Chris@0:       $max = 12;
Chris@0:     }
Chris@0:     else {
Chris@0:       $min = 0;
Chris@0:       $max = 23;
Chris@0:     }
Chris@0:     for ($i = $min; $i <= $max; $i++) {
Chris@0:       $formatted = ($format == 'H' || $format == 'h') ? DrupalDateTime::datePad($i) : $i;
Chris@0:       $hours[$i] = $formatted;
Chris@0:     }
Chris@0:     $none = ['' => ''];
Chris@0:     return !$required ? $none + $hours : $hours;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs an array of minutes.
Chris@0:    *
Chris@0:    * @param string $format
Chris@0:    *   (optional) A date format string that indicates the format to use for the
Chris@0:    *    minutes. Defaults to 'i'.
Chris@0:    * @param bool $required
Chris@0:    *   (optional) If FALSE, the returned array will include a blank value.
Chris@0:    *   Defaults to FALSE.
Chris@0:    * @param int $increment
Chris@0:    *   An integer value to increment the values. Defaults to 1.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of minutes in the selected format.
Chris@0:    */
Chris@0:   public static function minutes($format = 'i', $required = FALSE, $increment = 1) {
Chris@0:     $minutes = [];
Chris@0:     // Ensure $increment has a value so we don't loop endlessly.
Chris@0:     if (empty($increment)) {
Chris@0:       $increment = 1;
Chris@0:     }
Chris@0:     for ($i = 0; $i < 60; $i += $increment) {
Chris@0:       $formatted = $format == 'i' ? DrupalDateTime::datePad($i) : $i;
Chris@0:       $minutes[$i] = $formatted;
Chris@0:     }
Chris@0:     $none = ['' => ''];
Chris@0:     return !$required ? $none + $minutes : $minutes;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs an array of seconds.
Chris@0:    *
Chris@0:    * @param string $format
Chris@0:    *   (optional) A date format string that indicates the format to use for the
Chris@0:    *   seconds. Defaults to 's'.
Chris@0:    * @param bool $required
Chris@0:    *   (optional) If FALSE, the returned array will include a blank value.
Chris@0:    *   Defaults to FALSE.
Chris@0:    * @param int $increment
Chris@0:    *   An integer value to increment the values. Defaults to 1.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of seconds in the selected format.
Chris@0:    */
Chris@0:   public static function seconds($format = 's', $required = FALSE, $increment = 1) {
Chris@0:     $seconds = [];
Chris@0:     // Ensure $increment has a value so we don't loop endlessly.
Chris@0:     if (empty($increment)) {
Chris@0:       $increment = 1;
Chris@0:     }
Chris@0:     for ($i = 0; $i < 60; $i += $increment) {
Chris@0:       $formatted = $format == 's' ? DrupalDateTime::datePad($i) : $i;
Chris@0:       $seconds[$i] = $formatted;
Chris@0:     }
Chris@0:     $none = ['' => ''];
Chris@0:     return !$required ? $none + $seconds : $seconds;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs an array of AM and PM options.
Chris@0:    *
Chris@0:    * @param bool $required
Chris@0:    *   (optional) If FALSE, the returned array will include a blank value.
Chris@0:    *   Defaults to FALSE.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of AM and PM options.
Chris@0:    */
Chris@0:   public static function ampm($required = FALSE) {
Chris@0:     $none = ['' => ''];
Chris@0:     $ampm = [
Chris@0:              'am' => t('am', [], ['context' => 'ampm']),
Chris@0:              'pm' => t('pm', [], ['context' => 'ampm']),
Chris@0:             ];
Chris@0:     return !$required ? $none + $ampm : $ampm;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Identifies the number of days in a month for a date.
Chris@0:    *
Chris@0:    * @param mixed $date
Chris@0:    *   (optional) A DrupalDateTime object or a date string.
Chris@0:    *   Defaults to NULL, which means to use the current date.
Chris@0:    *
Chris@0:    * @return int
Chris@0:    *   The number of days in the month.
Chris@0:    */
Chris@0:   public static function daysInMonth($date = NULL) {
Chris@0:     if (!$date instanceof DrupalDateTime) {
Chris@0:       $date = new DrupalDateTime($date);
Chris@0:     }
Chris@0:     if (!$date->hasErrors()) {
Chris@0:       return $date->format('t');
Chris@0:     }
Chris@0:     return NULL;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Identifies the number of days in a year for a date.
Chris@0:    *
Chris@0:    * @param mixed $date
Chris@0:    *   (optional) A DrupalDateTime object or a date string.
Chris@0:    *   Defaults to NULL, which means to use the current date.
Chris@0:    *
Chris@0:    * @return int
Chris@0:    *   The number of days in the year.
Chris@0:    */
Chris@0:   public static function daysInYear($date = NULL) {
Chris@0:     if (!$date instanceof DrupalDateTime) {
Chris@0:       $date = new DrupalDateTime($date);
Chris@0:     }
Chris@0:     if (!$date->hasErrors()) {
Chris@0:       if ($date->format('L')) {
Chris@0:         return 366;
Chris@0:       }
Chris@0:       else {
Chris@0:         return 365;
Chris@0:       }
Chris@0:     }
Chris@0:     return NULL;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns day of week for a given date (0 = Sunday).
Chris@0:    *
Chris@0:    * @param mixed $date
Chris@0:    *   (optional) A DrupalDateTime object or a date string.
Chris@0:    *   Defaults to NULL, which means use the current date.
Chris@0:    *
Chris@0:    * @return int
Chris@0:    *   The number of the day in the week.
Chris@0:    */
Chris@0:   public static function dayOfWeek($date = NULL) {
Chris@0:     if (!$date instanceof DrupalDateTime) {
Chris@0:       $date = new DrupalDateTime($date);
Chris@0:     }
Chris@0:     if (!$date->hasErrors()) {
Chris@0:       return $date->format('w');
Chris@0:     }
Chris@0:     return NULL;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns translated name of the day of week for a given date.
Chris@0:    *
Chris@0:    * @param mixed $date
Chris@0:    *   (optional) A DrupalDateTime object or a date string.
Chris@0:    *   Defaults to NULL, which means use the current date.
Chris@0:    * @param string $abbr
Chris@0:    *   (optional) Whether to return the abbreviated name for that day.
Chris@0:    *   Defaults to TRUE.
Chris@0:    *
Chris@0:    * @return string
Chris@0:    *   The name of the day in the week for that date.
Chris@0:    */
Chris@0:   public static function dayOfWeekName($date = NULL, $abbr = TRUE) {
Chris@0:     if (!$date instanceof DrupalDateTime) {
Chris@0:       $date = new DrupalDateTime($date);
Chris@0:     }
Chris@0:     $dow = self::dayOfWeek($date);
Chris@0:     $days = $abbr ? self::weekDaysAbbr() : self::weekDays();
Chris@0:     return $days[$dow];
Chris@0:   }
Chris@0: 
Chris@0: }