This is an old revision of the document!
PHP RFC: Add IntlDateTimePatternGenerator
- Version: 1.0
- Date: 2021-04-24
- Author: Mel Dafert, mel@dafert.at
- Status: Draft
- Implementation: https://github.com/php/php-src/pull/6771
- First Published at: http://wiki.php.net/rfc/intldatetimepatterngenerator
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 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 */
Backward Incompatible Changes
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.
Proposed PHP Version(s)
8.1
Open Issues
Naming
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.
Constructor
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?
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.
Proposed Voting Choices
Yes/No, requiring a 2/3 majority.
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
- the version(s) it was merged into
- a link to the git commit(s)
- a link to the PHP manual entry for the feature
- a link to the language specification section (if any)
References
Bug report: https://bugs.php.net/bug.php?id=70377