From 7684141f9dac8c09f4766f7befdc054ad083a59c Mon Sep 17 00:00:00 2001 From: kylekatarnls Date: Wed, 13 Mar 2024 12:22:44 +0100 Subject: [PATCH] Cleanup and warranty notice --- src/Carbon/Language.php | 131 ++++++++---------------------------- src/Carbon/List/regions.php | 45 ++++++++++--- 2 files changed, 64 insertions(+), 112 deletions(-) diff --git a/src/Carbon/Language.php b/src/Carbon/Language.php index 57162700b6..6197e8b007 100644 --- a/src/Carbon/Language.php +++ b/src/Carbon/Language.php @@ -14,54 +14,26 @@ namespace Carbon; use JsonSerializable; -use ReturnTypeWillChange; class Language implements JsonSerializable { - /** - * @var array - */ - protected static $languagesNames; + protected static ?array $languagesNames = null; - /** - * @var array - */ - protected static $regionsNames; + protected static ?array $regionsNames = null; - /** - * @var string - */ - protected $id; + protected string $id; - /** - * @var string - */ - protected $code; + protected string $code; - /** - * @var string|null - */ - protected $variant; + protected ?string $variant = null; - /** - * @var string|null - */ - protected $region; + protected ?string $region = null; - /** - * @var array - */ - protected $names; + protected ?array $names = null; - /** - * @var string - */ - protected $isoName; + protected ?string $isoName = null; - /** - * @var string - */ - protected $nativeName; + protected ?string $nativeName = null; public function __construct(string $id) { @@ -85,11 +57,9 @@ public function __construct(string $id) * * @return array */ - public static function all() + public static function all(): array { - if (!static::$languagesNames) { - static::$languagesNames = require __DIR__.'/List/languages.php'; - } + static::$languagesNames ??= require __DIR__.'/List/languages.php'; return static::$languagesNames; } @@ -97,38 +67,31 @@ public static function all() /** * Get the list of the known regions. * - * @return array + * ⚠ ISO 3166-2 short name provided with no warranty, should not + * be used for any purpose to show official state names. */ - public static function regions() + public static function regions(): array { - if (!static::$regionsNames) { - static::$regionsNames = require __DIR__.'/List/regions.php'; - } + static::$regionsNames ??= require __DIR__.'/List/regions.php'; return static::$regionsNames; } /** * Get both isoName and nativeName as an array. - * - * @return array */ public function getNames(): array { - if (!$this->names) { - $this->names = static::all()[$this->code] ?? [ - 'isoName' => $this->code, - 'nativeName' => $this->code, - ]; - } + $this->names ??= static::all()[$this->code] ?? [ + 'isoName' => $this->code, + 'nativeName' => $this->code, + ]; return $this->names; } /** * Returns the original locale ID. - * - * @return string */ public function getId(): string { @@ -137,8 +100,6 @@ public function getId(): string /** * Returns the code of the locale "en"/"fr". - * - * @return string */ public function getCode(): string { @@ -147,8 +108,6 @@ public function getCode(): string /** * Returns the variant code such as cyrl/latn. - * - * @return string|null */ public function getVariant(): ?string { @@ -157,8 +116,6 @@ public function getVariant(): ?string /** * Returns the variant such as Cyrillic/Latin. - * - * @return string|null */ public function getVariantName(): ?string { @@ -175,8 +132,6 @@ public function getVariantName(): ?string /** * Returns the region part of the locale. - * - * @return string|null */ public function getRegion(): ?string { @@ -186,7 +141,8 @@ public function getRegion(): ?string /** * Returns the region name for the current language. * - * @return string|null + * ⚠ ISO 3166-2 short name provided with no warranty, should not + * be used for any purpose to show official state names. */ public function getRegionName(): ?string { @@ -195,22 +151,16 @@ public function getRegionName(): ?string /** * Returns the long ISO language name. - * - * @return string */ public function getFullIsoName(): string { - if (!$this->isoName) { - $this->isoName = $this->getNames()['isoName']; - } + $this->isoName ??= $this->getNames()['isoName']; return $this->isoName; } /** * Set the ISO language name. - * - * @param string $isoName */ public function setIsoName(string $isoName): static { @@ -221,22 +171,16 @@ public function setIsoName(string $isoName): static /** * Return the full name of the language in this language. - * - * @return string */ public function getFullNativeName(): string { - if (!$this->nativeName) { - $this->nativeName = $this->getNames()['nativeName']; - } + $this->nativeName ??= $this->getNames()['nativeName']; return $this->nativeName; } /** * Set the name of the language in this language. - * - * @param string $nativeName */ public function setNativeName(string $nativeName): static { @@ -247,8 +191,6 @@ public function setNativeName(string $nativeName): static /** * Returns the short ISO language name. - * - * @return string */ public function getIsoName(): string { @@ -259,8 +201,6 @@ public function getIsoName(): string /** * Get the short name of the language in this language. - * - * @return string */ public function getNativeName(): string { @@ -271,10 +211,8 @@ public function getNativeName(): string /** * Get a string with short ISO name, region in parentheses if applicable, variant in parentheses if applicable. - * - * @return string */ - public function getIsoDescription() + public function getIsoDescription(): string { $region = $this->getRegionName(); $variant = $this->getVariantName(); @@ -284,10 +222,8 @@ public function getIsoDescription() /** * Get a string with short native name, region in parentheses if applicable, variant in parentheses if applicable. - * - * @return string */ - public function getNativeDescription() + public function getNativeDescription(): string { $region = $this->getRegionName(); $variant = $this->getVariantName(); @@ -297,10 +233,8 @@ public function getNativeDescription() /** * Get a string with long ISO name, region in parentheses if applicable, variant in parentheses if applicable. - * - * @return string */ - public function getFullIsoDescription() + public function getFullIsoDescription(): string { $region = $this->getRegionName(); $variant = $this->getVariantName(); @@ -310,10 +244,8 @@ public function getFullIsoDescription() /** * Get a string with long native name, region in parentheses if applicable, variant in parentheses if applicable. - * - * @return string */ - public function getFullNativeDescription() + public function getFullNativeDescription(): string { $region = $this->getRegionName(); $variant = $this->getVariantName(); @@ -323,21 +255,16 @@ public function getFullNativeDescription() /** * Returns the original locale ID. - * - * @return string */ - public function __toString() + public function __toString(): string { return $this->getId(); } /** * Get a string with short ISO name, region in parentheses if applicable, variant in parentheses if applicable. - * - * @return string */ - #[ReturnTypeWillChange] - public function jsonSerialize() + public function jsonSerialize(): string { return $this->getIsoDescription(); } diff --git a/src/Carbon/List/regions.php b/src/Carbon/List/regions.php index 785e838d7d..f24101516f 100644 --- a/src/Carbon/List/regions.php +++ b/src/Carbon/List/regions.php @@ -12,7 +12,32 @@ */ /* - * ISO 3166-2 + * ISO 3166-2 short names. + * + * ⚠ Provided with No Warranty + * + * This list has no official value, and it's using short name, i.e. the first column of + * https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes + * + * Without the extra parenthesis unless a particular ambiguity in the list. + * + * For instance: + * - Falkland Islands and Malvinas both to FK, but we keep only the first for brevity and + * because there is no ambiguity in the list to justify longer name. + * - For Sint Maarten/Saint Martin not to have any confusion between FM and SX codes that + * are on the same island and so to be clear it's not referring to the whole island, + * south (dutch-speaking) and north (french-speaking) parentheses are kept for disambiguation. + * - For Virgin Islands, that can refer to either VG or VI, parentheses are also kept for + * disambiguation. + * + * We won't take into consideration any change request in this list unless there is an update + * in ISO 3166-2 itself that we need to align to. + * + * It's a purely geographical helper, state sovereignty is out of scope, for political + * complains you should address them directly to https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes + * + * Anyone needing official state names (such as the second column of the wikipedia page above) + * should seek for another tool, this list is not meant to provide long names. */ return [ 'AD' => 'Andorra', @@ -43,7 +68,7 @@ 'BL' => 'Saint Barthélemy', 'BM' => 'Bermuda', 'BN' => 'Brunei Darussalam', - 'BO' => 'Bolivia (Plurinational State of)', + 'BO' => 'Bolivia', 'BQ' => 'Bonaire, Sint Eustatius and Saba', 'BR' => 'Brazil', 'BS' => 'Bahamas', @@ -86,8 +111,8 @@ 'ET' => 'Ethiopia', 'FI' => 'Finland', 'FJ' => 'Fiji', - 'FK' => 'Falkland Islands (Malvinas)', - 'FM' => 'Micronesia (Federated States of)', + 'FK' => 'Falkland Islands', + 'FM' => 'Micronesia', 'FO' => 'Faroe Islands', 'FR' => 'France', 'GA' => 'Gabon', @@ -122,7 +147,7 @@ 'IN' => 'India', 'IO' => 'British Indian Ocean Territory', 'IQ' => 'Iraq', - 'IR' => 'Iran (Islamic Republic of)', + 'IR' => 'Iran', 'IS' => 'Iceland', 'IT' => 'Italy', 'JE' => 'Jersey', @@ -153,12 +178,12 @@ 'LY' => 'Libya', 'MA' => 'Morocco', 'MC' => 'Monaco', - 'MD' => 'Moldova, Republic of', + 'MD' => 'Moldova', 'ME' => 'Montenegro', 'MF' => 'Saint Martin (French part)', 'MG' => 'Madagascar', 'MH' => 'Marshall Islands', - 'MK' => 'Macedonia, the former Yugoslav Republic of', + 'MK' => 'North Macedonia', 'ML' => 'Mali', 'MM' => 'Myanmar', 'MN' => 'Mongolia', @@ -197,7 +222,7 @@ 'PM' => 'Saint Pierre and Miquelon', 'PN' => 'Pitcairn', 'PR' => 'Puerto Rico', - 'PS' => 'Palestine, State of', + 'PS' => 'Palestine', 'PT' => 'Portugal', 'PW' => 'Palau', 'PY' => 'Paraguay', @@ -243,7 +268,7 @@ 'TT' => 'Trinidad and Tobago', 'TV' => 'Tuvalu', 'TW' => 'Taiwan', - 'TZ' => 'Tanzania, United Republic of', + 'TZ' => 'Tanzania', 'UA' => 'Ukraine', 'UG' => 'Uganda', 'UM' => 'United States Minor Outlying Islands', @@ -252,7 +277,7 @@ 'UZ' => 'Uzbekistan', 'VA' => 'Holy See', 'VC' => 'Saint Vincent and the Grenadines', - 'VE' => 'Venezuela (Bolivarian Republic of)', + 'VE' => 'Venezuela', 'VG' => 'Virgin Islands (British)', 'VI' => 'Virgin Islands (U.S.)', 'VN' => 'Viet Nam',