====== PHP RFC: intl_date_format() ======
  * Version: 1.0
  * Date: 2026-09-27
  * Author: Sepehr Mahmoudi <sepehrphpr@gmail.com>
  * Target Version: PHP 8.7
  * Status: Draft
  * First Published at: https://wiki.php.net/rfc/intl_date_format

===== Introduction =====

This RFC proposes adding a new function ''intl_date_format()'' to the ''intl'' extension that provides a simple, unified interface for formatting dates across different calendar systems (Gregorian, Persian, Islamic, etc.) using ICU's calendar capabilities.

Currently, PHP developers must manually instantiate ''IntlDateFormatter'' and configure calendar types through locale strings or setter methods. This RFC introduces a procedural function that simplifies calendar-aware date formatting for common use cases.

===== Proposal =====

Add a new function to the ''intl'' extension:

<code php>
function intl_date_format(
    string|int $date,
    string $calendar = 'gregorian',
    string $locale = 'en_US',
    string $pattern = 'yyyy/MM/dd'
): string|false
</code>

==== Parameters ====

  * **''$date''** (''string|int'', required)
    * Unix timestamp as integer (e.g., ''time()'', ''strtotime()'')
    * ISO 8601 date string (e.g., ''2026-09-27'' or ''2026-09-27T14:30:00Z'')
    * When an integer is provided, it represents seconds since Unix epoch
    * ICU internally converts timestamps to milliseconds for processing

  * **''$calendar''** (''string'', optional, default: ''gregorian'')
    * Calendar system identifier for date formatting
    * Supported values: ''gregorian'', ''persian'', ''islamic'', ''islamic-civil'', ''japanese'', ''buddhist'', ''chinese'', ''indian'', ''coptic'', ''ethiopic'', ''hebrew''
    * The function automatically appends ''@calendar=<value>'' to the locale string
    * Invalid calendar names will trigger an error

  * **''$locale''** (''string'', optional, default: ''en_US'')
    * ICU locale identifier (e.g., ''fa_IR'', ''ar_SA'', ''en_US'', ''de_DE'')
    * Controls language, number formatting, and regional conventions
    * Should **not** include ''@calendar='' suffix (handled automatically by the function)
    * Invalid locale will fall back to ''en_US'' with a warning

  * **''$pattern''** (''string'', optional, default: ''yyyy/MM/dd'')
    * ICU date format pattern defining output structure
    * Common pattern symbols:
      * ''yyyy'': 4-digit year, ''yy'': 2-digit year
      * ''MM'': 2-digit month, ''MMM'': short month name, ''MMMM'': full month name
      * ''dd'': 2-digit day, ''d'': day without leading zero
      * ''EEEE'': full weekday name, ''EEE'': short weekday name
      * ''HH'': 24-hour, ''hh'': 12-hour, ''mm'': minutes, ''ss'': seconds
      * ''a'': AM/PM marker
    * Full pattern syntax: [[https://unicode-org.github.io/icu/userguide/format_parse/datetime/|ICU Date Format Patterns]]

==== Return Value ====

  * **Success**: Returns the formatted date string according to the specified calendar, locale, and pattern
  * **Failure**: Returns ''false'' and emits a warning when:
    * Invalid date format (unparseable string or invalid timestamp)
    * Unsupported or invalid calendar name
    * ICU formatting error

==== Error Handling ====

The function follows PHP's standard error handling conventions for ''intl'' functions:

  * **Invalid ''$date''**: Returns ''false'' and emits ''E_WARNING''
    * Non-numeric string that cannot be parsed as ISO 8601
    * Timestamp out of valid range

  * **Invalid ''$calendar''**: Returns ''false'' and emits ''E_WARNING''
    * Calendar name not recognized by ICU

  * **Invalid ''$locale''**: Emits ''E_WARNING'' and falls back to ''en_US''
    * Malformed locale identifier

  * **Invalid ''$pattern''**: Returns ''false'' and emits ''E_WARNING''
    * Malformed ICU pattern syntax

  * **ICU internal error**: Returns ''false'' and emits ''E_WARNING''
    * Detailed error message available via ''intl_get_error_message()''

Example error handling:

<code php>
<?php
$result = intl_date_format('invalid-date', 'persian', 'fa_IR');
if ($result === false) {
    echo "Error: " . intl_get_error_message() . "\n";
    echo "Error code: " . intl_get_error_code() . "\n";
}
?>
</code>

===== Examples =====

==== Example 1: Persian (Jalali) Calendar ====

<code php>
<?php
// Format current timestamp in Persian calendar
echo intl_date_format(time(), 'persian', 'fa_IR');
// Output: 1405/07/05

echo intl_date_format(time(), 'persian', 'fa_IR', 'd MMMM yyyy');
// Output: ۵ مهر ۱۴۰۵
?>
</code>

==== Example 2: Islamic (Hijri) Calendar ====

<code php>
<?php
// Format specific date in Islamic calendar
$date = '2026-09-27';
echo intl_date_format($date, 'islamic', 'ar_SA', 'd MMMM yyyy');
// Output: ٢٤ ربيع الأول ١٤٤٨

echo intl_date_format($date, 'islamic-civil', 'en_US');
// Output: 1448/03/24
?>
</code>

==== Example 3: Gregorian Calendar with Multiple Locales ====

<code php>
<?php
$timestamp = strtotime('2026-09-27');

// English
echo intl_date_format($timestamp, 'gregorian', 'en_US', 'EEEE, MMMM d, yyyy');
// Output: Sunday, September 27, 2026

// German
echo intl_date_format($timestamp, 'gregorian', 'de_DE', 'EEEE, d. MMMM yyyy');
// Output: Sonntag, 27. September 2026
?>
</code>

==== Example 4: ISO 8601 String Input ====

<code php>
<?php
// Using ISO 8601 date string instead of timestamp
$isoDate = '2026-09-27T14:30:00Z';

echo intl_date_format($isoDate, 'persian', 'fa_IR', 'yyyy/MM/dd HH:mm');
// Output: 1405/07/05 14:30

echo intl_date_format($isoDate, 'gregorian', 'en_US', 'MMM d, yyyy h:mm a');
// Output: Sep 27, 2026 2:30 PM
?>
</code>

===== Backward Incompatible Changes =====

None. This is a new function.

===== Proposed PHP Version(s) =====

PHP 8.7

===== RFC Impact =====

==== To SAPIs ====

None.

==== To Existing Extensions ====

This adds a new function to the existing ''intl'' extension. No changes to existing ''intl'' functions..

===== Unaffcache ====

None.

===== Open Issues =====

None at this time.

===== Unaffected PHP Functionality =====

  * Existing ''IntlDateFormatter'' class remains unchanged
  * All existing date/time functions (''date()'', ''strftime()'', etc.) are unaffected
  * No changes to ''DateTime'' or ''DateTimeImmutable'' classes

===== Future Scope =====

  * Add support for additional calendar systems as ICU expands
  * Consider object-oriented wrapper class for advanced use cases
  * Explore integration with ''DateTimeInterface'' for calendar conversion
  * Potential ''intl_date_parse()'' function for reverse operation

===== Proposed Voting Choices =====

Accept ''intl_date_format()'' as proposed? Yes/No (requires 2/3 majority).

Voting opens: TBD  
Voting closes: TBD (minimum 2