====== 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

===== Introduction =====
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.

===== Motivation =====
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.

===== Proposed Function Signature =====
<code php>
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 {}
</code>

===== Parameters =====
  * **''$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.

===== Error Handling =====
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''.

===== Examples =====

==== 1. Quick format with defaults ====
<code php>
echo intl_date_format(new DateTime(), 'fa_IR');
// Output example: ۷ مهر ۱۴۰۵، ۱۸:۳۰:۰۰
</code>

==== 2. Full Persian date (no time) using Traditional calendar ====
<code php>
echo intl_date_format(
    datetime: '2026-09-28',
    locale: 'fa_IR',
    dateType: IntlDateFormatter::FULL,
    timeType: IntlDateFormatter::NONE,
    calendar: IntlDateFormatter::TRADITIONAL
);
// Output example: دوشنبه ۷ مهر ۱۴۰۵
</code>

==== 3. Timestamp with specific timezone ====
<code php>
echo intl_date_format(
    datetime: 1790610000,
    locale: 'en_US',
    timezone: 'America/New_York'
);
// Output example: Sep 28, 2026, 10:00:00 AM
</code>

==== 4. Using a custom pattern ====
<code php>
echo intl_date_format(
    datetime: '2026-09-28 15:30:00',
    locale: 'fa_IR@calendar=persian',
    pattern: 'yyyy/MM/dd'
);
// Output: ۱۴۰۵/۰۷/۰۷
</code>

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

===== Performance =====
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.