Implement Plural Rules

lcharette · lcharette · commit 3cdeb2ec9753 · 2025-02-08T22:02:30.000-05:00
diff --git a/src/I18n/PluralRules/Rule0.php b/src/I18n/PluralRules/Rule0.php
@@ -20,7 +20,7 @@
  */
 final class Rule0 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         return 1;
     }
diff --git a/src/I18n/PluralRules/Rule1.php b/src/I18n/PluralRules/Rule1.php
@@ -21,7 +21,7 @@
  */
 final class Rule1 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         return ($number == 1) ? 1 : 2;
     }
diff --git a/src/I18n/PluralRules/Rule10.php b/src/I18n/PluralRules/Rule10.php
@@ -23,7 +23,7 @@
  */
 final class Rule10 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if ($number % 100 == 1) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule11.php b/src/I18n/PluralRules/Rule11.php
@@ -24,7 +24,7 @@
  */
 final class Rule11 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if ($number == 1) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule12.php b/src/I18n/PluralRules/Rule12.php
@@ -26,7 +26,7 @@
  */
 final class Rule12 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if ($number == 1) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule13.php b/src/I18n/PluralRules/Rule13.php
@@ -23,7 +23,7 @@
  */
 final class Rule13 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if ($number === 1) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule14.php b/src/I18n/PluralRules/Rule14.php
@@ -22,7 +22,7 @@
  */
 final class Rule14 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if ($number % 10 == 1) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule15.php b/src/I18n/PluralRules/Rule15.php
@@ -21,7 +21,7 @@
  */
 final class Rule15 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if (($number % 10 == 1) && ($number % 100 != 11)) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule2.php b/src/I18n/PluralRules/Rule2.php
@@ -21,7 +21,7 @@
  */
 final class Rule2 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if ($number == 0 || $number == 1) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule3.php b/src/I18n/PluralRules/Rule3.php
@@ -22,7 +22,7 @@
  */
 final class Rule3 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if ($number == 0) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule4.php b/src/I18n/PluralRules/Rule4.php
@@ -23,7 +23,7 @@
  */
 final class Rule4 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if ($number == 1 || $number == 11) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule5.php b/src/I18n/PluralRules/Rule5.php
@@ -22,7 +22,7 @@
  */
 final class Rule5 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if ($number == 1) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule6.php b/src/I18n/PluralRules/Rule6.php
@@ -22,7 +22,7 @@
  */
 final class Rule6 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if (($number % 10 == 1) && ($number % 100 != 11)) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule7.php b/src/I18n/PluralRules/Rule7.php
@@ -22,7 +22,7 @@
  */
 final class Rule7 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if (($number % 10 == 1) && ($number % 100 != 11)) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule8.php b/src/I18n/PluralRules/Rule8.php
@@ -22,7 +22,7 @@
  */
 final class Rule8 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if ($number == 1) {
             return 1;
diff --git a/src/I18n/PluralRules/Rule9.php b/src/I18n/PluralRules/Rule9.php
@@ -22,7 +22,7 @@
  */
 final class Rule9 implements RuleInterface
 {
-    public static function getRule(int $number): int
+    public static function selectPluralForm(int $number): int
     {
         if ($number == 1) {
             return 1;
diff --git a/src/I18n/PluralRules/RuleInterface.php b/src/I18n/PluralRules/RuleInterface.php
@@ -22,11 +22,11 @@
 interface RuleInterface
 {
     /**
-     * Return the rule to apply.
+     * Return the plural form to apply.
      *
-     * @param int $number The number we want the rule for
+     * @param int $number The number we want the plural form for
      *
-     * @return int The rule
+     * @return int The plural form to use
      */
-    public static function getRule(int $number): int;
+    public static function selectPluralForm(int $number): int;
 }
diff --git a/src/I18n/Translator.php b/src/I18n/Translator.php
@@ -231,7 +231,7 @@ protected function getPluralValue(array|int $placeholders, string $pluralKey): ?
 
     /**
      * Return the correct plural message form to use.
-     * When multiple plural form are available for a message, this method will return the correct oen to use based on the numeric value.
+     * When multiple plural form are available for a message, this method will return the correct one to use based on the numeric value.
      *
      * @param mixed[] $messageArray The array with all the form inside ($pluralRule => $message)
      * @param int     $pluralValue  The numeric value used to select the correct message
@@ -240,7 +240,9 @@ protected function getPluralValue(array|int $placeholders, string $pluralKey): ?
      */
     protected function getPluralMessageKey(array $messageArray, int $pluralValue): ?int
     {
-        // Bypass the rules for a value of "0" so that "0 users" may be displayed as "No users".
+        // Bypass the rules for a value of "0". Instead of returning the correct
+        // plural form (>= 1), we force return the "0" form, which can used to
+        // display "0 users" as "No users".
         if ($pluralValue == 0 && isset($messageArray[0])) {
             return 0;
         }
@@ -253,7 +255,8 @@ protected function getPluralMessageKey(array $messageArray, int $pluralValue): ?
             return $usePluralForm;
         }
 
-        // If the key we need doesn't exist, use the previous available one.
+        // If the key we need doesn't exist, use the previous available one, including the special "0" form
+        // This is a fallback to avoid errors when the dictionary is not complete
         $numbers = array_keys($messageArray);
         foreach (array_reverse($numbers) as $num) {
             if (is_int($num) && $num > $usePluralForm) {
@@ -326,25 +329,20 @@ protected function parsePlaceHolders(string $message, $placeholders): string
      *
      * @see https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_and_Plurals
      *
-     * @param int|float $number    The number we want to get the plural case for. Float numbers are floored.
-     * @param int|bool  $forceRule False to use the plural rule of the language package
-     *                             or an integer to force a certain plural rule
+     * @param int|float $number    The number we want to get the plural form of. Float numbers are floored.
+     * @param int|null  $forceRule Used to force a certain plural rule. Null (default) to use the plural rule of the language package.
      *
-     * @return int The plural-case we need to use for the number plural-rule combination
+     * @return int The plural form we need to use for the number & plural rule combination
      */
-    public function getPluralForm(int|float $number, int|bool $forceRule = false): int
+    public function getPluralForm(int|float $number, ?int $forceRule = null): int
     {
-        if (is_int($forceRule)) {
-            $ruleNumber = $forceRule;
-        } else {
-            $ruleNumber = $this->dictionary->getLocale()->getPluralRule();
-        }
+        $rule = $forceRule ?? $this->dictionary->getLocale()->getPluralRule();
 
         // Get the rule class
-        if (!array_key_exists($ruleNumber, $this->rulesClass)) {
-            throw new OutOfRangeException("The rule number '$ruleNumber' must be between 0 and 15.");
+        if (!array_key_exists($rule, $this->rulesClass)) {
+            throw new OutOfRangeException("The rule number '$rule' must be between 0 and 15.");
         }
 
-        return $this->rulesClass[$ruleNumber]::getRule((int) $number);
+        return $this->rulesClass[$rule]::selectPluralForm((int) $number);
     }
 }
diff --git a/src/I18n/docs/README.md b/src/I18n/docs/README.md
@@ -142,7 +142,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -154,7 +154,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -166,7 +166,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -178,7 +178,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -190,7 +190,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -202,7 +202,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -214,7 +214,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -226,7 +226,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -238,7 +238,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -250,7 +250,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>int</em> <strong>$number</strong>)</strong> : <em>int The rule</em><br /><em>Return the rule to apply.</em> |
+| public static | <strong>selectPluralForm(</strong><em>int</em> <strong>$number</strong>)</strong> : <em>int The rule</em><br /><em>Return the rule to apply.</em> |
 
 <hr />
 
@@ -260,7 +260,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -272,7 +272,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -284,7 +284,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -296,7 +296,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -308,7 +308,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -320,7 +320,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
@@ -332,7 +332,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public static | <strong>getRule(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
+| public static | <strong>selectPluralForm(</strong><em>mixed</em> <strong>$number</strong>)</strong> : <em>mixed</em> |
 
 *This class implements [\UserFrosting\I18n\PluralRules\RuleInterface](#interface-userfrostingi18npluralrulesruleinterface)*
 
diff --git a/tests/I18n/Rules/RuleBase.php b/tests/I18n/Rules/RuleBase.php
@@ -39,7 +39,7 @@ public function testRuleClass(): void
     public function testRule(int $number, int $expectedResult): void
     {
         $rule = $this->ruleToTest;
-        $result = $rule::getRule($number);
+        $result = $rule::selectPluralForm($number);
         $this->assertSame($expectedResult, $result);
     }
 

Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@`
`20`	`20`	`*/`
`21`	`21`	`final class Rule0 implements RuleInterface`
`22`	`22`	`{`
`23`		`- public static function getRule(int $number): int`
	`23`	`+ public static function selectPluralForm(int $number): int`
`24`	`24`	`{`
`25`	`25`	`return 1;`
`26`	`26`	`}`
Original file line number	Diff line number	Diff line change
`@@ -21,7 +21,7 @@`
`21`	`21`	`*/`
`22`	`22`	`final class Rule1 implements RuleInterface`
`23`	`23`	`{`
`24`		`- public static function getRule(int $number): int`
	`24`	`+ public static function selectPluralForm(int $number): int`
`25`	`25`	`{`
`26`	`26`	`return ($number == 1) ? 1 : 2;`
`27`	`27`	`}`
Original file line number	Diff line number	Diff line change
`@@ -23,7 +23,7 @@`
`23`	`23`	`*/`
`24`	`24`	`final class Rule10 implements RuleInterface`
`25`	`25`	`{`
`26`		`- public static function getRule(int $number): int`
	`26`	`+ public static function selectPluralForm(int $number): int`
`27`	`27`	`{`
`28`	`28`	`if ($number % 100 == 1) {`
`29`	`29`	`return 1;`
Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@`
`24`	`24`	`*/`
`25`	`25`	`final class Rule11 implements RuleInterface`
`26`	`26`	`{`
`27`		`- public static function getRule(int $number): int`
	`27`	`+ public static function selectPluralForm(int $number): int`
`28`	`28`	`{`
`29`	`29`	`if ($number == 1) {`
`30`	`30`	`return 1;`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@`
`26`	`26`	`*/`
`27`	`27`	`final class Rule12 implements RuleInterface`
`28`	`28`	`{`
`29`		`- public static function getRule(int $number): int`
	`29`	`+ public static function selectPluralForm(int $number): int`
`30`	`30`	`{`
`31`	`31`	`if ($number == 1) {`
`32`	`32`	`return 1;`
Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,7 @@`
`22`	`22`	`*/`
`23`	`23`	`final class Rule14 implements RuleInterface`
`24`	`24`	`{`
`25`		`- public static function getRule(int $number): int`
	`25`	`+ public static function selectPluralForm(int $number): int`
`26`	`26`	`{`
`27`	`27`	`if ($number % 10 == 1) {`
`28`	`28`	`return 1;`