Wizards for defining Number Format masks for Percentages, Scientific,…

… Numbers, and Currency

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 ### Added
 
 - Support for configuring a Chart Title's overlay [PR #3325](https://github.com/PHPOffice/PhpSpreadsheet/pull/3325)
+- Wizards for defining Number Format masks for Percentages, Scientific, Numbers, and Currency [PR #3334](https://github.com/PHPOffice/PhpSpreadsheet/pull/3334)
 
 ### Changed
 

src/PhpSpreadsheet/Style/NumberFormat/Wizard/Currency.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;
+
+class Currency extends Number
+{
+    public const LEADING_SYMBOL = true;
+
+    public const TRAILING_SYMBOL = false;
+
+    public const SYMBOL_WITH_SPACING = true;
+
+    public const SYMBOL_WITHOUT_SPACING = false;
+
+    protected string $currencyCode = '$';
+
+    protected bool $currencySymbolPosition = self::LEADING_SYMBOL;
+
+    protected bool $currencySymbolSpacing = self::SYMBOL_WITHOUT_SPACING;
+
+    public function __construct(
+        string $currencyCode = '$',
+        int $decimals = 2,
+        bool $thousandsSeparator = true,
+        bool $currencySymbolPosition = self::LEADING_SYMBOL,
+        bool $currencySymbolSpacing = self::SYMBOL_WITHOUT_SPACING
+    ) {
+        $this->setCurrencyCode($currencyCode);
+        $this->setThousandsSeparator($thousandsSeparator);
+        $this->setDecimals($decimals);
+        $this->setCurrencySymbolPosition($currencySymbolPosition);
+        $this->setCurrencySymbolSpacing($currencySymbolSpacing);
+    }
+
+    public function setCurrencyCode(string $currencyCode): void
+    {
+        $this->currencyCode = $currencyCode;
+    }
+
+    public function setCurrencySymbolPosition(bool $currencySymbolPosition = self::LEADING_SYMBOL): void
+    {
+        $this->currencySymbolPosition = $currencySymbolPosition;
+    }
+
+    public function setCurrencySymbolSpacing(bool $currencySymbolSpacing = self::SYMBOL_WITHOUT_SPACING): void
+    {
+        $this->currencySymbolSpacing = $currencySymbolSpacing;
+    }
+
+    public function format(): string
+    {
+        return sprintf(
+            '%s%s%s0%s%s%s',
+            $this->currencySymbolPosition === self::LEADING_SYMBOL ? $this->currencyCode : null,
+            (
+                $this->currencySymbolPosition === self::LEADING_SYMBOL &&
+                $this->currencySymbolSpacing === self::SYMBOL_WITH_SPACING
+            ) ? ' ' : '',
+            $this->thousandsSeparator ? '#,##' : null,
+            $this->decimals > 0 ? '.' . str_repeat('0', $this->decimals) : null,
+            (
+                $this->currencySymbolPosition === self::TRAILING_SYMBOL &&
+                $this->currencySymbolSpacing === self::SYMBOL_WITH_SPACING
+            ) ? ' ' : '',
+            $this->currencySymbolPosition === self::TRAILING_SYMBOL ? $this->currencyCode : null
+        );
+    }
+}

src/PhpSpreadsheet/Style/NumberFormat/Wizard/Number.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;
+
+class Number extends NumberBase implements Wizard
+{
+    public const WITH_THOUSANDS_SEPARATOR = true;
+
+    public const WITHOUT_THOUSANDS_SEPARATOR = false;
+
+    protected bool $thousandsSeparator = true;
+
+    public function __construct(int $decimals = 2, bool $thousandsSeparator = self::WITH_THOUSANDS_SEPARATOR)
+    {
+        $this->setThousandsSeparator($thousandsSeparator);
+        $this->setDecimals($decimals);
+    }
+
+    public function setThousandsSeparator(bool $thousandsSeparator = self::WITH_THOUSANDS_SEPARATOR): void
+    {
+        $this->thousandsSeparator = $thousandsSeparator;
+    }
+
+    public function format(): string
+    {
+        return sprintf(
+            '%s0%s',
+            $this->thousandsSeparator ? '#,##' : null,
+            $this->decimals > 0 ? '.' . str_repeat('0', $this->decimals) : null
+        );
+    }
+}

src/PhpSpreadsheet/Style/NumberFormat/Wizard/NumberBase.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;
+
+abstract class NumberBase
+{
+    protected const MAX_DECIMALS = 30;
+
+    protected int $decimals = 2;
+
+    public function setDecimals(int $decimals = 2): void
+    {
+        $this->decimals = ($decimals > self::MAX_DECIMALS) ? self::MAX_DECIMALS : max($decimals, 0);
+    }
+
+    public function __toString(): string
+    {
+        return $this->format();
+    }
+}

src/PhpSpreadsheet/Style/NumberFormat/Wizard/Percentage.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;
+
+class Percentage extends NumberBase implements Wizard
+{
+    /**
+     * @param int $decimals number of decimal places to display, in the range 0-30
+     */
+    public function __construct(int $decimals = 2)
+    {
+        $this->setDecimals($decimals);
+    }
+
+    public function format(): string
+    {
+        return sprintf('0%s%%', $this->decimals > 0 ? '.' . str_repeat('0', $this->decimals) : null);
+    }
+}

src/PhpSpreadsheet/Style/NumberFormat/Wizard/Scientific.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;
+
+class Scientific extends NumberBase implements Wizard
+{
+    /**
+     * @param int $decimals number of decimal places to display, in the range 0-30
+     */
+    public function __construct(int $decimals = 2)
+    {
+        $this->setDecimals($decimals);
+    }
+
+    public function format(): string
+    {
+        return sprintf('0%sE+00', $this->decimals > 0 ? '.' . str_repeat('0', $this->decimals) : null);
+    }
+}

src/PhpSpreadsheet/Style/NumberFormat/Wizard/Wizard.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard;
+
+interface Wizard
+{
+    public function format(): string;
+}

tests/PhpSpreadsheetTests/Style/NumberFormat/Wizard/CurrencyTest.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheetTests\Style\NumberFormat\Wizard;
+
+use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Currency;
+use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Number;
+use PHPUnit\Framework\TestCase;
+
+class CurrencyTest extends TestCase
+{
+    /**
+     * @dataProvider providerCurrency
+     */
+    public function testCurrency(
+        string $expectedResult,
+        string $currencyCode,
+        int $decimals,
+        bool $thousandsSeparator,
+        bool $currencySymbolPosition,
+        bool $currencySymbolSpacing
+    ): void {
+        $wizard = new Currency($currencyCode, $decimals, $thousandsSeparator, $currencySymbolPosition, $currencySymbolSpacing);
+        self::assertSame($expectedResult, (string) $wizard);
+    }
+
+    public function providerCurrency(): array
+    {
+        return [
+            ['$ 0', '$', 0, Number::WITHOUT_THOUSANDS_SEPARATOR, Currency::LEADING_SYMBOL, Currency::SYMBOL_WITH_SPACING],
+            ['$ #,##0', '$', 0, Number::WITH_THOUSANDS_SEPARATOR, Currency::LEADING_SYMBOL, Currency::SYMBOL_WITH_SPACING],
+            ['$#,##0', '$', 0, Number::WITH_THOUSANDS_SEPARATOR, Currency::LEADING_SYMBOL, Currency::SYMBOL_WITHOUT_SPACING],
+            ['0.00 €', '€', 2, Number::WITHOUT_THOUSANDS_SEPARATOR, Currency::TRAILING_SYMBOL, Currency::SYMBOL_WITH_SPACING],
+            ['#,##0.00 €', '€', 2, Number::WITH_THOUSANDS_SEPARATOR, Currency::TRAILING_SYMBOL, Currency::SYMBOL_WITH_SPACING],
+            ['0.00€', '€', 2, Number::WITHOUT_THOUSANDS_SEPARATOR, Currency::TRAILING_SYMBOL, Currency::SYMBOL_WITHOUT_SPACING],
+        ];
+    }
+}

tests/PhpSpreadsheetTests/Style/NumberFormat/Wizard/NumberTest.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheetTests\Style\NumberFormat\Wizard;
+
+use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Number;
+use PHPUnit\Framework\TestCase;
+
+class NumberTest extends TestCase
+{
+    /**
+     * @dataProvider providerNumber
+     */
+    public function testNumber(string $expectedResult, int $decimals, bool $thousandsSeparator): void
+    {
+        $wizard = new Number($decimals, $thousandsSeparator);
+        self::assertSame($expectedResult, (string) $wizard);
+    }
+
+    public function providerNumber(): array
+    {
+        return [
+            ['0', 0, Number::WITHOUT_THOUSANDS_SEPARATOR],
+            ['#,##0', 0, Number::WITH_THOUSANDS_SEPARATOR],
+            ['0.0', 1, Number::WITHOUT_THOUSANDS_SEPARATOR],
+            ['#,##0.0', 1, Number::WITH_THOUSANDS_SEPARATOR],
+            ['0.00', 2, Number::WITHOUT_THOUSANDS_SEPARATOR],
+            ['#,##0.00', 2, Number::WITH_THOUSANDS_SEPARATOR],
+        ];
+    }
+}

tests/PhpSpreadsheetTests/Style/NumberFormat/Wizard/PercentageTest.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheetTests\Style\NumberFormat\Wizard;
+
+use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Percentage;
+use PHPUnit\Framework\TestCase;
+
+class PercentageTest extends TestCase
+{
+    /**
+     * @dataProvider providerPercentage
+     */
+    public function testPercentage(string $expectedResult, int $decimals): void
+    {
+        $wizard = new Percentage($decimals);
+        self::assertSame($expectedResult, (string) $wizard);
+    }
+
+    public function providerPercentage(): array
+    {
+        return [
+            ['0%', 0],
+            ['0.0%', 1],
+            ['0.00%', 2],
+            ['0.000%', 3],
+            ['0%', -1],
+            ['0.000000000000000000000000000000%', 31],
+        ];
+    }
+}

tests/PhpSpreadsheetTests/Style/NumberFormat/Wizard/ScientificTest.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheetTests\Style\NumberFormat\Wizard;
+
+use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Scientific;
+use PHPUnit\Framework\TestCase;
+
+class ScientificTest extends TestCase
+{
+    /**
+     * @dataProvider providerScientific
+     */
+    public function testScientific(string $expectedResult, int $decimals): void
+    {
+        $wizard = new Scientific($decimals);
+        self::assertSame($expectedResult, (string) $wizard);
+    }
+
+    public function providerScientific(): array
+    {
+        return [
+            ['0E+00', 0],
+            ['0.0E+00', 1],
+            ['0.00E+00', 2],
+            ['0.000E+00', 3],
+            ['0E+00', -1],
+            ['0.000000000000000000000000000000E+00', 31],
+        ];
+    }
+}