Tests and Documentation

docs/topics/recipes.md

@@ -1099,6 +1099,21 @@ All cells bound to the theme fonts (via the `Font::setScheme` method) can be eas
 $spreadsheet->resetThemeFonts();
 ```
 
+### Charset for Arabic and Persian Fonts
+
+It is unknown why this should be needed. However, some Excel
+users have reported better results if the internal declaration for an
+Arabic/Persian font includes a `charset` declaration.
+This seems like a bug in Excel, but, starting with release 4.4,
+this can be accomplished at the spreadsheet level, via:
+```php
+$spreadsheet->addFontCharset('C Nazanin');
+```
+As many charsets as desired can be added in this manner.
+There is a second optional parameter specifying the charset id
+to this method, but, since this seems to be needed only for
+Arabic/Persian, that is its default value.
+
 ### Styling cell borders
 
 In PhpSpreadsheet it is easy to apply various borders on a rectangular

src/PhpSpreadsheet/Spreadsheet.php

@@ -183,7 +183,12 @@ class Spreadsheet implements JsonSerializable
         'B Nazanin' => SharedFont::CHARSET_ANSI_ARABIC,
     ];
 
-    public function addFontCharset(string $fontName, int $charset): void
+    /**
+     * @param int $charset uses any value from Shared\Font,
+     *    but defaults to ARABIC because that is the only known
+     *    charset for which this declaration might be needed
+     */
+    public function addFontCharset(string $fontName, int $charset = SharedFont::CHARSET_ANSI_ARABIC): void
     {
         $this->fontCharsets[$fontName] = $charset;
     }

tests/PhpSpreadsheetTests/Writer/Xlsx/FontCharsetTest.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpOffice\PhpSpreadsheetTests\Writer\Xlsx;
+
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+use PhpOffice\PhpSpreadsheetTests\Functional\AbstractFunctional;
+
+class FontCharsetTest extends AbstractFunctional
+{
+    private ?Spreadsheet $spreadsheet = null;
+
+    private ?Spreadsheet $reloadedSpreadsheet = null;
+
+    protected function tearDown(): void
+    {
+        if ($this->spreadsheet !== null) {
+            $this->spreadsheet->disconnectWorksheets();
+            $this->spreadsheet = null;
+        }
+        if ($this->reloadedSpreadsheet !== null) {
+            $this->reloadedSpreadsheet->disconnectWorksheets();
+            $this->reloadedSpreadsheet = null;
+        }
+    }
+
+    public function testFontCharset(): void
+    {
+        $spreadsheet = $this->spreadsheet = new Spreadsheet();
+        $sheet = $this->spreadsheet->getActiveSheet();
+        $sheet->getStyle('A1')->getFont()->setName('Nazanin');
+        $spreadsheet->addFontCharset('Nazanin');
+
+        $spreadsheet2 = $this->reloadedSpreadsheet = $this->writeAndReload($spreadsheet, 'Xlsx');
+        $sheet2 = $spreadsheet2->getActiveSheet();
+        $sheet2->getStyle('B1')->getFont()->setName('B Nazanin');
+        $sheet2->getStyle('C1')->getFont()->setName('C Nazanin');
+        $sheet2->getStyle('D1')->getFont()->setName('D Nazanin');
+        $spreadsheet2->addFontCharset('C Nazanin');
+        // Do not add D Nazanin for this test.
+        self::assertSame(
+            [
+                'B Nazanin' => 178, // default entry
+                'Nazanin' => 178, // should have been set by Xlsx Reader
+                'C Nazanin' => 178, // explicitly set in this test
+            ],
+            $spreadsheet2->getFontCharsets()
+        );
+    }
+}