3 namespace Drupal\Core\Datetime;
6 * Defines Gregorian Calendar date values.
8 * Lots of helpful functions for use in massaging dates, specific to the
9 * Gregorian calendar system. The values include both translated and
10 * untranslated values.
12 * Untranslated values are useful as array keys and as css identifiers, and
13 * should be listed in English.
15 * Translated values are useful for display to the user. All values that need
16 * translation should be hard-coded and wrapped in t() so the translation system
17 * will be able to process them.
22 * Constructs an untranslated array of month names.
25 * An array of month names.
27 public static function monthNamesUntranslated() {
28 // Force the key to use the correct month value, rather than
29 // starting with zero.
47 * Constructs an untranslated array of abbreviated month names.
50 * An array of month names.
52 public static function monthNamesAbbrUntranslated() {
53 // Force the key to use the correct month value, rather than
54 // starting with zero.
72 * Returns a translated array of month names.
74 * @param bool $required
75 * (optional) If FALSE, the returned array will include a blank value.
79 * An array of month names.
81 public static function monthNames($required = FALSE) {
82 // Force the key to use the correct month value, rather than
83 // starting with zero.
85 1 => t('January', [], ['context' => 'Long month name']),
86 2 => t('February', [], ['context' => 'Long month name']),
87 3 => t('March', [], ['context' => 'Long month name']),
88 4 => t('April', [], ['context' => 'Long month name']),
89 5 => t('May', [], ['context' => 'Long month name']),
90 6 => t('June', [], ['context' => 'Long month name']),
91 7 => t('July', [], ['context' => 'Long month name']),
92 8 => t('August', [], ['context' => 'Long month name']),
93 9 => t('September', [], ['context' => 'Long month name']),
94 10 => t('October', [], ['context' => 'Long month name']),
95 11 => t('November', [], ['context' => 'Long month name']),
96 12 => t('December', [], ['context' => 'Long month name']),
99 return !$required ? $none + $monthnames : $monthnames;
103 * Constructs a translated array of month name abbreviations
105 * @param bool $required
106 * (optional) If FALSE, the returned array will include a blank value.
110 * An array of month abbreviations.
112 public static function monthNamesAbbr($required = FALSE) {
113 // Force the key to use the correct month value, rather than
114 // starting with zero.
116 1 => t('Jan', [], ['context' => 'Abbreviated month name']),
117 2 => t('Feb', [], ['context' => 'Abbreviated month name']),
118 3 => t('Mar', [], ['context' => 'Abbreviated month name']),
119 4 => t('Apr', [], ['context' => 'Abbreviated month name']),
120 5 => t('May', [], ['context' => 'Abbreviated month name']),
121 6 => t('Jun', [], ['context' => 'Abbreviated month name']),
122 7 => t('Jul', [], ['context' => 'Abbreviated month name']),
123 8 => t('Aug', [], ['context' => 'Abbreviated month name']),
124 9 => t('Sep', [], ['context' => 'Abbreviated month name']),
125 10 => t('Oct', [], ['context' => 'Abbreviated month name']),
126 11 => t('Nov', [], ['context' => 'Abbreviated month name']),
127 12 => t('Dec', [], ['context' => 'Abbreviated month name']),
130 return !$required ? $none + $monthnames : $monthnames;
134 * Constructs an untranslated array of week days.
137 * An array of week day names
139 public static function weekDaysUntranslated() {
152 * Returns a translated array of week names.
154 * @param bool $required
155 * (optional) If FALSE, the returned array will include a blank value.
159 * An array of week day names
161 public static function weekDays($required = FALSE) {
172 return !$required ? $none + $weekdays : $weekdays;
176 * Constructs a translated array of week day abbreviations.
178 * @param bool $required
179 * (optional) If FALSE, the returned array will include a blank value.
183 * An array of week day abbreviations
185 public static function weekDaysAbbr($required = FALSE) {
187 t('Sun', [], ['context' => 'Abbreviated weekday']),
188 t('Mon', [], ['context' => 'Abbreviated weekday']),
189 t('Tue', [], ['context' => 'Abbreviated weekday']),
190 t('Wed', [], ['context' => 'Abbreviated weekday']),
191 t('Thu', [], ['context' => 'Abbreviated weekday']),
192 t('Fri', [], ['context' => 'Abbreviated weekday']),
193 t('Sat', [], ['context' => 'Abbreviated weekday']),
196 return !$required ? $none + $weekdays : $weekdays;
200 * Constructs a translated array of 2-letter week day abbreviations.
202 * @param bool $required
203 * (optional) If FALSE, the returned array will include a blank value.
207 * An array of week day 2 letter abbreviations
209 public static function weekDaysAbbr2($required = FALSE) {
211 t('Su', [], ['context' => 'Abbreviated weekday']),
212 t('Mo', [], ['context' => 'Abbreviated weekday']),
213 t('Tu', [], ['context' => 'Abbreviated weekday']),
214 t('We', [], ['context' => 'Abbreviated weekday']),
215 t('Th', [], ['context' => 'Abbreviated weekday']),
216 t('Fr', [], ['context' => 'Abbreviated weekday']),
217 t('Sa', [], ['context' => 'Abbreviated weekday']),
220 return !$required ? $none + $weekdays : $weekdays;
224 * Constructs a translated array of 1-letter week day abbreviations.
226 * @param bool $required
227 * (optional) If FALSE, the returned array will include a blank value.
231 * An array of week day 1 letter abbreviations
233 public static function weekDaysAbbr1($required = FALSE) {
235 t('S', [], ['context' => 'Abbreviated 1 letter weekday Sunday']),
236 t('M', [], ['context' => 'Abbreviated 1 letter weekday Monday']),
237 t('T', [], ['context' => 'Abbreviated 1 letter weekday Tuesday']),
238 t('W', [], ['context' => 'Abbreviated 1 letter weekday Wednesday']),
239 t('T', [], ['context' => 'Abbreviated 1 letter weekday Thursday']),
240 t('F', [], ['context' => 'Abbreviated 1 letter weekday Friday']),
241 t('S', [], ['context' => 'Abbreviated 1 letter weekday Saturday']),
244 return !$required ? $none + $weekdays : $weekdays;
248 * Reorders weekdays to match the first day of the week.
250 * @param array $weekdays
251 * An array of weekdays.
254 * An array of weekdays reordered to match the first day of the week. The
255 * keys will remain unchanged. For example, if the first day of the week is
256 * set to be Monday, the array keys will be [1, 2, 3, 4, 5, 6, 0].
258 public static function weekDaysOrdered($weekdays) {
259 $first_day = \Drupal::config('system.date')->get('first_day');
260 if ($first_day > 0) {
261 for ($i = 1; $i <= $first_day; $i++) {
262 // Reset the array to the first element.
264 // Retrieve the first week day value.
265 $last = current($weekdays);
266 // Store the corresponding key.
267 $key = key($weekdays);
268 // Remove this week day from the beginning of the array.
269 unset($weekdays[$key]);
270 // Add this week day to the end of the array.
271 $weekdays[$key] = $last;
278 * Constructs an array of years in a specified range.
281 * (optional) The minimum year in the array. Defaults to zero.
283 * (optional) The maximum year in the array. Defaults to zero.
284 * @param bool $required
285 * (optional) If FALSE, the returned array will include a blank value.
289 * An array of years in the selected range.
291 public static function years($min = 0, $max = 0, $required = FALSE) {
292 // Ensure $min and $max are valid values.
294 $min = intval(date('Y', REQUEST_TIME) - 3);
297 $max = intval(date('Y', REQUEST_TIME) + 3);
300 $range = range($min, $max);
301 $range = array_combine($range, $range);
302 return !$required ? $none + $range : $range;
306 * Constructs an array of days in a month.
308 * @param bool $required
309 * (optional) If FALSE, the returned array will include a blank value.
312 * (optional) The month in which to find the number of days. Defaults to
315 * (optional) The year in which to find the number of days. Defaults to
319 * An array of days for the selected month.
321 public static function days($required = FALSE, $month = NULL, $year = NULL) {
322 // If we have a month and year, find the right last day of the month.
323 if (!empty($month) && !empty($year)) {
324 $date = new DrupalDateTime($year . '-' . $month . '-01 00:00:00', 'UTC');
325 $max = $date->format('t');
327 // If there is no month and year given, default to 31.
332 $range = range(1, $max);
333 $range = array_combine($range, $range);
334 return !$required ? $none + $range : $range;
338 * Constructs an array of hours.
340 * @param string $format
341 * (optional) A date format string that indicates the format to use for the
342 * hours. Defaults to 'H'.
343 * @param bool $required
344 * (optional) If FALSE, the returned array will include a blank value.
348 * An array of hours in the selected format.
350 public static function hours($format = 'H', $required = FALSE) {
352 if ($format == 'h' || $format == 'g') {
360 for ($i = $min; $i <= $max; $i++) {
361 $formatted = ($format == 'H' || $format == 'h') ? DrupalDateTime::datePad($i) : $i;
362 $hours[$i] = $formatted;
365 return !$required ? $none + $hours : $hours;
369 * Constructs an array of minutes.
371 * @param string $format
372 * (optional) A date format string that indicates the format to use for the
373 * minutes. Defaults to 'i'.
374 * @param bool $required
375 * (optional) If FALSE, the returned array will include a blank value.
377 * @param int $increment
378 * An integer value to increment the values. Defaults to 1.
381 * An array of minutes in the selected format.
383 public static function minutes($format = 'i', $required = FALSE, $increment = 1) {
385 // Ensure $increment has a value so we don't loop endlessly.
386 if (empty($increment)) {
389 for ($i = 0; $i < 60; $i += $increment) {
390 $formatted = $format == 'i' ? DrupalDateTime::datePad($i) : $i;
391 $minutes[$i] = $formatted;
394 return !$required ? $none + $minutes : $minutes;
398 * Constructs an array of seconds.
400 * @param string $format
401 * (optional) A date format string that indicates the format to use for the
402 * seconds. Defaults to 's'.
403 * @param bool $required
404 * (optional) If FALSE, the returned array will include a blank value.
406 * @param int $increment
407 * An integer value to increment the values. Defaults to 1.
410 * An array of seconds in the selected format.
412 public static function seconds($format = 's', $required = FALSE, $increment = 1) {
414 // Ensure $increment has a value so we don't loop endlessly.
415 if (empty($increment)) {
418 for ($i = 0; $i < 60; $i += $increment) {
419 $formatted = $format == 's' ? DrupalDateTime::datePad($i) : $i;
420 $seconds[$i] = $formatted;
423 return !$required ? $none + $seconds : $seconds;
427 * Constructs an array of AM and PM options.
429 * @param bool $required
430 * (optional) If FALSE, the returned array will include a blank value.
434 * An array of AM and PM options.
436 public static function ampm($required = FALSE) {
439 'am' => t('am', [], ['context' => 'ampm']),
440 'pm' => t('pm', [], ['context' => 'ampm']),
442 return !$required ? $none + $ampm : $ampm;
446 * Identifies the number of days in a month for a date.
449 * (optional) A DrupalDateTime object or a date string.
450 * Defaults to NULL, which means to use the current date.
453 * The number of days in the month.
455 public static function daysInMonth($date = NULL) {
456 if (!$date instanceof DrupalDateTime) {
457 $date = new DrupalDateTime($date);
459 if (!$date->hasErrors()) {
460 return $date->format('t');
466 * Identifies the number of days in a year for a date.
469 * (optional) A DrupalDateTime object or a date string.
470 * Defaults to NULL, which means to use the current date.
473 * The number of days in the year.
475 public static function daysInYear($date = NULL) {
476 if (!$date instanceof DrupalDateTime) {
477 $date = new DrupalDateTime($date);
479 if (!$date->hasErrors()) {
480 if ($date->format('L')) {
491 * Returns day of week for a given date (0 = Sunday).
494 * (optional) A DrupalDateTime object or a date string.
495 * Defaults to NULL, which means use the current date.
498 * The number of the day in the week.
500 public static function dayOfWeek($date = NULL) {
501 if (!$date instanceof DrupalDateTime) {
502 $date = new DrupalDateTime($date);
504 if (!$date->hasErrors()) {
505 return $date->format('w');
511 * Returns translated name of the day of week for a given date.
514 * (optional) A DrupalDateTime object or a date string.
515 * Defaults to NULL, which means use the current date.
516 * @param string $abbr
517 * (optional) Whether to return the abbreviated name for that day.
521 * The name of the day in the week for that date.
523 public static function dayOfWeekName($date = NULL, $abbr = TRUE) {
524 if (!$date instanceof DrupalDateTime) {
525 $date = new DrupalDateTime($date);
527 $dow = self::dayOfWeek($date);
528 $days = $abbr ? self::weekDaysAbbr() : self::weekDays();