Update docblock documentation for setting cell values explicit to indicate that value/datatype matching is the responsibility of the end-user developer making this call; and that values may be changed to reflect the specified datatype.

No doubt some developers will complain that it should be the other way round, that datatpe should be modified to match the specified value; but then they should be using setValue() instead; the use of setValueExplicit() is explicit.

Author: MarkBaker

CHANGELOG.md

@@ -21,6 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Changed
 
+- Better enforcement of value modification to match specified datatype when using setValueExplicit() 
+- Relax validation of merge cells to allow merge for a single cell reference [Issue #2776](https://github.com/PHPOffice/PhpSpreadsheet/issues/2776)
 - Memory and speed improvements, particularly for the Cell Collection, and the Writers.
 
   See [the Discussion section on github](https://github.com/PHPOffice/PhpSpreadsheet/discussions/2821) for details of performance across versions

src/PhpSpreadsheet/Cell/Cell.php

@@ -202,6 +202,11 @@ public function setValue($value)
      *
      * @param mixed $value Value
      * @param string $dataType Explicit data type, see DataType::TYPE_*
+     *        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.
+     *       If you do mismatch value and datatpe, then the value you enter may be changed to match the datatype
+     *          that you specify.
      *
      * @return Cell
      */
@@ -210,7 +215,7 @@ public function setValueExplicit($value, $dataType)
         // set the value according to data type
         switch ($dataType) {
             case DataType::TYPE_NULL:
-                $this->value = $value;
+                $this->value = null;
 
                 break;
             case DataType::TYPE_STRING2:

src/PhpSpreadsheet/Cell/DataType.php

@@ -48,7 +48,7 @@ public static function getErrorCodes()
      *
      * @param null|RichText|string $textValue Value to sanitize to an Excel string
      *
-     * @return null|RichText|string Sanitized value
+     * @return RichText|string Sanitized value
      */
     public static function checkString($textValue)
     {
@@ -58,7 +58,7 @@ public static function checkString($textValue)
         }
 
         // string must never be longer than 32,767 characters, truncate if necessary
-        $textValue = StringHelper::substring($textValue, 0, 32767);
+        $textValue = StringHelper::substring((string) $textValue, 0, 32767);
 
         // we require that newline is represented as "\n" in core, not as "\r\n" or "\r"
         $textValue = str_replace(["\r\n", "\r"], "\n", $textValue);

src/PhpSpreadsheet/Worksheet/Worksheet.php

@@ -1177,6 +1177,11 @@ public function setCellValueByColumnAndRow($columnIndex, $row, $value)
      *               or as an array of [$columnIndex, $row] (e.g. [3, 5]), or a CellAddress object.
      * @param mixed $value Value of the cell
      * @param string $dataType Explicit data type, see DataType::TYPE_*
+     *        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.
+     *       If you do mismatch value and datatpe, then the value you enter may be changed to match the datatype
+     *          that you specify.
      *
      * @return $this
      */
@@ -1199,6 +1204,11 @@ public function setCellValueExplicit($coordinate, $value, $dataType)
      * @param int $row Numeric row coordinate of the cell
      * @param mixed $value Value of the cell
      * @param string $dataType Explicit data type, see DataType::TYPE_*
+     *        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.
+     *       If you do mismatch value and datatpe, then the value you enter may be changed to match the datatype
+     *          that you specify.
      *
      * @return $this
      */
@@ -1770,6 +1780,10 @@ public function mergeCells($range)
         $numberRows = $lastRow - $firstRow;
         $numberColumns = $lastColumnIndex - $firstColumnIndex;
 
+        if ($numberRows === 1 && $numberColumns === 1) {
+            return $this;
+        }
+
         // create upper left cell if it does not already exist
         $upperLeft = "{$firstColumn}{$firstRow}";
         if (!$this->cellExists($upperLeft)) {