Merge pull request #4717 from oleibman/explicit

Prepare to Deprecate Optionality of Second Arg to Cell::setValueExplicit

Author: oleibman

CHANGELOG.md

@@ -28,7 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org). Thia is a
 
 ### Deprecated
 
-- Nothing yet.
+- $dataType, the second parameter of Cell::setValueExplicit, is currently optional. Omitting it is deprecated, and it will be required in a future release.
 
 ### Fixed
 

src/PhpSpreadsheet/Cell/Cell.php

@@ -247,6 +247,8 @@ public function setValue(mixed $value, ?IValueBinder $binder = null): self
      *
      * @param mixed $value Value
      * @param string $dataType Explicit data type, see DataType::TYPE_*
+     *        This parameter is currently optional (default = string).
+     *        Omitting it is ***DEPRECATED***, and the default will be removed in a future release.
      *        Note that PhpSpreadsheet does not validate that the value and datatype are consistent, in using this
      *             method, then it is your responsibility as an end-user developer to validate that the value and
      *             the datatype match.

tests/PhpSpreadsheetTests/Cell/SetValueExplicitCellTest.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpOffice\PhpSpreadsheetTests\Cell;
+
+use ArgumentCountError;
+use PhpOffice\PhpSpreadsheet\Cell\Cell;
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+use ReflectionMethod;
+
+class SetValueExplicitCellTest extends TestCase
+{
+    protected string $method = 'setValueExplicit';
+
+    protected int $requiredParameters = 1;
+
+    public function testRequired(): void
+    {
+        $reflectionMethod = new ReflectionMethod(Cell::class, $this->method);
+        $requiredParameters = $reflectionMethod->getNumberOfRequiredParameters();
+        self::assertSame($this->requiredParameters, $requiredParameters);
+    }
+
+    public static function setValueExplicitTypeArgumentProvider(): array
+    {
+        return require 'tests/data/Cell/SetValueExplicitTypeArguments.php';
+    }
+
+    #[DataProvider('setValueExplicitTypeArgumentProvider')]
+    public function testSetValueExplicitTypeArgumentHandling(
+        mixed $value,
+        ?string $dataType,
+        mixed $expectedValue,
+        string $expectedDataType
+    ): void {
+        $spreadsheet = new Spreadsheet();
+        $worksheet = $spreadsheet->getActiveSheet();
+        $coordinate = 'A1';
+        $cell = $worksheet->getCell($coordinate);
+
+        try {
+            if ($dataType !== null) {
+                $cell->{$this->method}($value, $dataType);
+            } else {
+                $cell->{$this->method}($value);
+                self::assertSame(1, $this->requiredParameters);
+            }
+            self::assertSame($expectedValue, $cell->getValue());
+            self::assertSame($expectedDataType, $cell->getDataType());
+        } catch (ArgumentCountError) {
+            self::assertSame(2, $this->requiredParameters);
+            self::assertNull($dataType);
+        }
+
+        $spreadsheet->disconnectWorksheets();
+    }
+}

tests/PhpSpreadsheetTests/Worksheet/SetValueExplicitWorksheetTest.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpOffice\PhpSpreadsheetTests\Worksheet;
+
+use ArgumentCountError;
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+use PhpOffice\PhpSpreadsheet\Worksheet\Worksheet;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+use ReflectionMethod;
+
+class SetValueExplicitWorksheetTest extends TestCase
+{
+    protected string $method = 'setCellValueExplicit';
+
+    protected int $requiredParameters = 3;
+
+    public function testRequired(): void
+    {
+        $reflectionMethod = new ReflectionMethod(Worksheet::class, $this->method);
+        $requiredParameters = $reflectionMethod->getNumberOfRequiredParameters();
+        self::assertSame($this->requiredParameters, $requiredParameters);
+    }
+
+    public static function setCellValueExplicitTypeArgumentProvider(): array
+    {
+        return require 'tests/data/Cell/SetValueExplicitTypeArguments.php';
+    }
+
+    #[DataProvider('setCellValueExplicitTypeArgumentProvider')]
+    public function testSetCellValueExplicitTypeArgumentHandling(
+        mixed $value,
+        ?string $dataType,
+        mixed $expectedValue,
+        string $expectedDataType
+    ): void {
+        $spreadsheet = new Spreadsheet();
+        $worksheet = $spreadsheet->getActiveSheet();
+        $coordinate = 'A1';
+        $cell = $worksheet->getCell($coordinate);
+
+        try {
+            if ($dataType) {
+                $worksheet->{$this->method}($coordinate, $value, $dataType);
+            } else {
+                $worksheet->{$this->method}($coordinate, $value);
+                self::assertSame(2, $this->requiredParameters);
+            }
+            self::assertSame($expectedValue, $cell->getValue());
+            self::assertSame($expectedDataType, $cell->getDataType());
+        } catch (ArgumentCountError) {
+            self::assertSame(3, $this->requiredParameters);
+            self::assertNull($dataType);
+        }
+
+        $spreadsheet->disconnectWorksheets();
+    }
+}

tests/data/Cell/SetValueExplicitTypeArguments.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpOffice\PhpSpreadsheet\Cell\DataType;
+
+// This member will be used to validate both:
+// Cell::setValueExplicit
+// Worksheet::setCellValueExplicit
+
+return [
+    'string with default type' => ['default string', null, 'default string', DataType::TYPE_STRING],
+    'integer with default type' => [42, null, '42', DataType::TYPE_STRING],
+    'string with string' => ['explicit string', DataType::TYPE_STRING, 'explicit string', DataType::TYPE_STRING],
+    'integer with string type' => [123, DataType::TYPE_STRING, '123', DataType::TYPE_STRING],
+    'numeric string with string type' => ['496', DataType::TYPE_STRING, '496', DataType::TYPE_STRING],
+    'integer with numeric type' => [591, DataType::TYPE_NUMERIC, 591, DataType::TYPE_NUMERIC],
+    'numeric string with numeric type' => ['1887', DataType::TYPE_NUMERIC, 1887, DataType::TYPE_NUMERIC],
+    'true with bool type' => [true, DataType::TYPE_BOOL, true, DataType::TYPE_BOOL],
+    'false with bool type' => [false, DataType::TYPE_BOOL, false, DataType::TYPE_BOOL],
+];