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:

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

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

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

Examples

Example 1: Persian (Jalali) Calendar

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

Example 2: Islamic (Hijri) Calendar

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

Example 3: Gregorian Calendar with Multiple Locales

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

Example 4: ISO 8601 String Input

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

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