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;
339 * Constructs an array of hours.
341 * @param string $format
342 * (optional) A date format string that indicates the format to use for the
343 * hours. Defaults to 'H'.
344 * @param bool $required
345 * (optional) If FALSE, the returned array will include a blank value.
349 * An array of hours in the selected format.
351 public static function hours($format = 'H', $required = FALSE) {
353 if ($format == 'h' || $format == 'g') {
361 for ($i = $min; $i <= $max; $i++) {
362 $formatted = ($format == 'H' || $format == 'h') ? DrupalDateTime::datePad($i) : $i;
363 $hours[$i] = $formatted;
366 return !$required ? $none + $hours : $hours;
370 * Constructs an array of minutes.
372 * @param string $format
373 * (optional) A date format string that indicates the format to use for the
374 * minutes. Defaults to 'i'.
375 * @param bool $required
376 * (optional) If FALSE, the returned array will include a blank value.
378 * @param int $increment
379 * An integer value to increment the values. Defaults to 1.
382 * An array of minutes in the selected format.
384 public static function minutes($format = 'i', $required = FALSE, $increment = 1) {
386 // Ensure $increment has a value so we don't loop endlessly.
387 if (empty($increment)) {
390 for ($i = 0; $i < 60; $i += $increment) {
391 $formatted = $format == 'i' ? DrupalDateTime::datePad($i) : $i;
392 $minutes[$i] = $formatted;
395 return !$required ? $none + $minutes : $minutes;
399 * Constructs an array of seconds.
401 * @param string $format
402 * (optional) A date format string that indicates the format to use for the
403 * seconds. Defaults to 's'.
404 * @param bool $required
405 * (optional) If FALSE, the returned array will include a blank value.
407 * @param int $increment
408 * An integer value to increment the values. Defaults to 1.
411 * An array of seconds in the selected format.
413 public static function seconds($format = 's', $required = FALSE, $increment = 1) {
415 // Ensure $increment has a value so we don't loop endlessly.
416 if (empty($increment)) {
419 for ($i = 0; $i < 60; $i += $increment) {
420 $formatted = $format == 's' ? DrupalDateTime::datePad($i) : $i;
421 $seconds[$i] = $formatted;
424 return !$required ? $none + $seconds : $seconds;
428 * Constructs an array of AM and PM options.
430 * @param bool $required
431 * (optional) If FALSE, the returned array will include a blank value.
435 * An array of AM and PM options.
437 public static function ampm($required = FALSE) {
440 'am' => t('am', [], ['context' => 'ampm']),
441 'pm' => t('pm', [], ['context' => 'ampm']),
443 return !$required ? $none + $ampm : $ampm;
447 * Identifies the number of days in a month for a date.
450 * (optional) A DrupalDateTime object or a date string.
451 * Defaults to NULL, which means to use the current date.
454 * The number of days in the month.
456 public static function daysInMonth($date = NULL) {
457 if (!$date instanceof DrupalDateTime) {
458 $date = new DrupalDateTime($date);
460 if (!$date->hasErrors()) {
461 return $date->format('t');
467 * Identifies the number of days in a year for a date.
470 * (optional) A DrupalDateTime object or a date string.
471 * Defaults to NULL, which means to use the current date.
474 * The number of days in the year.
476 public static function daysInYear($date = NULL) {
477 if (!$date instanceof DrupalDateTime) {
478 $date = new DrupalDateTime($date);
480 if (!$date->hasErrors()) {
481 if ($date->format('L')) {
492 * Returns day of week for a given date (0 = Sunday).
495 * (optional) A DrupalDateTime object or a date string.
496 * Defaults to NULL, which means use the current date.
499 * The number of the day in the week.
501 public static function dayOfWeek($date = NULL) {
502 if (!$date instanceof DrupalDateTime) {
503 $date = new DrupalDateTime($date);
505 if (!$date->hasErrors()) {
506 return $date->format('w');
512 * Returns translated name of the day of week for a given date.
515 * (optional) A DrupalDateTime object or a date string.
516 * Defaults to NULL, which means use the current date.
517 * @param string $abbr
518 * (optional) Whether to return the abbreviated name for that day.
522 * The name of the day in the week for that date.
524 public static function dayOfWeekName($date = NULL, $abbr = TRUE) {
525 if (!$date instanceof DrupalDateTime) {
526 $date = new DrupalDateTime($date);
528 $dow = self::dayOfWeek($date);
529 $days = $abbr ? self::weekDaysAbbr() : self::weekDays();