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

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.

Add a new function to the intl extension:

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

• $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: ICU Date Format Patterns

• 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

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:

<?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";
}
?>

<?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: ۵ مهر ۱۴۰۵
?>

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

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

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

None. This is a new function.

PHP 8.7

None.

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

None.

None at this time.

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

• 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

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

Voting opens: TBD Voting closes: TBD (minimum 2