Add IntlDatePatternGenerator View as Markdown

Introduction

PHP currently does not provide a way to flexibly create localized date formats, even though the underlying ICU library exposes such functionality already.

For locale-specific date and time formatting, IntlDateFormatter provides 6 options: IntlDateFormatter::LONG, IntlDateFormatter::MEDIUM, and IntlDateFormatter::SHORT, with RELATIVE_ variants.

However, sometimes more flexibility is necessary. For example, if an application requires a format that will always use the long version of a year, but the short version of a month (eg. “MM/dd/YYYY” for “en_US”, or “dd.MM.YYYY” for “de_DE”), one is out of luck. IntlDateFormatter::SHORT will use the short year for “de_DE” (“dd.MM.YY”), and IntlDateFormatter::MEDIUM will use the long version of a month for “en_US” (“MMM dd, YYYY”).

Here, it would be useful to specify exactly which forms should be used (“dd”, “MM”, and “YYYY”), but leave the exact order and formatting of these components to the formatter.

This is exactly what the ICU DateTimePatternGenerator class does. It allows generating a localized formatting pattern from a given so-called skeleton.

Proposal

Add a class IntlDatePatternGenerator that exposes the underlying ICU functionality to PHP, and allows generating formatting patterns that can be used with IntlDateFormatter to format dates/times.

class IntlDatePatternGenerator
{
    public function __construct(?string $locale = null) {}
 
    public static function create(?string $locale = null): ?IntlDatePatternGenerator {}
 
    public function getBestPattern(string $skeleton): string|false {}
}
 
// Procedural style:
function datepatterngenerator_create(?string $locale = null): ?IntlDatePatternGenerator {}
 
function datepatterngenerator_get_best_pattern(IntlDatePatternGenerator $patternGenerator, string $skeleton): string|false {}

With this, the use-case given above can be fulfilled:

$skeleton = "YYYYMMdd";
 
$today = \DateTimeImmutable::createFromFormat('Y-m-d', '2021-04-24');
 
$dtpg = new \IntlDatePatternGenerator("de_DE");
$pattern = $dtpg->getBestPattern($skeleton);
echo "de: ", \IntlDateFormatter::formatObject($today, $pattern, "de_DE"), "\n";
 
$dtpg = new \IntlDatePatternGenerator("en_US");
$pattern = $dtpg->getBestPattern($skeleton), "\n";
echo "en: ", \IntlDateFormatter::formatObject($today, $pattern, "en_US"), "\n";
 
/*
de: 24.04.2021
en: 04/24/2021
*/

Naming

We have two options for naming here:

IntlDateTimePatternGenerator:

• This would be consistent with ICU's DateTimePatternGenerator (similar to how IntlDateFormatter is consistent with ICU's DateFormatter).
• In theory, this would also mean that people familiar with ICU would immediately know what to expect.
• Users searching the web for the ICU name will find this class easier, and vice versa.

IntlDatePatternGenerator

• This is both shorter and would make it more consistent with IntlDateFormatter, giving PHP more internal consistency.
• Since this class will be documented for PHP separately, there is not much gained from consistency with ICU, especially since we do not implement all of ICU's methods.
• Searchability does not appear to be an issue, as searching for 'ICU DatePatternGenerator' will bring up the right results.
• HHVM/Hack also chose this name: https://docs.hhvm.com/hack/reference/class/IntlDatePatternGenerator/

IntlDatePatternGenerator seems to be the preferred option in all counts here.

Backward Incompatible Changes

None, except that the class name IntlDatePatternGenerator will be declared by PHP and conflict with applications declaring the same class name in the global namespace.

Proposed PHP Version(s)

8.1

Future Scope

The ICU DateTimePatternGenerator class provides some additional methods (for example getSkeleton to reduce a given pattern to its skeleton form). These other methodes are of limited use compared to getBestPattern, and have been omitted in this RFC.

Vote

Yes/No, requiring a 2/3 majority. Voting started on 2021-05-14 16:00 UTC and ends 2021-05-28 16:00 UTC.

Vote: Add IntlDatePatternGenerator? — Yes: 10 · No: 0 (closed)

Patches and Tests

The implementation is available at https://github.com/php/php-src/pull/6771

Implementation

After the project is implemented, this section should contain

1. the version(s) it was merged into
2. a link to the git commit(s)
3. a link to the PHP manual entry for the feature
4. a link to the language specification section (if any)

References

Bug report: https://bugs.php.net/bug.php?id=70377