feat: add method to spell conversion result(s) out in words (#171)

* test: add case for testing the spellout words feature

* feat: add method to spell conversions out as words instead of numbers

* docs: add example of spellout feature

README.md

@@ -119,7 +119,16 @@ if ($isOverSpeedLimit($capturedSpeed)) { # (bool) true
 }
 ```
 
-## Documentation
+#### Conversion Results as Words
+
+Sometimes you might need localization support for values. This component makes that a breeze by making using the `intl` extension. Simply opt for using the `spellout` method in lieu of `to`. You may also provide an optional locale as the second parameter to translate.
+
+```php
+$converter->convert(1)->from('in')->spellout('cm');       # (string) two point five four
+$converter->convert(1)->from('in')->spellout('cm', 'fr'); # (string) deux virgule cinq quatre
+```
+
+## 4. Documentation
 
 There are two kinds of in-depth documentation for this project: user & API documentation. Use whichever one you need to help answer your questions!
 

composer.json

@@ -11,7 +11,8 @@
     ],
     "require": {
         "php": "^7.1 || ^8.0",
-        "ext-bcmath": "*"
+        "ext-bcmath": "*",
+        "ext-intl": "*"
     },
     "require-dev": {
         "ergebnis/composer-normalize": "^2.13",

src/UnitConverter.php

@@ -14,6 +14,7 @@
 
 namespace UnitConverter;
 
+use NumberFormatter;
 use UnitConverter\Calculator\BinaryCalculator;
 use UnitConverter\Calculator\CalculatorInterface;
 use UnitConverter\Calculator\Formula\UnitConversionFormula;
@@ -187,7 +188,7 @@ public function calculatorExists(): bool
     }
 
     /**
-     * {@inheritDoc}
+     * @return static
      */
     public function convert($value, int $precision = null): UnitConverterInterface
     {
@@ -224,7 +225,7 @@ public function enableConversionLog(): UnitConverterInterface
     }
 
     /**
-     * {@inheritDoc}
+     * @return static
      */
     public function from(string $unit): UnitConverterInterface
     {
@@ -304,6 +305,24 @@ public function setRegistry(UnitRegistryInterface $registry): UnitConverterInter
         return $this;
     }
 
+    /**
+     * Like `to`, but will present the conversion result as words instead of a numeric value.
+     *
+     * @param string $unit The unit being converted **to**. The unit must first be registered to the UnitRegistry.
+     * @param string $locale The locale to translate the number with. Defaults to Canadian English
+     * @return string
+     * @see to
+     */
+    public function spellout(string $unit, string $locale = 'en_CA'): string
+    {
+        if (!extension_loaded('intl')) {
+            throw new RuntimeException('Unable to spellout a conversion due to missing intl library. Please check your PHP extensions.');
+        }
+
+        return (new NumberFormatter($locale, NumberFormatter::SPELLOUT))
+            ->format($this->to($unit));
+    }
+
     /**
      * {@inheritDoc}
      */

tests/unit/UnitConverter.spec.php

@@ -85,6 +85,18 @@ public function assertCalculateMethodReturnsCorrectCalculation()
         $this->assertIsFloat($actual);
     }
 
+    /**
+     * @test
+     * @covers ::spellout
+     */
+    public function assertConversionsCanBeSpelledOut(): void
+    {
+        $this->assertEquals(
+            'two point five four',
+            $this->converter->convert(1)->from('in')->spellout('cm'),
+        );
+    }
+
     /**
      * @test
      * @covers UnitConverter\Exception\BadRegistry