Tidy

README.md

@@ -4,10 +4,10 @@
 [![Downloads](https://img.shields.io/packagist/dt/icanboogie/cldr.svg)](https://packagist.org/packages/icanboogie/cldr/stats)
 [![Code Quality](https://img.shields.io/scrutinizer/quality/g/ICanBoogie/CLDR/6.0)](https://scrutinizer-ci.com/g/ICanBoogie/CLDR/?branch=6.0)
 
-The __CLDR__ package helps internationalize your application by leveraging the data and conventions
-defined by the [Unicode Common Locale Data Repository](http://cldr.unicode.org/) (CLDR). It offers
-helpful locale information and data (such as locale names for territories, languages, days…) as well
-as formatters for numbers, currencies, dates and times, units, sequences, lists…
+The __CLDR__ package facilitates the internationalization of your application by leveraging the data
+and conventions established by the [Unicode Common Locale Data Repository][cldr] (CLDR). It provides
+valuable locale information such as names for territories, languages, days… as well as formatters
+for numbers, currencies, dates and times, units, sequences, and lists.
 
 > **Note**
 >
@@ -140,19 +140,19 @@ The documentation is divided into the following parts, mimicking [Unicode's docu
 
 ## Getting started
 
-The CLDR is represented by a [Repository][] instance. The repository accesses data through a
-[Provider][] instance. There are a few providers available in the package, as well as caching
-mechanisms. Picking the right provider depends on your needs: you might want to favor flexibility
-(during development) or predictability (in production).
+The [CLDR][cldr] is represented by a [Repository][] instance, which accesses data through a
+[Provider][] instance. The package offers several and caching mechanisms. Choosing the right
+provider depends on your requirements: you may prioritize flexibility during development or
+predictability in production.
 
 
 
 ### Favor flexibility
 
-[WebProvider][] offers the maximum flexibility: when required, data is retrieved from the JSON
-distribution [hosted on GitHub][2]. To avoid hitting the web with every request, it is recommended
-to use a collection of caches, each with its own strategy. For example, [FileCache][] stores the
-retrieved data as PHP files that can benefit from opcache.
+[WebProvider][] offers maximum flexibility by retrieving data from the JSON distribution [hosted on
+GitHub][2] as needed. To minimize web requests, it is advised to use a collection of caches, each
+with its own strategy. For example, [FileCache][] stores the retrieved data as PHP files, allowing
+it to benefit from opcache.
 
 The following example demonstrates how a repository can be instantiated:
 
@@ -186,19 +186,18 @@ $cldr = new Repository($provider);
 
 ### Favor predictability
 
-You might want to favor predictability and restrict the usage of the repository to a few locales and
-distribute them as part of your application on a read-only filesystem. You can warm up the CLDR
-cache during development and commit the files, or as a building step of your CI/CD pipeline.
+For greater predictability, consider limiting the repository's usage to a few specific locales and
+distributing them as part of your application. You can prepopulate the CLDR cache during development
+and commit the files, or incorporate this step into your CI/CD pipeline build process.
 
 Use [the cldr command][] to warm up the CLDR cache:
 
 ```shell
 ./vendor/bin/cldr warm-up de en fr
 ```
 
-The following example demonstrates how a repository can be instantiated with a restrictive provider
-that uses warmed-up data only. With this configuration, the [RestrictedProvider][] throws an exception
-if the data is not available in the cache.
+The following example illustrates a setup to limit data access to the cache. [RestrictedProvider][]
+throws an exception in an attempt to retrieve data not available in the cache.
 
 ```php
 <?php
@@ -260,4 +259,5 @@ See [CONTRIBUTING](CONTRIBUTING.md) for details.
 [Repository]:                   src/Repository.php
 
 [2]:                            https://github.com/unicode-cldr
+[cldr]:                         http://cldr.unicode.org/
 [the cldr command]:             https://github.com/ICanBoogie/CLDR-CLI

composer.json

@@ -35,7 +35,6 @@
 		"ext-curl": "*",
 		"ext-json": "*",
 		"ext-mbstring": "*",
-		"icanboogie/common": "^6.0",
 		"icanboogie/accessor": "^6.0"
 	},
 	"require-dev": {

generator/src/Command/GenerateCurrency.php

@@ -28,7 +28,6 @@ protected function execute(InputInterface $input, OutputInterface $output): int
          * @var string[] $codes
          *
          * @link https://github.com/unicode-org/cldr-json/blob/45.0.0/cldr-json/cldr-numbers-full/main/en-001/currencies.json
-         * @phpstan-ignore-next-line
          */
         $codes = array_keys($this->repository->locale_for('en-001')['currencies']);
 
@@ -41,7 +40,6 @@ protected function execute(InputInterface $input, OutputInterface $output): int
          * }> $fractions
          *
          * @link https://github.com/unicode-org/cldr-json/blob/45.0.0/cldr-json/cldr-core/supplemental/currencyData.json
-         * @phpstan-ignore-next-line
          */
         $fractions = $this->repository->supplemental['currencyData']['fractions'];
 

generator/src/Command/GenerateSequenceCompanion.php

@@ -21,7 +21,6 @@ public function __construct(
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
-        // @phpstan-ignore-next-line
         $units = $this->repository->locale_for('en-001')['units']['long'];
         $methods = [];
 

generator/src/Command/GenerateTerritoryCode.php

@@ -27,7 +27,6 @@ protected function execute(InputInterface $input, OutputInterface $output): int
          * @var string[] $codes
          *
          * @link https://github.com/unicode-org/cldr-json/blob/45.0.0/cldr-json/cldr-localenames-full/main/en-001/territories.json
-         * @phpstan-ignore-next-line
          */
         $codes = array_keys($this->repository->locale_for('en-001')['territories']);
         $codes = array_values(array_filter($codes, fn($code) => !str_contains($code, '-alt')));

generator/src/Command/GenerateUnitsCompanion.php

@@ -21,7 +21,6 @@ public function __construct(
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
-        // @phpstan-ignore-next-line
         $units = $this->repository->locale_for('en-001')['units']['long'];
         $properties = [];
         $methods = [];

src/AbstractSectionCollection.php

@@ -3,10 +3,12 @@
 namespace ICanBoogie\CLDR;
 
 use ArrayAccess;
-use ICanBoogie\OffsetNotDefined;
+use LogicException;
 
 /**
- * @implements ArrayAccess<string, array>
+ * @template TKey of array-key
+ *
+ * @implements ArrayAccess<TKey, mixed>
  */
 abstract class AbstractSectionCollection implements ArrayAccess
 {
@@ -17,7 +19,7 @@ public function __construct(
     ) {
     }
 
-    abstract public function offsetExists($offset): bool;
+    abstract public function offsetExists(mixed $offset): bool;
 
     /**
      * @var array<string, array>
@@ -28,17 +30,14 @@ abstract public function offsetExists($offset): bool;
     private array $sections = [];
 
     /**
-     * @param string $offset
-     *
-     * @throws OffsetNotDefined
+     * @throws LogicException
      * @throws ResourceNotFound
      */
-    #[\ReturnTypeWillChange] // @phpstan-ignore-line
-    public function offsetGet(
-        $offset
-    ) {
+    #[\ReturnTypeWillChange]
+    public function offsetGet(mixed $offset)
+    {
         if (!$this->offsetExists($offset)) {
-            throw new OffsetNotDefined(offset: $offset, container: $this);
+            throw new LogicException("Offset '$offset' does not exist");
         }
 
         return $this->sections[$offset] ??= $this->repository->fetch(

src/Cache/CacheCollection.php

@@ -5,7 +5,7 @@
 use ICanBoogie\CLDR\Cache;
 
 /**
- * A collection of {@link Cache} instances.
+ * A collection of {@see Cache} instances.
  */
 final class CacheCollection implements Cache
 {

src/CollectionTrait.php

@@ -2,7 +2,7 @@
 
 namespace ICanBoogie\CLDR;
 
-use ICanBoogie\OffsetNotWritable;
+use LogicException;
 
 /**
  * A trait for classes implementing collection.
@@ -13,20 +13,18 @@ trait CollectionTrait
      * @param string $offset
      * @param mixed $value
      *
-     * @throw OffsetNotWritable in attempt to set the offset.
+     * @throw LogicException in an attempt to set the offset.
      */
-    public function offsetSet($offset, $value): void
+    public function offsetSet(mixed $offset, mixed $value): void
     {
-        throw new OffsetNotWritable(offset: $offset, container: $this);
+        throw new LogicException("Offset '$offset' is not writable");
     }
 
     /**
-     * @param string $offset
-     *
-     * @throw OffsetNotWritable in attempt to unset the offset.
+     * @throw LogicException in an attempt to unset the offset.
      */
-    public function offsetUnset($offset): void
+    public function offsetUnset(mixed $offset): void
     {
-        throw new OffsetNotWritable(offset: $offset, container: $this);
+        throw new LogicException("Offset '$offset' is not writable");
     }
 }

src/ContextTransforms.php

@@ -8,7 +8,7 @@
 use function mb_substr;
 
 /**
- * @see http://unicode.org/reports/tr35/tr35-general.html#contextTransformUsage_type_attribute_values
+ * @link https://unicode.org/reports/tr35/tr35-general.html#contextTransformUsage_type_attribute_values
  */
 final class ContextTransforms
 {

src/DateFormatPattern.php → src/DateFormatPatternParser.php

@@ -5,32 +5,36 @@
 /**
  * @link https://www.unicode.org/reports/tr35/tr35-72/tr35-dates.html#Date_Format_Patterns
  */
-final class DateFormatPattern
+final class DateFormatPatternParser
 {
     private const QUOTE = "'";
 
     /**
+     * Parses a date format pattern.
+     *
      * @param string $pattern
-     *     A date format pattern; for example, "yyyy.MM.dd G 'at' HH:mm:ss zzz".
+     *     A date format pattern; for example, "hh 'o''clock' a, zzzz".
      *
      * @return array<string|array{ string, int }>
      *     Where _value_ is either a literal or an array where `0` is a pattern character and `1` its length.
      */
-    public static function tokenize(string $pattern): array
+    public static function parse(string $pattern): array
     {
         static $cache = [];
 
-        return $cache[$pattern] ??= self::do_tokenize($pattern);
+        return $cache[$pattern] ??= self::do_parse($pattern);
     }
 
     /**
+     * Parses a date format pattern.
+     *
      * @param string $pattern
-     *     A date format pattern; for example, "yyyy.MM.dd G 'at' HH:mm:ss zzz".
+     *     A date format pattern; for example, "hh 'o''clock' a, zzzz".
      *
      * @return array<string|array{ string, int }>
      *     Where _value_ is either a literal or an array where `0` is a pattern character and `1` its length.
      */
-    private static function do_tokenize(string $pattern): array
+    private static function do_parse(string $pattern): array
     {
         $tokens = [];
         $is_literal = false;

src/DateTimeAccessor.php

@@ -8,54 +8,47 @@
 /**
  * @property-read int $timestamp Unix timestamp.
  * @property-read int $year Year.
- * @property-read int $month Month of the year.
- * @property-read int $day Day of the month.
- * @property-read int $hour Hour of the day.
- * @property-read int $minute Minute of the hour.
- * @property-read int $second Second of the minute.
- * @property-read int $quarter Quarter of the year.
- * @property-read int $week Week of the year.
- * @property-read int $weekday Day of the week.
+ * @property-read int<1, 12> $month Month of the year.
+ * @property-read int<1, 31> $day Day of the month.
+ * @property-read int<0, 23> $hour Hour of the day.
+ * @property-read int<1, 59> $minute Minute of the hour.
+ * @property-read int<1, 59> $second Second of the minute.
+ * @property-read int<1, 4> $quarter Quarter of the year.
+ * @property-read int<1, 53> $week Week of the year.
+ * @property-read int<1, 7> $weekday Day of the week.
  * @property-read int $year_day Day of the year.
- *
- * @method string format(string $format)
  */
 class DateTimeAccessor
 {
     public function __construct(
-        private readonly DateTimeInterface $datetime
+        public readonly DateTimeInterface $delegate
     ) {
     }
 
-    /**
-     * @return mixed
-     */
-    public function __get(string $property)
+    public function __get(string $property): int
     {
-        $dt = $this->datetime;
+        $f = $this->delegate->format(...);
 
         return match ($property) {
-            'year' => (int)$dt->format('Y'),
-            'month' => (int)$dt->format('m'),
-            'day' => (int)$dt->format('d'),
-            'hour' => (int)$dt->format('H'),
-            'minute' => (int)$dt->format('i'),
-            'second' => (int)$dt->format('s'),
+            'year' => (int)$f('Y'),
+            'month' => (int)$f('m'),
+            'day' => (int)$f('d'),
+            'hour' => (int)$f('H'),
+            'minute' => (int)$f('i'),
+            'second' => (int)$f('s'),
             'quarter' => (int)floor(($this->month - 1) / 3) + 1,
-            'week' => (int)$dt->format('W'),
-            'year_day' => (int)$dt->format('z') + 1,
-            'weekday' => (int)$dt->format('w') ?: 7,
+            'week' => (int)$f('W'),
+            'year_day' => (int)$f('z') + 1,
+            'weekday' => (int)$f('w') ?: 7,
             default => throw new LogicException("Undefined property: $property"),
         };
     }
 
     /**
-     * @param mixed[] $params
-     *
-     * @return mixed
+     * @see DateTimeInterface::format
      */
-    public function __call(string $name, array $params)
+    public function format(string $pattern): string
     {
-        return $this->datetime->$name(...$params);
+        return $this->delegate->format($pattern);
     }
 }

src/DateTimeFormatId.php

@@ -4,7 +4,7 @@
 
 /**
  *
- * @see: https://www.unicode.org/reports/tr35/tr35-72/tr35-dates.html#26-element-datetimeformats
+ * @link https://www.unicode.org/reports/tr35/tr35-72/tr35-dates.html#26-element-datetimeformats
  */
 final class DateTimeFormatId
 {

src/DateTimeFormatLength.php

@@ -3,7 +3,7 @@
 namespace ICanBoogie\CLDR;
 
 /**
- * @see https://www.unicode.org/reports/tr35/tr35-72/tr35-dates.html#26-element-datetimeformats
+ * @link https://www.unicode.org/reports/tr35/tr35-72/tr35-dates.html#26-element-datetimeformats
  */
 enum DateTimeFormatLength: string
 {