Merge branch 'master' into issue4522

Author: oleibman

CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Added
 
-- Nothing yet.
+- Address Excel Inappropriate Number Format Substitution. [PR #4532](https://github.com/PHPOffice/PhpSpreadsheet/pull/4532)
 
 ### Removed
 
@@ -29,7 +29,13 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Fixed
 
-- Nothing yet.
+- Writer Html/Pdf support RTL alignment of tables. [Issue #1104](https://github.com/PHPOffice/PhpSpreadsheet/issues/1104) [PR #4535](https://github.com/PHPOffice/PhpSpreadsheet/pull/4535)
+- Xlsx Reader use dynamic arrays if spreadsheet did so. [PR #4533](https://github.com/PHPOffice/PhpSpreadsheet/pull/4533)
+- Ods Reader Nested table-row. [Issue #4528](https://github.com/PHPOffice/PhpSpreadsheet/issues/4528) [Issue #2507](https://github.com/PHPOffice/PhpSpreadsheet/issues/2507) [PR #4531](https://github.com/PHPOffice/PhpSpreadsheet/pull/4531)
+- Recognize application/x-empty mimetype. [Issue #4521](https://github.com/PHPOffice/PhpSpreadsheet/issues/4521) [PR #4524](https://github.com/PHPOffice/PhpSpreadsheet/pull/4524)
+- Micro-optimization in getSheetByName. [PR #4499](https://github.com/PHPOffice/PhpSpreadsheet/pull/4499)
+- Bug in resizeMatricesExtend. [Issue #4451](https://github.com/PHPOffice/PhpSpreadsheet/issues/4451) [PR #4474](https://github.com/PHPOffice/PhpSpreadsheet/pull/4474)
+- Preserve 0x0a in Strings if Desired. [Issue #347](https://github.com/PHPOffice/PhpSpreadsheet/issues/347) [PR #4536](https://github.com/PHPOffice/PhpSpreadsheet/pull/4536)
 
 ## 2025-06-22 - 4.4.0
 

composer.lock

@@ -0,0 +1,46 @@
+# Excel Anomalies
+
+This is documentation for some behavior in Excel itself which we
+just do not understand, or which may come as a surprise to the user.
+
+## Date Number Format
+
+My system short date format is set to `yyyy-mm-dd`. Excel, for a very long time, did not include that amongst its formatting choices for dates, so it needed to be added as a custom format - no big deal. It has recently been added to the list of date formats, but ...
+
+I used Excel to create a spreadsheet, and included some dates, specifying `yyyy-mm-dd` formatting. When I looked at the resulting spreadsheet, I was surprised to see that Excel had stored the style not as `yyyy-mm-dd`, but rather as builtin style 14 (system short date format). Apparently the fact that the Excel styling matched my system choice was sufficient for it to override my choice! This is an astonishingly user-hostile implementation. Even though there are formats which, by design, "respond to changes in regional date and time settings", and even though the format I selected was not among those, Excel decided it was appropriate to vary the display even when I said I wanted an unvarying format. I assume, but have not confirmed, that this applies to formats other than `yyyy-mm-dd`.
+
+Note that this is not a problem when using PhpSpreadsheet to set the style, only when you let Excel do it. And, in that case, after a little experimentation, I figured out a format that Excel doesn't sabotage `[Black]yyyy-mm-dd`.
+
+If you have a spreadsheet that has been altered in this way, it can be fixed with the following PhpSpreadsheet code:
+```php
+        foreach ($spreadsheet->getCellXfCollection() as $style) {
+            $numberFormat = $style->getNumberFormat();
+            // okay to use NumberFormat::SHORT_DATE_INDEX below
+            if ($numberFormat->getBuiltInFormatCode() === 14) {
+                $numberFormat->setFormatCode('yyyy-mm-dd');
+            }
+        }
+```
+Starting with PhpSpreadsheet 4.5.0, this can be simplified to:
+```php
+        $spreadsheet->replaceBuiltinNumberFormat(
+            \PhpOffice\PhpSpreadsheet\Style\NumberFormat::SHORT_DATE_INDEX,
+            'yyyy-mm-dd'
+        );
+```
+
+## Negative Time Intervals
+
+You have a time in one cell, and a time in another, and you want to subtract and display the result in `h:mm` format. No problem if the result is positive. But, if it's negative, Excel just fills the cell with `#`. There is a solution of sorts. If you use a 1904 base date (default on Mac), the negative interval will work just fine. Alas, no dice if you use a 1900 base data (default on Windows). No idea why they can't fix that - the existing implementation can't really be something that anybody actually wants. Note that it is *not* safe to change the base date for an existing spreadsheet, so, if this is something you want to do, make sure you change the base date before populating any data.
+
+## Long-ago Dates
+
+Excel does not support dates before either 1900-01-01 (Windows default) or 1904-01-01 (Mac default). For the 1900 base year, there is the additional problem that non-existent date 1900-02-29 is squeezed between 1900-02-28 and 1900-03-01.
+
+## Weird Fractions
+
+Similar fraction formats have inconsistent results in Excel. For example, if a cell contains the value 1 and the cell's format is `0 0/0`, it will display as `1 0/1`. But, if the cell's format is `? ??/???`, it will display as `1`. See [this issue](https://github.com/PHPOffice/PhpSpreadsheet/issues/3625), which remains open because, in the absence of usable documentation, we aren't sure how to handle things.
+
+## COUNTIF and Text Cells
+
+In Excel, COUNTIF appears to ignore text cells, behavior which doesn't seem to be documented anywhere. See [this issue](https://github.com/PHPOffice/PhpSpreadsheet/issues/3802), which remains open because, in the absence of usable documentation, we aren't sure how to handle things.

docs/topics/Excel Anomalies.md

@@ -14,20 +14,20 @@ Open/Libre Office and Gnumeric don't have this limitation, and negative date/tim
 To write a date in a cell using PhpSpreadsheet, we need to calculate the serialized Excel datestamp for that date. Methods to do this are available in the Shared\Date class, which provides a number of methods for conversion between different date options typically used in PHP applications (Unix timestamp, PHP DateTime objects and some recognisable formatted strings) and the Excel serialized value; and vice versa.
 
  - Shared\Date::convertIsoDate()
-   - Converts a date/time in [ISO-8601 standard format](https://en.wikipedia.org/wiki/ISO_8601) to an Excel serialized timestamp
+     - Converts a date/time in [ISO-8601 standard format](https://en.wikipedia.org/wiki/ISO_8601) to an Excel serialized timestamp
  - Shared\Date::PHPToExcel()
-   - Converts a Unix timestamp, a PHP DateTime object, or a recognisable formatted string to an Excel serialized timestamp
+     - Converts a Unix timestamp, a PHP DateTime object, or a recognisable formatted string to an Excel serialized timestamp
  - Shared\Date::dateTimeToExcel()
-   - Converts a Unix timestamp to an Excel serialized timestamp
+     - Converts a Unix timestamp to an Excel serialized timestamp
  - Shared\Date::timestampToExcel()
-   - Converts a PHP DateTime object to an Excel serialized timestamp
+     - Converts a PHP DateTime object to an Excel serialized timestamp
  - Shared\Date::formattedPHPToExcel()
-   - Converts year, month, day, hour, minute, and second to an Excel serialized timestamp
+     - Converts year, month, day, hour, minute, and second to an Excel serialized timestamp
  - Shared\Date::excelToDateTimeObject()
-   - Converts an Excel serialized timestamp to a PHP DateTime object
+     - Converts an Excel serialized timestamp to a PHP DateTime object
  - Shared\Date::excelToTimestamp()
-   - Converts an Excel serialized timestamp to a Unix timestamp.
-   - The use of Unix timestamps, and therefore this function, is discouraged: they are not Y2038-safe on a 32-bit system, and have no timezone info.
+     - Converts an Excel serialized timestamp to a Unix timestamp.
+     - The use of Unix timestamps, and therefore this function, is discouraged: they are not Y2038-safe on a 32-bit system, and have no timezone info.
 
 We probably also want to set the number format mask for the cell so that it will be displayed as a human-readable date.
 ```php
@@ -184,7 +184,7 @@ MS Excel allows any separator character between hours/minutes/seconds; PhpSpread
 
 ### Duration (Elapsed Time)
 
-Excel also supports formatting a value as a duration; a total number of hours, minutes or seconds rather than a time of day.
+Excel also supports formatting a value as a duration; a total number of hours, minutes or seconds rather than a time of day. However, please note that negative durations are supported only if using base year 1904 (Mac default).
 
 | Code    | Description                                                    | Displays as |
 |---------|----------------------------------------------------------------|-------------|

docs/topics/The Dating Game.md

@@ -545,17 +545,18 @@ $this->spreadsheet->addDefinedName(
 ### Naming Names
 
 The names that you assign to Defined Name must follow the following set of rules:
+
  - The first character of a name must be one of the following characters:
-   - letter (including UTF-8 letters)
-   - underscore (`_`)
+     - letter (including UTF-8 letters)
+     - underscore (`_`)
  - Remaining characters in the name can be
-   - letters (including UTF-8 letters)
-   - numbers (including UTF-8 numbers)
-   - periods (`.`)
-   - underscore characters (`_`)
+     - letters (including UTF-8 letters)
+     - numbers (including UTF-8 numbers)
+     - periods (`.`)
+     - underscore characters (`_`)
  - The following are not allowed:
-   - Space characters are not allowed as part of a name.
-   - Names can't look like cell addresses, such as A35 or R2C2
+     - Space characters are not allowed as part of a name.
+     - Names can't look like cell addresses, such as A35 or R2C2
  - Names are not case sensitive. For example, `North` and `NORTH` are treated as the same name.
 
 ### Limitations

docs/topics/defined-names.md

@@ -2,12 +2,10 @@
 
 use PhpOffice\PhpSpreadsheet\Spreadsheet;
 use PhpOffice\PhpSpreadsheet\Worksheet\Drawing;
-use PhpOffice\PhpSpreadsheet\Writer\Pdf\Mpdf;
 
 require __DIR__ . '/../Header.php';
-/** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */
-require_once __DIR__ . '/Mpdf2.php';
 
+/** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */
 $spreadsheet = new Spreadsheet();
 $sheet = $spreadsheet->getActiveSheet();
 
@@ -41,11 +39,6 @@
 $spreadsheet->mergeDrawingCellsForPdf();
 
 $helper->log('Write to Mpdf');
-$writer = new Mpdf($spreadsheet);
-$filename = $helper->getFileName(__FILE__, 'pdf');
-$writer->save($filename);
-$helper->log("Saved $filename");
-if (PHP_SAPI !== 'cli') {
-    echo '<a href="/download.php?type=pdf&name=' . basename($filename) . '">Download ' . basename($filename) . '</a><br />';
-}
+$helper->write($spreadsheet, __FILE__, ['Mpdf']);
+
 $spreadsheet->disconnectWorksheets();

samples/Pdf/21f_Drawing_mpdf.php renamed to samples/Pdf/21f_Drawing.php

@@ -0,0 +1,28 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+
+require __DIR__ . '/../Header.php';
+
+/** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */
+$spreadsheet = new Spreadsheet();
+$sheet = $spreadsheet->getActiveSheet();
+
+$sheet1 = $spreadsheet->getActiveSheet();
+$sheet2 = $spreadsheet->createSheet();
+$sheet3 = $spreadsheet->createSheet();
+$cells = [
+    ['a1', 'b1', 'c1'],
+    ['a2', 'b2', 'c2'],
+];
+$sheet1->fromArray($cells);
+$sheet1->setRightToLeft(true);
+$sheet2->fromArray($cells);
+$sheet3->fromArray($cells);
+$sheet3->setRightToLeft(true);
+
+$helper->log('Write to html, mpdf, tcpdf');
+// Save
+$helper->write($spreadsheet, __FILE__, ['Html', 'Mpdf', 'Tcpdf']);
+
+$spreadsheet->disconnectWorksheets();

samples/Pdf/21g_Direction.php

@@ -0,0 +1,36 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+use PhpOffice\PhpSpreadsheet\Writer\Html as HtmlWriter;
+
+require __DIR__ . '/../Header.php';
+
+/** @var PhpOffice\PhpSpreadsheet\Helper\Sample $helper */
+$spreadsheet = new Spreadsheet();
+$sheet = $spreadsheet->getActiveSheet();
+
+$sheet1 = $spreadsheet->getActiveSheet();
+$sheet2 = $spreadsheet->createSheet();
+$sheet3 = $spreadsheet->createSheet();
+$cells = [
+    ['a1', 'b1', 'c1'],
+    ['a2', 'b2', 'c2'],
+];
+$sheet1->fromArray($cells);
+$sheet1->setRightToLeft(true);
+$sheet2->fromArray($cells);
+$sheet3->fromArray($cells);
+$sheet3->setRightToLeft(true);
+
+$helper->log('Write to html, mpdf');
+// Save
+$helper->write(
+    $spreadsheet,
+    __FILE__,
+    ['Html', 'Mpdf'],
+    writerCallback: function (HtmlWriter $writer): void {
+            $writer->writeAllSheets();
+    }
+);
+
+$spreadsheet->disconnectWorksheets();

samples/Pdf/21h_DirectionMultiple.php

@@ -852,15 +852,15 @@ private static function resizeMatricesExtend(array &$matrix1, array &$matrix2, i
             if ($matrix2Columns < $matrix1Columns) {
                 for ($i = 0; $i < $matrix2Rows; ++$i) {
                     /** @var mixed[][] $matrix2 */
-                    $x = $matrix2[$i][$matrix2Columns - 1];
+                    $x = ($matrix2Columns === 1) ? $matrix2[$i][0] : null;
                     for ($j = $matrix2Columns; $j < $matrix1Columns; ++$j) {
                         $matrix2[$i][$j] = $x;
                     }
                 }
             }
             if ($matrix2Rows < $matrix1Rows) {
-                $x = $matrix2[$matrix2Rows - 1];
-                for ($i = 0; $i < $matrix1Rows; ++$i) {
+                $x = ($matrix2Rows === 1) ? $matrix2[0] : array_fill(0, $matrix2Columns, null);
+                for ($i = $matrix2Rows; $i < $matrix1Rows; ++$i) {
                     $matrix2[$i] = $x;
                 }
             }
@@ -870,15 +870,15 @@ private static function resizeMatricesExtend(array &$matrix1, array &$matrix2, i
             if ($matrix1Columns < $matrix2Columns) {
                 for ($i = 0; $i < $matrix1Rows; ++$i) {
                     /** @var mixed[][] $matrix1 */
-                    $x = $matrix1[$i][$matrix1Columns - 1];
+                    $x = ($matrix1Columns === 1) ? $matrix1[$i][0] : null;
                     for ($j = $matrix1Columns; $j < $matrix2Columns; ++$j) {
                         $matrix1[$i][$j] = $x;
                     }
                 }
             }
             if ($matrix1Rows < $matrix2Rows) {
-                $x = $matrix1[$matrix1Rows - 1];
-                for ($i = 0; $i < $matrix2Rows; ++$i) {
+                $x = ($matrix1Rows === 1) ? $matrix1[0] : array_fill(0, $matrix1Columns, null);
+                for ($i = $matrix1Rows; $i < $matrix2Rows; ++$i) {
                     $matrix1[$i] = $x;
                 }
             }
@@ -2375,15 +2375,15 @@ private function executeNumericBinaryOperation(mixed $operand1, mixed $operand2,
             for ($row = 0; $row < $rows; ++$row) {
                 for ($column = 0; $column < $columns; ++$column) {
                     /** @var mixed[][] $operand1 */
-                    if ($operand1[$row][$column] === null) {
+                    if (($operand1[$row][$column] ?? null) === null) {
                         $operand1[$row][$column] = 0;
                     } elseif (!self::isNumericOrBool($operand1[$row][$column])) {
                         $operand1[$row][$column] = self::makeError($operand1[$row][$column]);
 
                         continue;
                     }
                     /** @var mixed[][] $operand2 */
-                    if ($operand2[$row][$column] === null) {
+                    if (($operand2[$row][$column] ?? null) === null) {
                         $operand2[$row][$column] = 0;
                     } elseif (!self::isNumericOrBool($operand2[$row][$column])) {
                         $operand1[$row][$column] = self::makeError($operand2[$row][$column]);

src/PhpSpreadsheet/Calculation/Calculation.php

@@ -62,7 +62,7 @@ private static function filterByRow(array $lookupArray, array $matchArray): arra
 
         return array_filter(
             array_values($lookupArray),
-            fn ($index): bool => (bool) $matchArray[$index],
+            fn ($index): bool => (bool) ($matchArray[$index] ?? null),
             ARRAY_FILTER_USE_KEY
         );
     }