# Dates

This part covers [calendars](#calendars) and [dates and times](#dates-and-times).

[Unicode Reference](https://www.unicode.org/reports/tr35/tr35-72/tr35-dates.html#Contents)

-----

The documentation is divided into the following parts, mimicking [Unicode's documentation](https://www.unicode.org/reports/tr35/tr35-72/tr35.html#parts):

- Part 1: [Core](Core.md) (languages, locales, basic structure)
- Part 2: [General](General.md) (display names & transforms, etc.)
- Part 3: [Numbers](Numbers.md) (number & currency formatting)
- Part 4: [Dates](Dates.md) (date, time, time zone formatting)
- Part 5: Collation (sorting, searching, grouping)
- Part 6: [Supplemental](Supplemental.md) (supplemental data)

-----



## Calendars

Calendars are represented by a [Calendar][] instance, they can be accessed as arrays and also
provide magic properties to rapidly access days, eras, months, and quarters:

```php
<?php

use ICanBoogie\CLDR\Dates\CalendarId;

/**
 * @var \ICanBoogie\CLDR\Core\Locale $locale
 */

$calendar = $locale->calendar_for(CalendarId::GREGORIAN);
# or
$calendar = $locale->calendar; // because the gregorian is the default one for this locale

$calender['days']['stand-alone']['abbreviated']
# or
$calendar->standalone_abbreviated_days;

$calender['days']['format']['abbreviated']
# or
$calendar->abbreviated_days;
```

This works with days, eras, months, quarters and the following widths: `abbreviated`, `narrow`,
`short`, and `wide`. Here are some examples:

```php
<?php

/**
 * @var \ICanBoogie\CLDR\Dates\Calendar $calendar
 */

$calendar->standalone_abbreviated_eras;
$calendar->standalone_narrow_months;
$calendar->standalone_short_quarters;
$calendar->standalone_wide_days;
$calendar->abbreviated_days;
$calendar->narrow_months;
$calendar->short_days;
$calendar->wide_quarters;
```



### Dates and times formatters

From a calendar you can obtain formatters for dates and times.

The following example demonstrates how the dates and times formatters can be accessed and
used.

```php
<?php

/**
 * @var ICanBoogie\CLDR\Repository $repository
 */

$datetime = '2018-11-24 20:12:22 UTC';
$calendar = $repository->locale_for('fr')->calendar;

echo $calendar['days']['format']['wide']['sun'];    // dimanche
echo $calendar->wide_days['sun'];                   // dimanche

echo $calendar->format_datetime($datetime, 'full'); // samedi 24 novembre 2018 20:12:22 UTC
echo $calendar->format_date($datetime, 'long');     // 24 novembre 2018
echo $calendar->format_time($datetime, 'long');     // 20:12:22 UTC
# or
echo $calendar->datetime_formatter->format($datetime, 'full'); // samedi 24 novembre 2018 20:12:22 UTC
echo $calendar->date_formatter->format($datetime, 'long');     // 24 novembre 2018
echo $calendar->time_formatter->format($datetime, 'long');     // 20:12:22 UTC
```



## Dates and Times

Calendars provide a formatter for dates and times. A width, a skeleton or a pattern can be
used for the formatting. The datetime can be specified as an Unix timestamp, a string or a
`DateTime` instance.

```php
<?php

use ICanBoogie\CLDR\Dates\DateTimeFormatId;

/**
 * @var \ICanBoogie\CLDR\Dates\Calendar $calendar
 */

$datetime = '2013-11-02 22:23:45 UTC';
$format = $calendar->datetime_formatter->format(...);

echo $format($datetime, "MMM d, y");                    // November 2, 2013
echo $format($datetime, "MMM d, y 'at' hh:mm:ss a");    // November 2, 2013 at 10:23:45 PM
echo $format($datetime, $formatter::WIDHT_FULL);        // Saturday, November 2, 2013 at 10:23:45 PM UTC
echo $format($datetime, $formatter::WIDHT_LONG);        // November 2, 2013 at 10:23:45 PM UTC
echo $format($datetime, $formatter::WIDHT_MEDIUM);      // Nov 2, 2013, 10:23:45 PM
echo $format($datetime, $formatter::WIDHT_SHORT);       // 11/2/13, 10:23 PM
echo $format($datetime, DateTimeFormatId::from('Ehm')); // Sat 10:23 PM
```





### Date formatter

Calendars provide a formatter for dates. A width or a pattern is used for the formatting.

```php
<?php

use ICanBoogie\CLDR\Dates\DateTimeFormatId;use ICanBoogie\CLDR\Dates\DateTimeFormatLength;

/**
 * @var \ICanBoogie\CLDR\Dates\Calendar $calendar
 */

$datetime = '2013-11-04 20:21:22 UTC';

$calendar->format_datetime($datetime, DateTimeFormatLength::FULL);
// Monday, November 4, 2013 at 8:21:22 PM UTC

$calendar->format_datetime($datetime, DateTimeFormatLength::LONG);
// November 4, 2013 at 8:21:22 PM UTC

$calendar->format_datetime($datetime, DateTimeFormatLength::MEDIUM);
// Nov 4, 2013, 8:21:22 PM

$calendar->format_datetime($datetime, DateTimeFormatLength::SHORT);
// 11/4/13, 8:21 PM

$calendar->format_datetime($datetime, DateTimeFormatId::from('yMMMEd'));
// Mon, Nov 4, 2013
```

Alternatively, use can use a [DateTimeFormatter] instance:

```php
<?php

use ICanBoogie\CLDR\Dates\DateTimeFormatLength;

/**
 * @var \ICanBoogie\CLDR\Dates\Calendar $calendar
 */

$datetime = '2013-11-05 21:22:23';
$format = $calendar->datetime_formatter->format(...);

$format($datetime, DateTimeFormatLength::FULL);
// Tuesday, November 5, 2013

$format($datetime, DateTimeFormatLength::LONG);
// November 5, 2013

$format($datetime, DateTimeFormatLength::MEDIUM);
// Nov 5, 2013

$format($datetime, DateTimeFormatLength::SHORT);
// 11/5/13
```





### Time formatter

Calendars provide a formatter for times. A width or a pattern is used for the formatting.

```php
<?php

use ICanBoogie\CLDR\Dates\DateTimeFormatLength;

/**
 * @var \ICanBoogie\CLDR\Dates\Calendar $calendar
 */

$datetime = '2013-11-05 21:22:23 UTC';

echo $calendar->format_time($datetime, DateTimeFormatLength::FULL);
// 9:22:23 PM UTC

echo $calendar->format_time($datetime, DateTimeFormatLength::LONG);
// 9:22:23 PM UTC

echo $calendar->format_time($datetime, DateTimeFormatLength::MEDIUM);
// 9:22:23 PM

echo $calendar->format_time($datetime, DateTimeFormatLength::SHORT);
// 9:22 PM
```

Alternatively, you can use a [TimeFormatter][] instance:

```php
<?php

use ICanBoogie\CLDR\Dates\DateTimeFormatLength;

/**
 * @var \ICanBoogie\CLDR\Dates\Calendar $calendar
 */

$datetime = '2013-11-05 21:22:23 UTC';
$format = $calendar->time_formatter->format(...);

echo $format($datetime, DateTimeFormatLength::FULL);
// 9:22:23 PM UTC
```



### Localized DateTime

`DateTime` can be localized by wrapping them inside a [LocalizedDateTime][] instance, or by using
the `localize` method of the desired locale:

```php
<?php

use ICanBoogie\CLDR\Dates\LocalizedDateTime;

/**
 * @var ICanBoogie\CLDR\Repository $repository
 */

$locale = $repository->locale_for('fr');

$ldt = new LocalizedDateTime(new \DateTime('2013-11-04 20:21:22 UTC'), $locale);

echo $ldt->as_full;          // lundi 4 novembre 2013 à 20:21:22 UTC
# or
echo $ldt->format_as_full(); // lundi 4 novembre 2013 à 20:21:22 UTC

echo $ldt->as_long;          // 4 novembre 2013 à 20:21:22 UTC
echo $ldt->as_medium;        // 4 nov. 2013 20:21:22
echo $ldt->as_short;         // 04/11/2013 20:21
```



[Calendar]: ../src/Dates/Calendar.php
[DateTimeFormatter]: ../src/Dates/DateTimeFormatter.php
[LocalizedDateTime]: ../src/Dates/LocalizedDateTime.php
[TimeFormatter]: ../src/Dates/TimeFormatter.php