PHP RFC: intl_date_format

• Version: 1.0
• Date: 2026-09-28
• Author: Sepehr Mahmoudi (sepehrphpr@gmail.com)
• Target Version: PHP 8.7
• Status: Draft

This proposal introduces a new procedural function intl_date_format() to the ext/intl extension. The goal is to provide a simplified, developer-friendly interface for formatting date and time using IntlDateFormatter's capabilities, without the overhead of instantiating and configuring objects for simple use cases.

Currently, using IntlDateFormatter for standard formatting requires significant boilerplate code: instantiating an object, setting the timezone and calendar, and finally calling the format method. Adding a procedural function, similar to the core date() function, will improve ergonomics and development speed for internationalized applications.

function intl_date_format(
    DateTimeInterface|int|string|float $datetime,
    ?string $locale = null,
    int $dateType = IntlDateFormatter::MEDIUM,
    int $timeType = IntlDateFormatter::MEDIUM,
    IntlTimeZone|DateTimeZone|string|null $timezone = null,
    IntlCalendar|int|null $calendar = null,
    string $pattern = ""
): string {}

• $datetime: The date/time to format. Can be a DateTimeInterface object, a Unix timestamp (int/float), or a valid date string.
• $locale: The locale to use (e.g., fa_IR, en_US). If null, the default system locale is used.
• $dateType: The date formatter constant (e.g., IntlDateFormatter::MEDIUM).
• $timeType: The time formatter constant (e.g., IntlDateFormatter::MEDIUM).
• $timezone: The timezone. Can be a DateTimeZone object, IntlTimeZone object, or a string identifier.
• $calendar: The calendar type (e.g., IntlDateFormatter::TRADITIONAL).
• $pattern: An optional ICU pattern string. If provided, this overrides the $dateType and $timeType arguments.

This function adheres to modern PHP 8.7 error handling standards:

• TypeError: Thrown if invalid data types are passed for any parameter.
• ValueError: Thrown if invalid numerical values are passed for constants.
• IntlException: Thrown if the underlying ICU engine encounters an error during formatting.
• The function will always return a string on success and will never return false.

echo intl_date_format(new DateTime(), 'fa_IR');
// Output example: ۷ مهر ۱۴۰۵، ۱۸:۳۰:۰۰

echo intl_date_format(
    datetime: '2026-09-28',
    locale: 'fa_IR',
    dateType: IntlDateFormatter::FULL,
    timeType: IntlDateFormatter::NONE,
    calendar: IntlDateFormatter::TRADITIONAL
);
// Output example: دوشنبه ۷ مهر ۱۴۰۵

echo intl_date_format(
    datetime: 1790610000,
    locale: 'en_US',
    timezone: 'America/New_York'
);
// Output example: Sep 28, 2026, 10:00:00 AM

echo intl_date_format(
    datetime: '2026-09-28 15:30:00',
    locale: 'fa_IR@calendar=persian',
    pattern: 'yyyy/MM/dd'
);
// Output: ۱۴۰۵/۰۷/۰۷

This is a new function and does not introduce any breaking changes.

To avoid overhead caused by frequently instantiating formatters in tight loops, the implementation utilizes an internal C-level LRU Cache to store and reuse formatter instances.