rfc:intldatetimepatterngenerator

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
rfc:intldatetimepatterngenerator [2021/04/24 14:58]
deltragon created
rfc:intldatetimepatterngenerator [2021/06/10 11:48] (current)
nikic
Line 1: Line 1:
-====== PHP RFC: Add IntlDateTimePatternGenerator ======+====== PHP RFC: Add IntlDatePatternGenerator ======
   * Version: 1.0   * Version: 1.0
   * Date: 2021-04-24   * Date: 2021-04-24
   * Author: Mel Dafert, mel@dafert.at   * Author: Mel Dafert, mel@dafert.at
-  * Status: Draft+  * Status: Implemented
   * Implementation: https://github.com/php/php-src/pull/6771   * Implementation: https://github.com/php/php-src/pull/6771
   * First Published at: http://wiki.php.net/rfc/intldatetimepatterngenerator   * First Published at: http://wiki.php.net/rfc/intldatetimepatterngenerator
 +  * Target Version: PHP 8.1
  
 ===== Introduction ===== ===== Introduction =====
Line 21: Line 22:
  
 ===== Proposal ===== ===== 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.+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.
  
 <code php> <code php>
-class IntlDateTimePatternGenerator+class IntlDatePatternGenerator
 { {
     public function __construct(?string $locale = null) {}     public function __construct(?string $locale = null) {}
  
-    public static function create(?string $locale = null): ?IntlDateTimePatternGenerator {}+    public static function create(?string $locale = null): ?IntlDatePatternGenerator {}
  
     public function getBestPattern(string $skeleton): string|false {}     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 {}
 </code> </code>
  
Line 41: Line 47:
 $today = \DateTimeImmutable::createFromFormat('Y-m-d', '2021-04-24'); $today = \DateTimeImmutable::createFromFormat('Y-m-d', '2021-04-24');
  
-$dtpg = new \IntlDateTimePatternGenerator("de_DE");+$dtpg = new \IntlDatePatternGenerator("de_DE");
 $pattern = $dtpg->getBestPattern($skeleton); $pattern = $dtpg->getBestPattern($skeleton);
 echo "de: ", \IntlDateFormatter::formatObject($today, $pattern, "de_DE"), "\n"; echo "de: ", \IntlDateFormatter::formatObject($today, $pattern, "de_DE"), "\n";
  
-$dtpg = new \IntlDateTimePatternGenerator("en_US");+$dtpg = new \IntlDatePatternGenerator("en_US");
 $pattern = $dtpg->getBestPattern($skeleton), "\n"; $pattern = $dtpg->getBestPattern($skeleton), "\n";
 echo "en: ", \IntlDateFormatter::formatObject($today, $pattern, "en_US"), "\n"; echo "en: ", \IntlDateFormatter::formatObject($today, $pattern, "en_US"), "\n";
Line 54: Line 60:
 */ */
 </code> </code>
 +
 +==== 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 ===== ===== 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. +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) ===== ===== Proposed PHP Version(s) =====
 8.1 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 ''<nowiki>__construct</nowiki>'' method and an equivalent static ''create'' method. 
-Other classes inside the intl extension (like ''IntlCalendar'') only provide a static ''create'' method, and leave the ''<nowiki>__</nowiki>construct'' method private. Is there a preferred way, or are both equivalent? 
  
 ===== Future Scope ===== ===== 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. 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 ===== +===== Vote ===== 
-Yes/No, requiring a 2/3 majority.+Yes/No, requiring a 2/3 majority. Voting started on 2021-05-14 16:00 UTC and ends 2021-05-28 16:00 UTC. 
 +<doodle title="Add IntlDatePatternGenerator?" auth="deltragon" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle>
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
rfc/intldatetimepatterngenerator.1619276298.txt.gz · Last modified: 2021/04/24 14:58 by deltragon