PHP RFC: Add IntlDateTimePatternGenerator

• Version: 1.0
• Date: 2021-04-24
• Author: Mel Dafert, mel@dafert.at
• Status: Under Discussion
• Implementation: https://github.com/php/php-src/pull/6771
• First Published at: http://wiki.php.net/rfc/intldatetimepatterngenerator

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.

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

class IntlDateTimePatternGenerator
{
    public function __construct(?string $locale = null) {}
 
    public static function create(?string $locale = null): ?IntlDateTimePatternGenerator {}
 
    public function getBestPattern(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 \IntlDateTimePatternGenerator("de_DE");
$pattern = $dtpg->getBestPattern($skeleton);
echo "de: ", \IntlDateFormatter::formatObject($today, $pattern, "de_DE"), "\n";
 
$dtpg = new \IntlDateTimePatternGenerator("en_US");
$pattern = $dtpg->getBestPattern($skeleton), "\n";
echo "en: ", \IntlDateFormatter::formatObject($today, $pattern, "en_US"), "\n";
 
/*
de: 24.04.2021
en: 04/24/2021
*/

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

8.1

The name IntlDateTimePatternGenerator was chosen for consistency with ICU (similarly to IntlDateFormatter, which exposes ICU's DateFormatter class). However, for internal consistency in PHP, it might be preferable to name it IntlDatePatternGenerator instead.

Like IntlDateFormatter, this provides both a __construct method and an equivalent static create method. Other classes inside the intl extension (like IntlCalendar) only provide a static create method, and leave the __construct method private. Is there a preferred way, or are both equivalent?

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.

Yes/No, requiring a 2/3 majority.

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

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)

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