Automate Function-by-Name and Function-by-Category Docs

Examining whether it is possible to analyze the 2 Php scripts in the bin directory even though they lack a .php extension, I found that the docs generated by `generate-document` had not been updated in over a year even though support for a number of functions (e.g. ARRAYTOTEXT) had long ago been implemented. The files generated by the other script `generate-locales` are automatically generated as part of the unit test suite, and I can't see any reason not to do the same for `generate-document`.

It isn't totally clear that the 2 scripts in bin are needed any more now that each has an equivalent in the unit test suite. For now, I'm keeping them, and allowing them to be analyzed by phpcs, php-cs-fixer, and phpstan.

.php-cs-fixer.dist.php

@@ -3,6 +3,7 @@
 $finder = PhpCsFixer\Finder::create()
     ->exclude('vendor')
     ->notPath('src/PhpSpreadsheet/Writer/ZipStream3.php')
+    ->name('/(\.php|^generate-document|^generate-locales)$/')
     ->in(__DIR__);
 
 $config = new PhpCsFixer\Config();

.phpcs.xml.dist

@@ -6,6 +6,8 @@
     <file>src</file>
     <file>tests</file>
     <file>infra</file>
+    <file>bin/generate-document</file>
+    <file>bin/generate-locales</file>
 
     <exclude-pattern>samples/Header.php</exclude-pattern>
     <exclude-pattern>*/tests/Core/*/*Test\.(inc|css|js)$</exclude-pattern>

bin/generate-document

@@ -13,10 +13,12 @@ try {
     $phpSpreadsheetFunctions = $phpSpreadsheetFunctionsProperty->getValue();
     ksort($phpSpreadsheetFunctions);
 
-    file_put_contents(__DIR__ . '/../docs/references/function-list-by-category.md',
+    file_put_contents(
+        __DIR__ . '/../docs/references/function-list-by-category.md',
         DocumentGenerator::generateFunctionListByCategory($phpSpreadsheetFunctions)
     );
-    file_put_contents(__DIR__ . '/../docs/references/function-list-by-name.md',
+    file_put_contents(
+        __DIR__ . '/../docs/references/function-list-by-name.md',
         DocumentGenerator::generateFunctionListByName($phpSpreadsheetFunctions)
     );
 } catch (ReflectionException $e) {

bin/generate-locales

@@ -13,7 +13,7 @@ try {
     $phpSpreadsheetFunctions = $phpSpreadsheetFunctionsProperty->getValue();
 
     $localeGenerator = new LocaleGenerator(
-        realpath(__DIR__ . '/../src/PhpSpreadsheet/Calculation/locale/'),
+        (string) realpath(__DIR__ . '/../src/PhpSpreadsheet/Calculation/locale/'),
         'Translations.xlsx',
         $phpSpreadsheetFunctions,
         true

docs/references/function-list-by-category.md

@@ -200,6 +200,7 @@ ISNA                     | \PhpOffice\PhpSpreadsheet\Calculation\Information\Err
 ISNONTEXT                | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isNonText
 ISNUMBER                 | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isNumber
 ISODD                    | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isOdd
+ISOMITTED                | **Not yet Implemented**
 ISREF                    | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isRef
 ISTEXT                   | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isText
 N                        | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::asNumber
@@ -213,13 +214,21 @@ TYPE                     | \PhpOffice\PhpSpreadsheet\Calculation\Information\Val
 Excel Function           | PhpSpreadsheet Function
 -------------------------|--------------------------------------
 AND                      | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Operations::logicalAnd
+BYCOL                    | **Not yet Implemented**
+BYROW                    | **Not yet Implemented**
 FALSE                    | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Boolean::FALSE
 IF                       | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Conditional::statementIf
 IFERROR                  | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Conditional::IFERROR
 IFNA                     | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Conditional::IFNA
 IFS                      | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Conditional::IFS
+LAMBDA                   | **Not yet Implemented**
+LET                      | **Not yet Implemented**
+MAKEARRAY                | **Not yet Implemented**
+MAP                      | **Not yet Implemented**
 NOT                      | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Operations::NOT
 OR                       | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Operations::logicalOr
+REDUCE                   | **Not yet Implemented**
+SCAN                     | **Not yet Implemented**
 SWITCH                   | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Conditional::statementSwitch
 TRUE                     | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Boolean::TRUE
 XOR                      | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Operations::logicalXor
@@ -513,7 +522,7 @@ ZTEST                    | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Dis
 
 Excel Function           | PhpSpreadsheet Function
 -------------------------|--------------------------------------
-ARRAYTOTEXT              | **Not yet Implemented**
+ARRAYTOTEXT              | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::fromArray
 ASC                      | **Not yet Implemented**
 BAHTTEXT                 | **Not yet Implemented**
 CHAR                     | \PhpOffice\PhpSpreadsheet\Calculation\TextData\CharacterConvert::character
@@ -550,10 +559,10 @@ SEARCHB                  | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Search
 SUBSTITUTE               | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Replace::substitute
 T                        | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::test
 TEXT                     | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Format::TEXTFORMAT
-TEXTAFTER                | **Not yet Implemented**
-TEXTBEFORE               | **Not yet Implemented**
+TEXTAFTER                | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Extract::after
+TEXTBEFORE               | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Extract::before
 TEXTJOIN                 | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Concatenate::TEXTJOIN
-TEXTSPLIT                | **Not yet Implemented**
+TEXTSPLIT                | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::split
 THAIDIGIT                | **Not yet Implemented**
 THAINUMSOUND             | **Not yet Implemented**
 THAINUMSTRING            | **Not yet Implemented**
@@ -563,7 +572,7 @@ UNICHAR                  | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Charac
 UNICODE                  | \PhpOffice\PhpSpreadsheet\Calculation\TextData\CharacterConvert::code
 UPPER                    | \PhpOffice\PhpSpreadsheet\Calculation\TextData\CaseConvert::upper
 VALUE                    | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Format::VALUE
-VALUETOTEXT              | **Not yet Implemented**
+VALUETOTEXT              | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Format::valueToText
 
 ## CATEGORY_WEB
 
@@ -572,3 +581,10 @@ Excel Function           | PhpSpreadsheet Function
 ENCODEURL                | \PhpOffice\PhpSpreadsheet\Calculation\Web\Service::urlEncode
 FILTERXML                | **Not yet Implemented**
 WEBSERVICE               | \PhpOffice\PhpSpreadsheet\Calculation\Web\Service::webService
+
+## CATEGORY_UNCATEGORISED
+
+Excel Function           | PhpSpreadsheet Function
+-------------------------|--------------------------------------
+ANCHORARRAY              | **Not yet Implemented**
+SINGLE                   | **Not yet Implemented**

docs/references/function-list-by-name.md

@@ -15,10 +15,11 @@ ADDRESS                  | CATEGORY_LOOKUP_AND_REFERENCE  | \PhpOffice\PhpSpread
 AGGREGATE                | CATEGORY_MATH_AND_TRIG         | **Not yet Implemented**
 AMORDEGRC                | CATEGORY_FINANCIAL             | \PhpOffice\PhpSpreadsheet\Calculation\Financial\Amortization::AMORDEGRC
 AMORLINC                 | CATEGORY_FINANCIAL             | \PhpOffice\PhpSpreadsheet\Calculation\Financial\Amortization::AMORLINC
+ANCHORARRAY              | CATEGORY_UNCATEGORISED         | **Not yet Implemented**
 AND                      | CATEGORY_LOGICAL               | \PhpOffice\PhpSpreadsheet\Calculation\Logical\Operations::logicalAnd
 ARABIC                   | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Arabic::evaluate
 AREAS                    | CATEGORY_LOOKUP_AND_REFERENCE  | **Not yet Implemented**
-ARRAYTOTEXT              | CATEGORY_TEXT_AND_DATA         | **Not yet Implemented**
+ARRAYTOTEXT              | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::fromArray
 ASC                      | CATEGORY_TEXT_AND_DATA         | **Not yet Implemented**
 ASIN                     | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Sine::asin
 ASINH                    | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Sine::asinh
@@ -57,6 +58,8 @@ BITLSHIFT                | CATEGORY_ENGINEERING           | \PhpOffice\PhpSpread
 BITOR                    | CATEGORY_ENGINEERING           | \PhpOffice\PhpSpreadsheet\Calculation\Engineering\BitWise::BITOR
 BITRSHIFT                | CATEGORY_ENGINEERING           | \PhpOffice\PhpSpreadsheet\Calculation\Engineering\BitWise::BITRSHIFT
 BITXOR                   | CATEGORY_ENGINEERING           | \PhpOffice\PhpSpreadsheet\Calculation\Engineering\BitWise::BITXOR
+BYCOL                    | CATEGORY_LOGICAL               | **Not yet Implemented**
+BYROW                    | CATEGORY_LOGICAL               | **Not yet Implemented**
 
 ## C
 
@@ -305,6 +308,7 @@ ISNONTEXT                | CATEGORY_INFORMATION           | \PhpOffice\PhpSpread
 ISNUMBER                 | CATEGORY_INFORMATION           | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isNumber
 ISO.CEILING              | CATEGORY_MATH_AND_TRIG         | **Not yet Implemented**
 ISODD                    | CATEGORY_INFORMATION           | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isOdd
+ISOMITTED                | CATEGORY_INFORMATION           | **Not yet Implemented**
 ISOWEEKNUM               | CATEGORY_DATE_AND_TIME         | \PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Week::isoWeekNumber
 ISPMT                    | CATEGORY_FINANCIAL             | \PhpOffice\PhpSpreadsheet\Calculation\Financial\CashFlow\Constant\Periodic\Interest::schedulePayment
 ISREF                    | CATEGORY_INFORMATION           | \PhpOffice\PhpSpreadsheet\Calculation\Information\Value::isRef
@@ -327,12 +331,14 @@ KURT                     | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpread
 
 Excel Function           | Category                       | PhpSpreadsheet Function
 -------------------------|--------------------------------|--------------------------------------
+LAMBDA                   | CATEGORY_LOGICAL               | **Not yet Implemented**
 LARGE                    | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Size::large
 LCM                      | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Lcm::evaluate
 LEFT                     | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Extract::left
 LEFTB                    | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Extract::left
 LEN                      | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::length
 LENB                     | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::length
+LET                      | CATEGORY_LOGICAL               | **Not yet Implemented**
 LINEST                   | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Trends::LINEST
 LN                       | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Logarithms::natural
 LOG                      | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Logarithms::withBase
@@ -349,6 +355,8 @@ LOWER                    | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpread
 
 Excel Function           | Category                       | PhpSpreadsheet Function
 -------------------------|--------------------------------|--------------------------------------
+MAKEARRAY                | CATEGORY_LOGICAL               | **Not yet Implemented**
+MAP                      | CATEGORY_LOGICAL               | **Not yet Implemented**
 MATCH                    | CATEGORY_LOOKUP_AND_REFERENCE  | \PhpOffice\PhpSpreadsheet\Calculation\LookupRef\ExcelMatch::MATCH
 MAX                      | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Maximum::max
 MAXA                     | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Maximum::maxA
@@ -468,6 +476,7 @@ RANK.AVG                 | CATEGORY_STATISTICAL           | **Not yet Implemente
 RANK.EQ                  | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Percentiles::RANK
 RATE                     | CATEGORY_FINANCIAL             | \PhpOffice\PhpSpreadsheet\Calculation\Financial\CashFlow\Constant\Periodic\Interest::rate
 RECEIVED                 | CATEGORY_FINANCIAL             | \PhpOffice\PhpSpreadsheet\Calculation\Financial\Securities\Price::received
+REDUCE                   | CATEGORY_LOGICAL               | **Not yet Implemented**
 REPLACE                  | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Replace::replace
 REPLACEB                 | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Replace::replace
 REPT                     | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Concatenate::builtinREPT
@@ -489,6 +498,7 @@ RTD                      | CATEGORY_LOOKUP_AND_REFERENCE  | **Not yet Implemente
 
 Excel Function           | Category                       | PhpSpreadsheet Function
 -------------------------|--------------------------------|--------------------------------------
+SCAN                     | CATEGORY_LOGICAL               | **Not yet Implemented**
 SEARCH                   | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Search::insensitive
 SEARCHB                  | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Search::insensitive
 SEC                      | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Secant::sec
@@ -500,6 +510,7 @@ SHEET                    | CATEGORY_INFORMATION           | **Not yet Implemente
 SHEETS                   | CATEGORY_INFORMATION           | **Not yet Implemented**
 SIGN                     | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Sign::evaluate
 SIN                      | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Sine::sin
+SINGLE                   | CATEGORY_UNCATEGORISED         | **Not yet Implemented**
 SINH                     | CATEGORY_MATH_AND_TRIG         | \PhpOffice\PhpSpreadsheet\Calculation\MathTrig\Trig\Sine::sinh
 SKEW                     | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Deviations::skew
 SKEW.P                   | CATEGORY_STATISTICAL           | **Not yet Implemented**
@@ -550,10 +561,10 @@ TBILLPRICE               | CATEGORY_FINANCIAL             | \PhpOffice\PhpSpread
 TBILLYIELD               | CATEGORY_FINANCIAL             | \PhpOffice\PhpSpreadsheet\Calculation\Financial\TreasuryBill::yield
 TDIST                    | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Distributions\StudentT::distribution
 TEXT                     | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Format::TEXTFORMAT
-TEXTAFTER                | CATEGORY_TEXT_AND_DATA         | **Not yet Implemented**
-TEXTBEFORE               | CATEGORY_TEXT_AND_DATA         | **Not yet Implemented**
+TEXTAFTER                | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Extract::after
+TEXTBEFORE               | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Extract::before
 TEXTJOIN                 | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Concatenate::TEXTJOIN
-TEXTSPLIT                | CATEGORY_TEXT_AND_DATA         | **Not yet Implemented**
+TEXTSPLIT                | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Text::split
 THAIDAYOFWEEK            | CATEGORY_DATE_AND_TIME         | **Not yet Implemented**
 THAIDIGIT                | CATEGORY_TEXT_AND_DATA         | **Not yet Implemented**
 THAIMONTHOFYEAR          | CATEGORY_DATE_AND_TIME         | **Not yet Implemented**
@@ -591,7 +602,7 @@ USDOLLAR                 | CATEGORY_FINANCIAL             | \PhpOffice\PhpSpread
 Excel Function           | Category                       | PhpSpreadsheet Function
 -------------------------|--------------------------------|--------------------------------------
 VALUE                    | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Format::VALUE
-VALUETOTEXT              | CATEGORY_TEXT_AND_DATA         | **Not yet Implemented**
+VALUETOTEXT              | CATEGORY_TEXT_AND_DATA         | \PhpOffice\PhpSpreadsheet\Calculation\TextData\Format::valueToText
 VAR                      | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Variances::VAR
 VAR.P                    | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Variances::VARP
 VAR.S                    | CATEGORY_STATISTICAL           | \PhpOffice\PhpSpreadsheet\Calculation\Statistical\Variances::VAR

phpstan.neon.dist

@@ -10,6 +10,8 @@ parameters:
         - tests/
         - samples/
         - infra/
+        - bin/generate-document
+        - bin/generate-locales
     excludePaths:
         - src/PhpSpreadsheet/Chart/Renderer/JpGraph.php
         - src/PhpSpreadsheet/Chart/Renderer/JpGraphRendererBase.php

tests/PhpSpreadsheetTests/DocumentGeneratorTest.php

@@ -4,21 +4,28 @@
 
 namespace PhpOffice\PhpSpreadsheetTests;
 
+use PhpOffice\PhpSpreadsheet\Calculation\Calculation;
 use PhpOffice\PhpSpreadsheet\Calculation\Category as Cat;
 use PhpOffice\PhpSpreadsheet\Calculation\Functions;
 use PhpOffice\PhpSpreadsheet\Calculation\Logical;
 use PhpOffice\PhpSpreadsheetInfra\DocumentGenerator;
 use PHPUnit\Framework\TestCase;
+use ReflectionClass;
 use UnexpectedValueException;
 
 class DocumentGeneratorTest extends TestCase
 {
+    private static bool $succeededByName = false;
+
+    private static bool $succeededByCategory = false;
+
     /**
      * @dataProvider providerGenerateFunctionListByName
      */
     public function testGenerateFunctionListByName(array $phpSpreadsheetFunctions, string $expected): void
     {
         self::assertEquals($expected, DocumentGenerator::generateFunctionListByName($phpSpreadsheetFunctions));
+        self::$succeededByName = true;
     }
 
     /**
@@ -27,6 +34,7 @@ public function testGenerateFunctionListByName(array $phpSpreadsheetFunctions, s
     public function testGenerateFunctionListByCategory(array $phpSpreadsheetFunctions, string $expected): void
     {
         self::assertEquals($expected, DocumentGenerator::generateFunctionListByCategory($phpSpreadsheetFunctions));
+        self::$succeededByCategory = true;
     }
 
     public static function providerGenerateFunctionListByName(): array
@@ -154,4 +162,27 @@ public function testGenerateFunctionBadArray(): void
         ];
         DocumentGenerator::generateFunctionListByName($phpSpreadsheetFunctions);
     }
+
+    public function testGenerateDocuments(): void
+    {
+        if (!self::$succeededByName || !self::$succeededByCategory) {
+            self::markTestSkipped('Not run because prior test failed');
+        }
+        $directory = 'docs/references/';
+        self::assertNotEmpty($directory);
+        $phpSpreadsheetFunctionsProperty = (new ReflectionClass(Calculation::class))
+            ->getProperty('phpSpreadsheetFunctions');
+        $phpSpreadsheetFunctionsProperty->setAccessible(true);
+        $phpSpreadsheetFunctions = $phpSpreadsheetFunctionsProperty->getValue();
+        ksort($phpSpreadsheetFunctions);
+
+        self::assertNotFalse(file_put_contents(
+            $directory . 'function-list-by-category.md',
+            DocumentGenerator::generateFunctionListByCategory($phpSpreadsheetFunctions)
+        ));
+        self::assertNotFalse(file_put_contents(
+            $directory . 'function-list-by-name.md',
+            DocumentGenerator::generateFunctionListByName($phpSpreadsheetFunctions)
+        ));
+    }
 }