Skip to content

Latest commit

 

History

History
275 lines (178 loc) · 6.96 KB

Dates.md

File metadata and controls

275 lines (178 loc) · 6.96 KB

Dates

This part covers calendars and dates and times.

Unicode Reference

The documentation is divided into the following parts, mimicking Unicode's documentation:

  • Part 1: Core (languages, locales, basic structure)
  • Part 2: General (display names & transforms, etc.)
  • Part 3: Numbers (number & currency formatting)
  • Part 4: Dates (date, time, time zone formatting)
  • Part 5: Collation (sorting, searching, grouping)
  • Part 6: Supplemental (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

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

/**
 * @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

/**
 * @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

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

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

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

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

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

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