Document NumberFormat Wizard Dependency on Intl Extension

Intl is only a "suggested" extension. A lot of the NumberFormat Wizard code depends on it. That's insufficient reason to make it required, but the suggestion text now mentions this dependency explicitly. Also clean up the Wizard documentation to reflect some changes since PhpSpreadsheet 1.28.

Author: oleibman

.github/workflows/main.yml

@@ -35,7 +35,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
-          extensions: ctype, dom, gd, iconv, fileinfo, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
+          extensions: ctype, dom, fileinfo, gd, iconv, intl, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
           coverage: none
 
       - name: Get composer cache directory
@@ -82,7 +82,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: 8.4
-          extensions: ctype, dom, gd, iconv, fileinfo, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
+          extensions: ctype, dom, fileinfo, gd, iconv, intl, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
           coverage: none
 
       # This is non-ideal because it only checks for the last commit of the PR, not all of them, but better than nothing
@@ -99,7 +99,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: 8.4
-          extensions: ctype, dom, gd, iconv, fileinfo, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
+          extensions: ctype, dom, fileinfo, gd, iconv, intl, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
           coverage: none
           tools: cs2pr
 
@@ -130,7 +130,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: 8.4
-          extensions: ctype, dom, gd, iconv, fileinfo, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
+          extensions: ctype, dom, fileinfo, gd, iconv, intl, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
           coverage: none
           tools: cs2pr
 
@@ -161,7 +161,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: 8.4
-          extensions: ctype, dom, gd, iconv, fileinfo, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
+          extensions: ctype, dom, fileinfo, gd, iconv, intl, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
           coverage: none
           tools: cs2pr
 
@@ -192,7 +192,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: 8.4
-          extensions: ctype, dom, gd, iconv, fileinfo, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
+          extensions: ctype, dom, fileinfo, gd, iconv, intl, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
           coverage: none
           tools: cs2pr
 
@@ -231,7 +231,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: 8.4
-          extensions: ctype, dom, gd, iconv, fileinfo, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
+          extensions: ctype, dom, fileinfo, gd, iconv, intl, libxml, mbstring, simplexml, xml, xmlreader, xmlwriter, zip, zlib
           coverage: pcov
 
       - name: Get composer cache directory

composer.json

@@ -103,7 +103,7 @@
         "tecnickcom/tcpdf": "^6.5"
     },
     "suggest": {
-        "ext-intl": "PHP Internationalization Functions",
+        "ext-intl": "PHP Internationalization Functions, regquired for NumberFormat Wizard",
         "mpdf/mpdf": "Option for rendering PDF with PDF Writer",
         "dompdf/dompdf": "Option for rendering PDF with PDF Writer",
         "tecnickcom/tcpdf": "Option for rendering PDF with PDF Writer",

docs/topics/Behind the Mask.md

@@ -194,6 +194,7 @@ But if we use the "pull down" for that block, we access the "Number" tab of "For
 This gives us access to a number of "Wizards" for different "Categories" of masking, as well as "Custom", which allows us to build our own masks.
 
 Since version 1.28.0, PhpSpreadsheet has also provided a set of "Wizards", allowing for the easier creation of Mask values for most Categories.
+In many cases, you will need to enable PHP's `Intl` extension in order to use the Wizards.
 
 ## Mask Categories
 
@@ -232,7 +233,7 @@ var_dump($worksheet->getCell('C20')
 var_dump($worksheet->getCell('C20')->getFormattedValue()); // "-12,345.679"
 ```
 
-PhpSpreadsheet's "Wizard" doesn't yet offer options for displaying negative values; they will simply be masked so that they always display the sign.
+PhpSpreadsheet's Number Wizard doesn't yet offer options for displaying negative values; they will simply be masked so that they always display the sign.
 But alternative masking for negative values is an option that may be added in the future.
 
 ### Currency
@@ -245,6 +246,7 @@ The "Symbol" dropdown provides a lot of locale-specific variants of the same cur
 
 The PhpSpreadsheet Currency "Wizard" allows you to specify the currency code, number of decimals, and the use of a thousands separator.
 In addition, optionally, you can also specify whether the currency symbol should be leading or trailing, and whether it should be separated from the value or not.
+Finally, you have a choice of 4 ways of specifying negative values - minus sign, minus sign with the field in red, parentheses, and parentheses with the field in red.
 
 ```php
 use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Currency;
@@ -302,9 +304,6 @@ var_dump($worksheet->getCell('C21')->getFormattedValue()); // -12,345.68 €
 If we use the locale in the "Wizard", then a typical mask might look like '#,##0.00 [$€-de-DE]', with the currency wrapped in braces, a `$` to indicate that this is a localised value, and the locale included.
  > Note: The Wizard does not accept LCIDs.
 
-PhpSpreadsheet's "Wizard" doesn't yet offer options for displaying negative values; they will simply be masked so that they always display the sign.
-But alternative masking for negative values is an option that may be added in the future.
-
 ### Accounting
 
 Excel's Accounting "Wizard" is like the Currency "Wizard", but without the options for presenting negative values.
@@ -340,7 +339,6 @@ var_dump($worksheet->getCell('C20')->getFormattedValue()); //  -12,345.68 €
 ```
 A typical Accounting mask might look something like '_-#,##0.00 €*_-', with the currency symbol as a literal; and with placement indicators like `_-`, that ensure the alignment of the currency symbols and decimal points of numbers in a column.
 
-At the moment, none of the PhpSpreadsheet Wizards provide different masks for zero and negative values; unless you have the PHP `Intl` extension enabled, and can use the locale to generate the Mask.
 As with using a locale with the Currency "Wizard", when you use a locale with the Accounting "Wizard" the locale value must be valid, and any additional options will be ignored.
 ```php
 use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Accounting;
@@ -391,8 +389,6 @@ I've written in detail about Date Format Masks elsewhere in "The Dating Game"; b
 | yyyy  | Year (4 digits)                     | 2023                                  |
 
 
-There is currently no PhpSpreadsheet "Wizard" for Date Masks; but this will be introduced in the 1.29.0 release.
-
 ### Time
 
 As with Dates, when you use the Excel Time "Wizard", you can select a locale and you'll then be presented with a number of time format options that are appropriate for that locale.
@@ -411,7 +407,7 @@ I've written in detail about Time Format Masks elsewhere in "The Dating Game"; b
 | ss     | Seconds with a leading zero                                        | 00-59       |
 | AM/PM  | Periods of the day <br/>(if omitted, 24-hour time format is used)  | AM or PM    |
 
-Excel also supports Masks for Time Durations, although there is no "Wizard" for this; but the following Mask codes can be used to display Durations.
+Excel also supports Masks for Time Durations (note that spreadsheets using the 1904 base date can display negative durations, but those using the 1900 base date cannot). There is no "Wizard" for this; but the following Mask codes can be used to display Durations.
 
 | Code    | Description                                                    | Displays as |
 |---------|----------------------------------------------------------------|-------------|
@@ -422,8 +418,6 @@ Excel also supports Masks for Time Durations, although there is no "Wizard" for
 | [s]     | Elapsed time in seconds                                        |             |
 | [ss]    | Elapsed time in seconds<br>with a leading zero if less than 10 |             |
 
-There is currently no PhpSpreadsheet "Wizard" for Time Masks, or for Durations; but these will be introduced in the 1.29.0 release.
-
 ### Percentage
 
 This is among the simplest of the Excel "Wizards", only allowing you to specify the number of decimals to be displayed.

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

@@ -19,10 +19,6 @@ final class Locale
 
     public function __construct(?string $locale, int $style)
     {
-        if (class_exists(NumberFormatter::class) === false) {
-            throw new Exception();
-        }
-
         $formatterLocale = str_replace('-', '_', $locale ?? '');
         $this->formatter = new NumberFormatter($formatterLocale, $style);
         if ($this->formatter->getLocale() !== $formatterLocale) {

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

@@ -11,11 +11,13 @@
 use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Currency;
 use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\CurrencyNegative;
 use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Number;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
+use ReflectionMethod;
 
 class AccountingTest extends TestCase
 {
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerAccounting')]
+    #[DataProvider('providerAccounting')]
     public function testAccounting(
         string $expectedResultPositive,
         string $expectedResultNegative,
@@ -45,7 +47,7 @@ public static function providerAccounting(): array
         ];
     }
 
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerAccountingLocale')]
+    #[DataProvider('providerAccountingLocale')]
     public function testAccountingLocale(
         string $expectedResult,
         string $currencyCode,
@@ -105,7 +107,7 @@ public function testIcu721(): void
         }
     }
 
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerAccountingLocaleNoDecimals')]
+    #[DataProvider('providerAccountingLocaleNoDecimals')]
     public function testAccountingLocaleNoDecimals(
         string $expectedResult,
         string $currencyCode,
@@ -170,4 +172,12 @@ public function testAccountingLocaleInvalidCode(): void
         $wizard = new Accounting('€');
         $wizard->setLocale($locale);
     }
+
+    public function testLocaleNull2(): void
+    {
+        $wizard = new Accounting('$', 2);
+        $reflectionMethod = new ReflectionMethod($wizard, 'formatCurrencyCode');
+        $result = $reflectionMethod->invokeArgs($wizard, []);
+        self::assertSame('$*', $result);
+    }
 }

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

@@ -11,11 +11,13 @@
 use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Currency;
 use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\CurrencyNegative;
 use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Number;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
+use ReflectionMethod;
 
 class CurrencyTest extends TestCase
 {
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerCurrency')]
+    #[DataProvider('providerCurrency')]
     public function testCurrency(
         string $expectedResultPositive,
         string $expectedResultNegative,
@@ -43,10 +45,25 @@ public static function providerCurrency(): array
             [' 1,234.56€ ', ' -1,234.56€ ', ' 0.00€ ', '€', 2, Number::WITH_THOUSANDS_SEPARATOR, Currency::TRAILING_SYMBOL, Currency::SYMBOL_WITH_SPACING],
             [' 1234.56€ ', ' -1234.56€ ', ' 0.00€ ', '€', 2, Number::WITHOUT_THOUSANDS_SEPARATOR, Currency::TRAILING_SYMBOL, Currency::SYMBOL_WITHOUT_SPACING],
             [' 1234.56€ ', ' (1234.56)€ ', ' 0.00€ ', '€', 2, Number::WITHOUT_THOUSANDS_SEPARATOR, Currency::TRAILING_SYMBOL, Currency::SYMBOL_WITHOUT_SPACING, CurrencyNegative::parentheses],
+            [' 1234.56 GBP ', ' (1234.56) GBP ', '  0.00GBP ', 'GBP', 2, Number::WITHOUT_THOUSANDS_SEPARATOR, Currency::TRAILING_SYMBOL, Currency::SYMBOL_WITHOUT_SPACING, CurrencyNegative::parentheses],
         ];
     }
 
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerCurrencyLocale')]
+    public function testSetNegative(): void
+    {
+        $expectedResultNegative = ' (1234.56)€ ';
+        $currencyCode = '€';
+        $decimals = 2;
+        $thousandsSeparator = Number::WITHOUT_THOUSANDS_SEPARATOR;
+        $currencySymbolPosition = Currency::TRAILING_SYMBOL;
+        $currencySymbolSpacing = Currency::SYMBOL_WITHOUT_SPACING;
+        $negative = CurrencyNegative::parentheses;
+        $wizard = new Currency($currencyCode, $decimals, $thousandsSeparator, $currencySymbolPosition, $currencySymbolSpacing);
+        $wizard->setNegative($negative);
+        self::assertSame($expectedResultNegative, Formatter::toFormattedString(-1234.56, $wizard->format()));
+    }
+
+    #[DataProvider('providerCurrencyLocale')]
     public function testCurrencyLocale(
         string $expectedResult,
         string $currencyCode,
@@ -106,7 +123,7 @@ public function testIcu721(): void
         }
     }
 
-    #[\PHPUnit\Framework\Attributes\DataProvider('providerCurrencyLocaleNoDecimals')]
+    #[DataProvider('providerCurrencyLocaleNoDecimals')]
     public function testCurrencyLocaleNoDecimals(
         string $expectedResult,
         string $currencyCode,
@@ -171,4 +188,12 @@ public function testCurrencyLocaleInvalidCode(): void
         $wizard = new Currency('€');
         $wizard->setLocale($locale);
     }
+
+    public function testLocaleNull3(): void
+    {
+        $wizard = new Currency('$', 2);
+        $reflectionMethod = new ReflectionMethod($wizard, 'formatCurrencyCode');
+        $result = $reflectionMethod->invokeArgs($wizard, []);
+        self::assertSame('$', $result);
+    }
 }

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

@@ -6,6 +6,7 @@
 
 use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\Duration;
 use PHPUnit\Framework\TestCase;
+use ReflectionMethod;
 
 class DurationTest extends TestCase
 {
@@ -33,4 +34,12 @@ public static function providerTime(): array
             ['[h]:mm:ss'],
         ];
     }
+
+    public function testOddCase(): void
+    {
+        $wizard = new Duration(null, Duration::HOURS_DURATION, Duration::MINUTES_LONG, Duration::SECONDS_LONG);
+        $reflectionMethod = new ReflectionMethod($wizard, 'mapFormatBlocks');
+        $result = $reflectionMethod->invokeArgs($wizard, ['%%%']);
+        self::assertSame('"%%%"', $result);
+    }
 }

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

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpOffice\PhpSpreadsheetTests\Style\NumberFormat\Wizard;
+
+use PhpOffice\PhpSpreadsheet\Style\NumberFormat\Wizard\NumberBase;
+
+class NumberBase2 extends NumberBase
+{
+    protected function getLocaleFormat(): string
+    {
+        return 'none';
+    }
+}

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

@@ -65,4 +65,10 @@ public function testNumberLocaleInvalidFormat(): void
         $wizard = new Number(2);
         $wizard->setLocale($locale);
     }
+
+    public function testNonOverriddenFormat(): void
+    {
+        $wizard = new NumberBase2();
+        self::assertSame('General', $wizard->format());
+    }
 }

tests/bootstrap.php

@@ -3,6 +3,7 @@
 declare(strict_types=1);
 
 setlocale(LC_ALL, 'en_US.utf8');
+ini_set('error_reporting', (string) E_ALL);
 
 function phpunit10ErrorHandler(int $errno, string $errstr, string $filename, int $lineno): bool
 {