feat: implement FormatPHP::formatDisplayName() method (#47)

Author: ramsey

CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## 0.7.0 - 2022-02-11
+
+### Added
+
+- Provide functionality for formatting locale-appropriate display names with `Intl\DisplayNames` and `FormatPHP::formatDisplayName()`.
+
+### Changed
+
+- Nothing.
+
+### Deprecated
+
+- Nothing.
+
+### Removed
+
+- Nothing.
+
+### Fixed
+
+- Nothing.
+
 ## 0.6.0 - 2022-02-07
 
 ### Added

README.md

@@ -81,8 +81,8 @@ echo $formatphp->formatMessage([
 
 ### Formatting Numbers and Currency
 
-You may use the methods `formatNumber()` and `formatCurrency()` for format
-numbers and currency, according to the locale.
+You may use the methods `formatNumber()` and `formatCurrency()` to format
+numbers and currency according to the locale.
 
 ```php
 use FormatPHP\Config;
@@ -366,6 +366,65 @@ Additional options include:
   You may use the zone names of the [IANA time zone database](https://www.iana.org/time-zones),
   such as "Asia/Shanghai", "Asia/Kolkata", "America/New_York".
 
+### Formatting Display Names of Languages, Regions, Currency, and More
+
+You may use the method `formatDisplayName()` to format the display names of
+languages, regions, currency, and more. This returns a locale-appropriate,
+translated string for the type requested.
+
+```php
+use FormatPHP\Config;
+use FormatPHP\FormatPHP;
+use FormatPHP\Intl;
+
+$config = new Config(new Intl\Locale('en-US'));
+$formatphp = new FormatPHP($config);
+
+echo $formatphp->formatDisplayName('zh-Hans-SG', new Intl\DisplayNamesOptions([
+    'type' => 'language',
+])); // e.g., "Chinese (Simplified, Singapore)"
+
+echo $formatphp->formatDisplayName('Deva', new Intl\DisplayNamesOptions([
+    'type' => 'script',
+])); // e.g., "Devanagari"
+
+echo $formatphp->formatDisplayName('CNY', new Intl\DisplayNamesOptions([
+    'type' => 'currency',
+])); // e.g., "Chinese yuan"
+
+echo $formatphp->formatDisplayName('CNY', new Intl\DisplayNamesOptions([
+    'type' => 'currency',
+    'style' => 'narrow',
+])); // e.g., "¥"
+
+echo $formatphp->formatDisplayName('UN', new Intl\DisplayNamesOptions([
+    'type' => 'region',
+])); // e.g., "United Nations"
+```
+
+#### Using Intl\DisplayNamesOptions with formatDisplayName()
+
+When formatting display names, you must provide a `DisplayNamesOptions` instance
+with at least a `type` defined.
+
+* `type`: The type of data for which we wish to format a display name. This
+  currently supports `currency`, `language`, `region`, and `script`.  While
+  [ECMA-402](https://tc39.es/ecma402/#sec-intl-displaynames-constructor) defines
+  `calendar` and `dateTimeField` as additional types, these types are not
+  implemented in Node.js or in any browsers. In fact, if set, the
+  implementations throw exceptions, so this FormatPHP follows the same
+  pattern.
+* `fallback`: The fallback strategy to use. If we are unable to format a display
+  name, we will return the same code provided if `fallback` is set to `code.` If
+  `fallback` is `none`, then we return `null`. The default `fallback` is `code`.
+* `style`: The formatting style to use: `long`, `short`, or `narrow`. This
+  currently only affects the display name when `type` is `currency`, and the
+  default is `long`.
+* `languageDisplay`: This is a suggestion for displaying the language according
+  to the locale's dialect or standard representation. In JavaScript, this
+  defaults to `dialect`. For now, PHP supports only the `standard`
+  representation, so `dialect` has no effect.
+
 ### Rich Text Formatting (Use of Tags in Messages)
 
 While the ICU message syntax does not prohibit the use of HTML tags in formatted

src/Exception/UnableToFormatDisplayNameException.php

@@ -0,0 +1,30 @@
+<?php
+
+/**
+ * This file is part of skillshare/formatphp
+ *
+ * skillshare/formatphp is open source software: you can distribute
+ * it and/or modify it under the terms of the MIT License
+ * (the "License"). You may not use this file except in
+ * compliance with the License.
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ * implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ *
+ * @copyright Copyright (c) Skillshare, Inc. <https://www.skillshare.com>
+ * @license https://opensource.org/licenses/MIT MIT License
+ */
+
+declare(strict_types=1);
+
+namespace FormatPHP\Exception;
+
+/**
+ * Thrown when we are unable to format a display name
+ */
+class UnableToFormatDisplayNameException extends UnableToFormatStringException
+{
+}

src/FormatPHP.php

@@ -27,6 +27,8 @@
 use Exception as PhpException;
 use FormatPHP\Intl\DateTimeFormat;
 use FormatPHP\Intl\DateTimeFormatOptions;
+use FormatPHP\Intl\DisplayNames;
+use FormatPHP\Intl\DisplayNamesOptions;
 use FormatPHP\Intl\MessageFormat;
 use FormatPHP\Intl\NumberFormat;
 use FormatPHP\Intl\NumberFormatOptions;
@@ -156,6 +158,19 @@ public function formatCurrency($value, string $currencyCode, ?NumberFormatOption
         return $this->formatNumber($value, $options);
     }
 
+    /**
+     * @throws Exception\InvalidArgumentException
+     * @throws Exception\UnableToFormatDisplayNameException
+     *
+     * @inheritdoc
+     */
+    public function formatDisplayName(string $value, ?DisplayNamesOptions $options = null): ?string
+    {
+        $formatter = new DisplayNames($this->config->getLocale(), $options);
+
+        return $formatter->of($value);
+    }
+
     protected function getConfig(): ConfigInterface
     {
         return $this->config;

src/FormatterInterface.php

@@ -24,6 +24,7 @@
 
 use DateTimeInterface as PhpDateTimeInterface;
 use FormatPHP\Intl\DateTimeFormatOptions;
+use FormatPHP\Intl\DisplayNamesOptions;
 use FormatPHP\Intl\NumberFormatOptions;
 
 /**
@@ -109,4 +110,15 @@ public function formatNumber($number, ?NumberFormatOptions $options = null): str
      * @throws Exception\UnableToFormatNumberException
      */
     public function formatCurrency($value, string $currencyCode, ?NumberFormatOptions $options = null): string;
+
+    /**
+     * Returns a translated, localized display string for the given code
+     *
+     * Additional options may be provided to configure how the display name
+     * should be formatted.
+     *
+     * @throws Exception\InvalidArgumentException
+     * @throws Exception\UnableToFormatDisplayNameException
+     */
+    public function formatDisplayName(string $value, ?DisplayNamesOptions $options = null): ?string;
 }