IntlDateFormatter::create

datefmt_create

IntlDateFormatter::__construct

Create a date formatter

Description

Object-oriented style

public static IntlDateFormatternull IntlDateFormatter::create(
    stringnull $locale,
    int $dateType = IntlDateFormatter::FULL,
    int $timeType = IntlDateFormatter::FULL,
    IntlTimeZoneDateTimeZonestringnull $timezone = null,
    IntlCalendarintnull $calendar = null,
    stringnull $pattern = null
)

Object-oriented style (constructor)

public IntlDateFormatter::__construct(
    stringnull $locale,
    int $dateType = IntlDateFormatter::FULL,
    int $timeType = IntlDateFormatter::FULL,
    IntlTimeZoneDateTimeZonestringnull $timezone = null,
    IntlCalendarintnull $calendar = null,
    stringnull $pattern = null
)

Procedural style

IntlDateFormatternull datefmt_create(
    stringnull $locale,
    int $dateType = IntlDateFormatter::FULL,
    int $timeType = IntlDateFormatter::FULL,
    IntlTimeZoneDateTimeZonestringnull $timezone = null,
    IntlCalendarintnull $calendar = null,
    stringnull $pattern = null
)

Create a date formatter.

Parameters

locale

Locale to use when formatting or parsing or null to use the value specified in the ini setting intl.default_locale.

Both en_US and en-US are accepted. The locale may carry ICU keywords, such as fa_IR@calendar=persian, but the calendar keyword only changes the calendar used when calendar is IntlDateFormatter::TRADITIONAL.
dateType

Format of the date determined by one of the IntlDateFormatter constants. The default value is IntlDateFormatter::FULL.

timeType

Format of the time determined by one of the IntlDateFormatter constants. The default value is IntlDateFormatter::FULL.

timezone

Time zone ID. The default (and the one used if null is given) is the one returned by date_default_timezone_get or, if applicable, that of the IntlCalendar object passed for the calendar parameter. This ID must be a valid identifier on ICUʼs database or an ID representing an explicit offset, such as GMT-05:30.

This can also be an IntlTimeZone or a DateTimeZone object.

calendar

Calendar to use for formatting or parsing. The default value is null, which corresponds to IntlDateFormatter::GREGORIAN. This can either be one of the IntlDateFormatter calendar constants or an IntlCalendar. Any IntlCalendar object passed will be clone; it will not be changed by the IntlDateFormatter. This will determine the calendar type used (gregorian, islamic, persian, etc.) and, if null is given for the timezone parameter, also the timezone used.

IntlDateFormatter::GREGORIAN always uses the Gregorian calendar, even if the locale has a calendar keyword. IntlDateFormatter::TRADITIONAL uses the default calendar of the locale: the one given by its calendar keyword if there is one, otherwise the one ICU defines for the region of the locale (for example persian for fa_IR and buddhist for th_TH, but gregorian for en_US). The latter depends on the ICU version. The calendar types available for a locale are listed by IntlCalendar::getKeywordValuesForLocale.
pattern
Optional pattern to use when formatting or parsing. If given, it is used instead of the format determined by dateType and timeType. Possible patterns are documented at » https://unicode-org.github.io/icu/userguide/format_parse/datetime/. A pattern holds no time zone: the time it shows, and the name shown by the z letters, are those of the timezone parameter.

Return Values

The created IntlDateFormatter or null in case of failure.

Errors/Exceptions

A ValueError is thrown if locale is invalid.

Changelog

Version Description
8.4.0 A ValueError is thrown if locale is invalid.
8.1.0

Parameters dateType and timeType are now optional.

Examples

Example #1 datefmt_create example

<?php
$fmt = datefmt_create( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
    'America/Los_Angeles', IntlDateFormatter::GREGORIAN  );
echo "First Formatted output is ".datefmt_format( $fmt , 0);
$fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
    'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
echo "Second Formatted output is ".datefmt_format( $fmt , 0);

$fmt = datefmt_create( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
     'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
echo "First Formatted output with pattern is ".datefmt_format( $fmt , 0);
$fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
     'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
echo "Second Formatted output with pattern is ".datefmt_format( $fmt , 0);
?>

Example #2 OO example

<?php
$fmt = new IntlDateFormatter( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
    'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
echo "First Formatted output is ".$fmt->format(0);
$fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
    'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
echo "Second Formatted output is ".$fmt->format(0);

$fmt = new IntlDateFormatter( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
     'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
echo "First Formatted output with pattern is ".$fmt->format(0);
$fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
      'America/Los_Angeles',IntlDateFormatter::GREGORIAN , "MM/dd/yyyy");
echo "Second Formatted output with pattern is ".$fmt->format(0);
?>

Example #3 Example of invalid locale handling

<?php
try {
    $fmt = new IntlDateFormatter(
        'invalid_locale',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'dunno',
        IntlDateFormatter::GREGORIAN,
    );
} catch (\Error $e) {
    // ...
}
?>

The above example will output:

First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
Second Formatted output is Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00
First Formatted output with pattern is 12/31/1969
Second Formatted output with pattern is 12/31/1969
         

Example #4 Calendar of the locale and time zone with a pattern

<?php
$timestamp = 1700000000;

foreach ([IntlDateFormatter::GREGORIAN, IntlDateFormatter::TRADITIONAL] as $calendar) {
    $formatter = new IntlDateFormatter(
        'en_US@calendar=persian',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'UTC',
        $calendar,
        'yyyy-MM-dd'
    );
    echo $formatter->format($timestamp), "\n";
}

$formatter = new IntlDateFormatter(
    'en_US',
    IntlDateFormatter::FULL,
    IntlDateFormatter::FULL,
    'Asia/Singapore',
    null,
    'yyyy-MM-dd HH:mm zzzz'
);
echo $formatter->format(gmmktime(21, 0, 0, 6, 1, 2024)), "\n";

The above example will output:

2023-11-14
1402-08-23
2024-06-02 05:00 Singapore Standard Time

See Also

  • datefmt_format
  • datefmt_parse
  • datefmt_get_error_code
  • datefmt_get_error_message