====== PHP RFC: Add IntlDatePatternGenerator ======
  * Version: 1.0
  * Date: 2021-04-24
  * Author: Mel Dafert, mel@dafert.at
  * Status: Implemented
  * Implementation: https://github.com/php/php-src/pull/6771
  * First Published at: http://wiki.php.net/rfc/intldatetimepatterngenerator
  * Target Version: PHP 8.1

===== 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.

<code php>
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 {}
</code>

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

<code php>
$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
*/
</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 =====
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.
<doodle title="Add IntlDatePatternGenerator?" auth="deltragon" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== 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