در تاریخ دوشنبه ۲۸ سپتامبر ۲۰۲۶، ۱۴:۵۱ Weilin Du <[email protected]> نوشت:
> Hi Sepehr
>
> Can you please explain the advantage you see in using
> your proposed API instead of:
>
> ```
> $formatter = new IntlDateFormatter(
> 'fa_IR@calendar=persian',
> IntlDateFormatter::NONE,
> IntlDateFormatter::NONE,
> 'UTC',
> IntlDateFormatter::TRADITIONAL,
> 'yyyy/MM/dd',
> );
> echo $formatter->format(strtotime('2026-09-27 UTC')); // ۱۴۰۵/۰۷/۰۵
> ```
>
> To justify the addition into the extension?
>
> BR,
> Weilin Du
>
---------
Hi Weilin,
Thank you for bringing this up. That is a very fair and essential question.
The primary motivation behind `intl_date_format()` is developer ergonomics,
reducing cognitive boilerplate, and internal optimization:
1. Boilerplate & Ergonomics:
Using `IntlDateFormatter` directly requires configuring up to 6 parameters
(datetype, timetype, calendar constants, pattern, timezone, and locale
syntax). For standard web use cases—such as quickly outputting a
localized/calendar-aware date (e.g., Jalali or Hijri in an API response or
UI template)—developers frequently find the existing API overly verbose and
unintuitive. A simple, procedural wrapper mirrors the simplicity developers
are used to with `date()`, but with ICU's full calendar capabilities.
2. C-level Caching Potential:
In userland, repeatedly instantiating `IntlDateFormatter` carries
noticeable instantiation overhead unless developers implement their own
pooling/singleton mechanisms. A native C implementation can optimize
pattern/calendar cache instances internally, offering better out-of-the-box
performance for batch-rendering dates.
3. Addressing Gaps in the Draft:
Based on your feedback and further reflection, I recognize that the current
draft should be refined before proceeding:
- Support for `DateTimeInterface` (allowing DateTime/DateTimeImmutable as
the `$date` argument).
- An explicit `$timezone` parameter (defaulting to the date object's
timezone or `date_default_timezone_get()`).
- Modern PHP 8 error semantics (throwing `ValueError` / `IntlException`
instead of emitting `E_WARNING` and returning `false`).
- Better locale/calendar integration (e.g., accepting BCP-47 / ICU locale
keywords seamlessly).
Would such adjustments make the API justifiable from a maintainer's
perspective, or would you prefer exploring a static convenience method on
`IntlDateFormatter` (e.g., `IntlDateFormatter::formatQuick(...)`) instead
of a procedural function?
I'd really appreciate your thoughts on this direction.
Best regards,
Sepehr
>
