PHP 8.4.2 Released!

    IntlDateFormatter::create

    datefmt_create

    IntlDateFormatter::__construct

    (PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

    IntlDateFormatter::create -- datefmt_create -- IntlDateFormatter::__construct — Create a date formatter

    Description

    Object-oriented style

    public static IntlDateFormatter::create(
        ?string $locale,
        int $dateType = IntlDateFormatter::FULL,
        int $timeType = IntlDateFormatter::FULL,
        IntlTimeZone|DateTimeZone|string|null $timezone = null,
        IntlCalendar|int|null $calendar = null,
        ?string $pattern = null
    ): ?IntlDateFormatter

    Object-oriented style (constructor)

    public IntlDateFormatter::__construct(
        ?string $locale,
        int $dateType = IntlDateFormatter::FULL,
        int $timeType = IntlDateFormatter::FULL,
        IntlTimeZone|DateTimeZone|string|null $timezone = null,
        IntlCalendar|int|null $calendar = null,
        ?string $pattern = null
    )

    Procedural style

    datefmt_create(
        ?string $locale,
        int $dateType = IntlDateFormatter::FULL,
        int $timeType = IntlDateFormatter::FULL,
        IntlTimeZone|DateTimeZone|string|null $timezone = null,
        IntlCalendar|int|null $calendar = null,
        ?string $pattern = null
    ): ?IntlDateFormatter

    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.

    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.

    pattern

    Optional pattern to use when formatting or parsing. Possible patterns are documented at » https://unicode-org.github.io/icu/userguide/format_parse/datetime/.

    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

    See Also

    Found A Problem?

    Learn How To Improve This Page • Submit a Pull Request • Report a Bug
    ＋add a note

    User Contributed Notes 5 notes

    up
    4
    daniel dot rhodes at warpasylum dot co dot uk
    13 years ago
    It should be noted that the locale string passed into IntlDateFormatter's constructor supports UCA keywords. So you can, for example, do things like this to output the year as a Japanese era year:

    <?php
    $now     = new DateTime(); //DateTime is a core PHP class as of version 5.2.0

    $formatter = new IntlDateFormatter('ja_JP', IntlDateFormatter::FULL,
    IntlDateFormatter::FULL, 'Asia/Tokyo', IntlDateFormatter::GREGORIAN);

    echo     'It is now: "' . $formatter->format($now) . '" in Tokyo' . "\n";
    //above gives [It is now: "2011年8月19日金曜日 23時32分27秒JST" in Tokyo]

    $formatter = new IntlDateFormatter('ja_JP@calendar=japanese', IntlDateFormatter::FULL,
    IntlDateFormatter::FULL, 'Asia/Tokyo', IntlDateFormatter::TRADITIONAL);

    echo     'It is now: "' . $formatter->format($now) . '" in Tokyo' . "\n";
    //above gives [It is now: "平成23年8月19日金曜日 23時32分27秒JST" in Tokyo]
    ?>
    up
    2
    mikko dot rantalainen at peda dot net
    12 years ago
    Documentation says "timezone: Time zone ID, default is system default."

    The "system default" really means only the "TZ" environment variable on Unix/Linux systems. It does not mean PHP ini setting or value set via date_default_timezone_set() or the OS default time zone in file "/etc/timezone".
    up
    1
    info at mobger dot de
    1 year ago
    The $locale can although contain the information about the calendar

    <?php
    //...
    $traditionalFormatter = new IntlDateFormatter(
    $locale.'@calendar='.$calendar,
    IntlDateFormatter::SHORT,
    IntlDateFormatter::SHORT,
    'Europe/Berlin',
    IntlDateFormatter::TRADITIONAL,
    'yyyy/MM/dd HH:mm:ss' // ICU-datetime-format
    );
    //..
    ?>

    To get the allowed values for $calendar, use the following code:

    <?php
    $bundle    =new ResourceBundle('','ICUDATA');
    $cnames=[];
    $calendars=$bundle->get('calendar');
    foreach(    $calendars as $n=>$v){
    $cnames[]=$n;
    }
    echo (    print_r($cnames,true));

    ?>

    The result is:
    Array
    (
    [0] => buddhist
    [1] => chinese
    [2] => coptic
    [3] => dangi
    [4] => default
    [5] => ethiopic
    [6] => ethiopic-amete-alem
    [7] => gregorian
    [8] => hebrew
    [9] => indian
    [10] => islamic
    [11] => islamic-civil
    [12] => japanese
    [13] => persian
    [14] => roc
    )
    up
    1
    Anonymous
    6 years ago
    The documentation says that $datetype and $timetype can also be NULL, in which case ICUʼs default date type or time type will be used.

    But when declare (strict_types=1); is also set, Intl fails to create the IntlDateFormatter class, and it returns an error "datefmt_create: unable to parse input parameters".
    up
    0
    Patanjali
    3 years ago
    Just to be clear, to use any non-gregorian calendar:

    a. The locale must be in the form of locale@calendar=calendar-name

    b. The calendar must use the intlDateFormatter::TRADITIONAL constant, or an intlCalendar object created with a locale as specified in a.

    The calendar name can be 'gregorian', even if the intlDateFormatter::TRADITIONAL constant is used, which makes for a more generic code approach.
    ＋add a note
    To Top