Changes by @Progi1984

Author: Progi1984

docs/changes/1.x/1.2.0.md

@@ -15,6 +15,24 @@
 - Word2007 Reader/Writer: Permit book-fold printing by [@potofcoffee](https://github.com/potofcoffee) in [#2225](https://github.com/PHPOffice/PHPWord/pull/2225) & [#2470](https://github.com/PHPOffice/PHPWord/pull/2470)
 - Word2007 Writer : Add PageNumber to TOC by [@jet-desk](https://github.com/jet-desk) in [#1652](https://github.com/PHPOffice/PHPWord/pull/1652) & [#2471](https://github.com/PHPOffice/PHPWord/pull/2471)
 - Word2007 Reader/Writer + ODText Reader/Writer : Add Element Formula in  by [@Progi1984](https://github.com/Progi1984) in [#2477](https://github.com/PHPOffice/PHPWord/pull/2477)
+- Add Support for Various Missing Features in HTML Writer by [@oleibman](https://github.com/oleibman) in [#2475](https://github.com/PHPOffice/PHPWord/pull/2475)
+  - HTML Writer : Added ability to specify generic fallback font 
+  - HTML Writer : Added ability to specify handling of whitespace
+  - PDF Writer : Added support for PageBreak
+  - PDF Writer : Added callback for modifying the HTML
+<!---
+Use css @page and page declarations for sections.
+Wrap sections in div, with page break before each (except first).
+Support for Language, both for document overall and individual text elements.
+Support for Table Border style, color, and size.
+Support for empty paragraphs (Word writer permits, browsers generally suppress).
+Default paragraph style should apply to all paragraphs, as well as class Normal.
+Paragraph style should support line-height.
+Paragraph style should support indentation.
+Paragraph style should support page-break-before.
+Paragraph style should not specify margin-top/bottom when spacing is null.
+Fixed Bug while transforming html to word document with addHtml method. #2467 - text-align:right in html is not handled correctly.
+-->
 
 ### Bug fixes
 
@@ -41,4 +59,8 @@
 - Bump phpunit/phpunit from 9.6.11 to 9.6.13 by [@dependabot](https://github.com/dependabot) in [#2481](https://github.com/PHPOffice/PHPWord/pull/2481)
 - Bump tecnickcom/tcpdf from 6.6.2 to 6.6.5 by [@dependabot](https://github.com/dependabot) in [#2482](https://github.com/PHPOffice/PHPWord/pull/2482)
 - Bump phpmd/phpmd from 2.13.0 to 2.14.1 by [@dependabot](https://github.com/dependabot) in [#2483](https://github.com/PHPOffice/PHPWord/pull/2483)
-- Bump phpstan/phpstan-phpunit from 1.3.14 to 1.3.15 by [@dependabot](https://github.com/dependabot) in [#2494](https://github.com/PHPOffice/PHPWord/pull/2494)
+- Bump phpstan/phpstan-phpunit from 1.3.14 to 1.3.15 by [@dependabot](https://github.com/dependabot) in [#2494](https://github.com/PHPOffice/PHPWord/pull/2494)
+
+
+### BC Breaks
+- Removed dependency `laminas/laminas-escaper`

docs/usage/styles/font.md

@@ -24,5 +24,5 @@ Available Font style options:
    See ``\PhpOffice\PhpWord\Style\Language`` class for some language codes.
 - ``position``. The text position, raised or lowered, in half points
 - ``hidden``. Hidden text, *true* or *false*.
-`htmlWhiteSpace``. How white space is handled when generating html/pdf. Possible values are *pre-wrap* and *normal* (other css values for white space are accepted, but are not expected to be useful).
-- ``htmlGenericFont``. Fallback generic font for html/pdf. Possible values are *sans-serif*, *serif*, and *monospace* (other css values for generic fonts are accepted).
+- ``whiteSpace``. How white space is handled when generating html/pdf. Possible values are *pre-wrap* and *normal* (other css values for white space are accepted, but are not expected to be useful).
+- ``fallbackFont``. Fallback generic font for html/pdf. Possible values are *sans-serif*, *serif*, and *monospace* (other css values for generic fonts are accepted).

docs/usage/writers.md

@@ -11,12 +11,13 @@ $writer->save(__DIR__ . '/sample.html');
 ```
 
 
-When generating html/pdf, you can alter the default handling of white space (normal),
-and/or supply a fallback generic font as follows:
+When generating html/pdf, you can alter the default handling of white space (normal), and/or supply a fallback generic font as follows:
 
 ```php
-    $phpWord->setDefaultHtmlGenericFont('serif');
-    $phpWord->setDefaultHtmlWhiteSpace('pre-wrap');
+$writer = IOFactory::createWriter($oPhpWord, 'HTML');
+$writer->setDefaultGenericFont('serif');
+$writer->setDefaultWhiteSpace('pre-wrap');
+$writer->save(__DIR__ . '/sample.html');
 ```
 
 ## ODText
@@ -39,6 +40,33 @@ $writer = IOFactory::createWriter($oPhpWord, 'PDF');
 $writer->save(__DIR__ . '/sample.pdf');
 ```
 
+To generate a PDF, the PhpWord object passes through HTML before generating the PDF.
+This HTML can be modified using a callback.
+
+``` php
+<?php
+
+$writer = IOFactory::createWriter($oPhpWord, 'PDF');
+$writer->setEditCallback('cbEditHTML');
+$writer->save(__DIR__ . '/sample.pdf');
+
+/**
+ * Add a meta tag generator
+ */
+function cbEditHTML(string $inputHTML): string
+{
+    $beforeBody = '<meta name="generator" content="PHPWord" />';
+    $needle = '</head>';
+
+    $pos = strpos($inputHTML, $needle);
+    if ($pos !== false) {
+        $inputHTML = (string) substr_replace($inputHTML, "$beforeBody\n$needle", $pos, strlen($needle));
+    }
+
+    return $inputHTML;
+}
+```
+
 ### Options
 
 You can define options like :

src/PhpWord/Metadata/Settings.php

@@ -114,7 +114,7 @@ class Settings
     /**
      * Theme Font Languages.
      *
-     * @var Language
+     * @var ?Language
      */
     private $themeFontLang;
 
@@ -369,22 +369,20 @@ public function setMirrorMargins($mirrorMargins): void
 
     /**
      * Returns the Language.
-     *
-     * @return Language
      */
-    public function getThemeFontLang()
+    public function getThemeFontLang(): ?Language
     {
         return $this->themeFontLang;
     }
 
     /**
-     * sets the Language for this document.
-     *
-     * @param Language $themeFontLang
+     * Sets the Language for this document.
      */
-    public function setThemeFontLang($themeFontLang): void
+    public function setThemeFontLang(Language $themeFontLang): self
     {
         $this->themeFontLang = $themeFontLang;
+
+        return $this;
     }
 
     /**

src/PhpWord/PhpWord.php

@@ -256,68 +256,6 @@ public function setDefaultFontName($fontName): void
         Settings::setDefaultFontName($fontName);
     }
 
-    /**
-     * Default generic name for default font for html.
-     *
-     * @var string
-     */
-    private $defaultHtmlGenericFont = '';
-
-    /**
-     * Get generic name for default font for html.
-     *
-     * @return string
-     */
-    public function getDefaultHtmlGenericFont()
-    {
-        return $this->defaultHtmlGenericFont;
-    }
-
-    /**
-     * Set generic name for default font for html.
-     *
-     * @param string $value
-     *
-     * @return bool
-     */
-    public function setDefaultHtmlGenericFont($value)
-    {
-        $this->defaultHtmlGenericFont = \PhpOffice\PhpWord\Style\Font::validateGenericFont($value);
-
-        return '' !== $this->defaultHtmlGenericFont;
-    }
-
-    /**
-     * Default white space style for html.
-     *
-     * @var string
-     */
-    private $defaultHtmlWhiteSpace = '';
-
-    /**
-     * Get default white space style for html.
-     *
-     * @return string
-     */
-    public function getDefaultHtmlWhiteSpace()
-    {
-        return $this->defaultHtmlWhiteSpace;
-    }
-
-    /**
-     * Set default white space style for html.
-     *
-     * @param string $value
-     *
-     * @return bool
-     */
-    public function setDefaultHtmlWhiteSpace($value)
-    {
-        $this->defaultHtmlWhiteSpace = \PhpOffice\PhpWord\Style\Font::validateWhiteSpace($value);
-
-        return '' !== $this->defaultHtmlWhiteSpace;
-    }
-
     /**
      * Get default font size.
      *
@@ -387,4 +325,52 @@ public function save($filename, $format = 'Word2007', $download = false)
 
         return true;
     }
+
+    /**
+     * Create new section.
+     *
+     * @deprecated 0.10.0
+     *
+     * @param array $settings
+     *
+     * @return \PhpOffice\PhpWord\Element\Section
+     *
+     * @codeCoverageIgnore
+     */
+    public function createSection($settings = null)
+    {
+        return $this->addSection($settings);
+    }
+
+    /**
+     * Get document properties object.
+     *
+     * @deprecated 0.12.0
+     *
+     * @return \PhpOffice\PhpWord\Metadata\DocInfo
+     *
+     * @codeCoverageIgnore
+     */
+    public function getDocumentProperties()
+    {
+        return $this->getDocInfo();
+    }
+
+    /**
+     * Set document properties object.
+     *
+     * @deprecated 0.12.0
+     *
+     * @param \PhpOffice\PhpWord\Metadata\DocInfo $documentProperties
+     *
+     * @return self
+     *
+     * @codeCoverageIgnore
+     */
+    public function setDocumentProperties($documentProperties)
+    {
+        $this->metadata['Document'] = $documentProperties;
+
+        return $this;
+    }
 }

src/PhpWord/Shared/Handler.php

@@ -145,16 +145,10 @@ public static function isUTF8($value = '')
     public static function toUTF8($value = '')
     {
         if (null !== $value && !self::isUTF8($value)) {
-            // utf8_encode deprecated in php8.2, but mb_convert_encoding always usable
+            // PHP8.2 : utf8_encode is deprecated, but mb_convert_encoding always usable
             $value = (function_exists('mb_convert_encoding')) ? mb_convert_encoding($value, 'UTF-8', 'ISO-8859-1') : utf8_encode($value);
         }
 
-        return self::ensureStringOrNull($value);
-    }
-
-    /** @param null|array|string $value */
-    private static function ensureStringOrNull($value): ?string
-    {
         return is_array($value) ? '' : $value;
     }
 

src/PhpWord/Shared/Text.php

@@ -0,0 +1,76 @@
+<?php
+/**
+ * This file is part of PHPWord - A pure PHP library for reading and writing
+ * word processing documents.
+ *
+ * PHPWord is free software distributed under the terms of the GNU Lesser
+ * General Public License version 3 as published by the Free Software Foundation.
+ *
+ * For the full copyright and license information, please read the LICENSE
+ * file that was distributed with this source code. For the full list of
+ * contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
+ *
+ * @see         https://github.com/PHPOffice/PHPWord
+ *
+ * @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
+ */
+declare(strict_types=1);
+
+namespace PhpOffice\PhpWord\Shared;
+
+class Validate
+{
+    public const CSS_WHITESPACE = [
+        'pre-wrap',
+        'normal',
+        'nowrap',
+        'pre',
+        'pre-line',
+        'initial',
+        'inherit',
+    ];
+
+    public const CSS_GENERICFONT = [
+        'serif',
+        'sans-serif',
+        'monospace',
+        'cursive',
+        'fantasy',
+        'system-ui',
+        'math',
+        'emoji',
+        'fangsong',
+    ];
+
+    /**
+     * Validate html css white-space value. It is expected that only pre-wrap and normal (default) are useful.
+     *
+     * @param string $value CSS White space
+     *
+     * @return string value if valid, empty string if not
+     */
+    public static function validateCSSWhiteSpace(?string $value): string
+    {
+        if (in_array($value, self::CSS_WHITESPACE)) {
+            return $value;
+        }
+
+        return '';
+    }
+
+    /**
+     * Validate generic font for fallback for html.
+     *
+     * @param string $value Generic font name
+     *
+     * @return string Value if legitimate, empty string if not
+     */
+    public static function validateCSSGenericFont(?string $value): string
+    {
+        if (in_array($value, self::CSS_GENERICFONT)) {
+            return $value;
+        }
+
+        return '';
+    }
+}