v0.3.0 update

Author: LamentXU123

docs/rfc-ext-intl-locale-display-keyword.wiki

@@ -0,0 +1,350 @@
+====== PHP RFC: Add Locale::getDisplayKeyword() and Locale::getDisplayKeywordValue() ======
+  * Version: 0.9
+  * Date: 2026-05-22
+  * Author: Your Name, your_email_address@example.com
+  * Status: Draft
+  * Implementation: https://github.com/...
+  * Discussion thread:
+
+===== Introduction =====
+
+This RFC proposes adding ``Locale::getDisplayKeyword()`` and
+``Locale::getDisplayKeywordValue()`` to ``ext/intl``, together with their
+procedural aliases. These APIs expose ICU's
+``uloc_getDisplayKeyword()`` and ``uloc_getDisplayKeywordValue()`` to PHP
+userland.
+
+PHP already exposes a family of locale display helpers such as
+``Locale::getDisplayLanguage()``, ``Locale::getDisplayRegion()``,
+``Locale::getDisplayVariant()``, and ``Locale::getDisplayName()``. PHP also
+exposes ``Locale::getKeywords()``, which allows code to extract locale keyword
+pairs. What is currently missing is a way to localize the keyword names
+themselves and the display labels for their values. This proposal fills that
+gap in a way that is consistent with the existing ``Locale`` API surface.
+
+<PHP>
+<?php
+
+$locale = 'de_DE@collation=phonebook';
+$keyword = 'collation';
+
+echo Locale::getDisplayKeyword($keyword, 'en'), PHP_EOL;
+echo Locale::getDisplayKeywordValue($locale, $keyword, 'en'), PHP_EOL;
+
+?>
+</PHP>
+
+===== Proposal =====
+
+Add two new procedural functions and two new ``Locale`` static methods:
+
+<PHP>
+<?php
+
+function locale_get_display_keyword(
+    string $keyword,
+    ?string $displayLocale = null
+): string|false {}
+
+function locale_get_display_keyword_value(
+    string $locale,
+    string $keyword,
+    ?string $displayLocale = null
+): string|false {}
+
+class Locale
+{
+    public static function getDisplayKeyword(
+        string $keyword,
+        ?string $displayLocale = null
+    ): string|false {}
+
+    public static function getDisplayKeywordValue(
+        string $locale,
+        string $keyword,
+        ?string $displayLocale = null
+    ): string|false {}
+}
+
+?>
+</PHP>
+
+The proposed methods intentionally follow the existing ``Locale::getDisplay*()``
+naming pattern.
+
+==== Semantics ====
+
+``Locale::getDisplayKeyword()`` returns a localized display label for a locale
+keyword, such as ``collation`` or ``calendar``.
+
+``Locale::getDisplayKeywordValue()`` returns a localized display label for the
+value of a given keyword inside a locale identifier.
+
+The new APIs should follow the behavior of the existing display-oriented
+``Locale`` methods:
+
+  * If ``$displayLocale`` is ``null``, the current default locale is used.
+  * On ICU failure, the function returns ``false`` and reports the error through
+    the existing intl error mechanism.
+  * Embedded NUL bytes in string parameters should continue to throw
+    ``ValueError``, consistent with current locale input handling.
+  * Invalid locale strings should continue to follow existing ICU-backed
+    ``ext/intl`` behavior.
+
+==== Motivation ====
+
+This proposal brings practical value because it completes an already existing
+workflow in ``ext/intl``:
+
+  * Parse or receive a locale identifier.
+  * Extract keyword/value pairs via ``Locale::getKeywords()``.
+  * Render those keywords and values for humans in a chosen display locale.
+
+Without these APIs, userland code must maintain its own mapping layer for
+keyword labels and keyword values, even though ICU already contains the data and
+PHP already exposes adjacent display APIs.
+
+This is a pragmatic addition for applications that render locale settings in:
+
+  * admin interfaces
+  * user profile settings
+  * CMS configuration screens
+  * diagnostics and developer tooling
+  * internationalization dashboards
+
+==== API Details ====
+
+=== locale_get_display_keyword() / Locale::getDisplayKeyword() ===
+
+Returns a localized display label for a locale keyword.
+
+Example intent:
+
+  * ``Locale::getDisplayKeyword('collation', 'en')`` should return the English
+    display label for the ``collation`` keyword.
+  * ``Locale::getDisplayKeyword('calendar', 'fr')`` should return the French
+    display label for the ``calendar`` keyword.
+
+=== locale_get_display_keyword_value() / Locale::getDisplayKeywordValue() ===
+
+Returns a localized display label for the value of a given locale keyword.
+
+The first parameter is the locale string that carries the keyword value. The
+second parameter identifies which keyword should be resolved from that locale.
+
+Example intent:
+
+  * ``Locale::getDisplayKeywordValue('de_DE@collation=phonebook', 'collation', 'en')``
+    should return the English display label for the ``phonebook`` collation
+    value.
+  * ``Locale::getDisplayKeywordValue('en_US@calendar=gregorian', 'calendar', 'en')``
+    should return the English display label for the ``gregorian`` calendar
+    value.
+
+==== Interaction with Existing Functionality ====
+
+This RFC complements, rather than replaces, the following existing APIs:
+
+  * ``Locale::getKeywords()``
+  * ``Locale::getDisplayLanguage()``
+  * ``Locale::getDisplayScript()``
+  * ``Locale::getDisplayRegion()``
+  * ``Locale::getDisplayVariant()``
+  * ``Locale::getDisplayName()``
+
+The new methods are specifically intended to cover the missing "display the
+keyword and its value" step.
+
+==== Edge Cases ====
+
+The following edge cases should be covered by tests and documented:
+
+  * ``$displayLocale === null`` uses the default locale.
+  * Locale identifiers with multiple keyword/value pairs.
+  * A requested keyword not present in the locale identifier.
+  * Invalid locale strings.
+  * Invalid or unsupported keywords.
+  * Embedded NUL bytes in any string argument.
+
+If a keyword is not present in the locale identifier, the implementation should
+follow ICU behavior and existing ``ext/intl`` failure conventions rather than
+inventing PHP-specific fallback semantics.
+
+==== Examples ====
+
+Simple example:
+
+<PHP>
+<?php
+
+$locale = 'de_DE@collation=phonebook';
+
+echo Locale::getDisplayKeyword('collation', 'en'), PHP_EOL;
+echo Locale::getDisplayKeywordValue($locale, 'collation', 'en'), PHP_EOL;
+
+?>
+</PHP>
+
+Example showing composition with ``Locale::getKeywords()``:
+
+<PHP>
+<?php
+
+$locale = 'en_US@calendar=gregorian;collation=phonebook';
+$displayLocale = 'en';
+
+foreach (Locale::getKeywords($locale) as $keyword => $value) {
+    $label = Locale::getDisplayKeyword($keyword, $displayLocale);
+    $displayValue = Locale::getDisplayKeywordValue($locale, $keyword, $displayLocale);
+
+    printf("%s: %s\n", $label, $displayValue);
+}
+
+?>
+</PHP>
+
+Example showing an edge case:
+
+<PHP>
+<?php
+
+var_dump(Locale::getDisplayKeywordValue('en_US@calendar=gregorian', 'currency', 'en'));
+
+?>
+</PHP>
+
+The exact return value in the edge case above should match ICU-backed failure
+behavior as implemented in the patch and documented in the manual.
+
+===== Backward Incompatible Changes =====
+
+There are no intentional backward incompatible changes to existing behavior.
+
+However, the following low-risk compatibility concerns exist and should be noted:
+
+  * New global functions ``locale_get_display_keyword()`` and
+    ``locale_get_display_keyword_value()`` may conflict with userland polyfills
+    in codebases that defined those names conditionally.
+  * New ``Locale`` methods may conflict with userland subclasses of ``Locale``
+    that already define methods with the same names but incompatible signatures.
+
+These risks are typical for additions of new internal functions and methods.
+
+Before voting, it would be reasonable to do a lightweight ecosystem scan using:
+
+  * GitHub code search
+  * grep.app
+  * Sourcegraph
+
+to estimate whether these exact names are already used in polyfills or
+``Locale`` subclasses.
+
+===== Proposed PHP Version(s) =====
+
+Next PHP 8.x.
+
+===== RFC Impact =====
+
+==== To the Ecosystem ====
+
+This is a straightforward API addition. IDEs, LSPs, static analyzers, and
+documentation generators would need updated stubs so the new functions and
+methods are recognized.
+
+Userland internationalization libraries and admin UIs may simplify their own
+locale metadata mapping code if they choose to adopt these APIs.
+
+==== To Existing Extensions ====
+
+No existing extension behavior should change.
+
+The implementation is limited to ``ext/intl`` and its stubs, arginfo, tests,
+and manual documentation.
+
+==== To SAPIs ====
+
+No SAPI-specific impact is expected.
+
+Behavior should be identical across CLI, FPM, Apache module, the development
+server, and embedded use, subject only to the availability and behavior of the
+linked ICU version as already applies to ``ext/intl``.
+
+===== Open Issues =====
+
+The following details should be confirmed during discussion and resolved before
+the RFC enters voting:
+
+  * Exact failure behavior when the requested keyword is absent from the locale.
+  * Exact failure behavior for invalid or unsupported keyword names.
+  * Whether the implementation should share an internal helper with the existing
+    ``Locale::getDisplay*()`` functions for consistency.
+  * Whether an implementation PR will be prepared before the RFC enters voting.
+
+===== Future Scope =====
+
+This RFC does not propose a general policy that all ICU locale helper functions
+must be exposed automatically.
+
+It is intentionally limited to two methods that fit naturally into the existing
+``Locale::getDisplay*()`` family and directly complement
+``Locale::getKeywords()``.
+
+Future RFCs may evaluate other ICU-backed locale helpers independently on their
+own merits.
+
+===== Voting Choices =====
+
+Primary Vote requiring a 2/3 majority to accept the RFC:
+
+<doodle title="Add Locale::getDisplayKeyword() and Locale::getDisplayKeywordValue() as outlined in the RFC?" voteType="single" closed="true" closeon="2026-05-29T15:30:00Z">
+   * Yes
+   * No
+   * Abstain
+</doodle>
+
+===== Patches and Tests =====
+
+No implementation PR exists yet.
+
+The expected implementation work is:
+
+  * wrappers around ICU's ``uloc_getDisplayKeyword()`` and
+    ``uloc_getDisplayKeywordValue()``
+  * ``ext/intl/php_intl.stub.php`` updates
+  * ``ext/intl/locale/locale.stub.php`` updates
+  * arginfo regeneration
+  * phpt coverage for success and failure cases
+
+If there is no patch by the time discussion begins, the RFC should clearly state
+who plans to implement it.
+
+===== Implementation =====
+
+After the RFC 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
+
+===== References =====
+
+  * GH-22097: https://github.com/php/php-src/issues/22097
+  * ICU ``uloc_getDisplayKeyword()`` and ``uloc_getDisplayKeywordValue()``:
+    https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/uloc_8h.html
+  * PHP RFC howto: https://wiki.php.net/rfc/howto
+
+===== Rejected Features =====
+
+The earlier idea of exposing locale orientation APIs
+(``Locale::getCharacterOrientation()`` and ``Locale::getLineOrientation()``)
+was discussed first, but this RFC intentionally does not pursue that direction.
+
+The reason is that ``Locale::getDisplayKeyword()`` and
+``Locale::getDisplayKeywordValue()`` fill a clearer gap in the existing
+``Locale`` API and are more naturally aligned with common PHP application needs.
+
+===== Changelog =====
+
+  * 2026-05-22: Initial wiki-format draft created. Scope focused on
+    ``Locale::getDisplayKeyword()`` and
+    ``Locale::getDisplayKeywordValue()`` instead of locale orientation APIs.