Add support for various missing features in HTML Writer

composer.json

@@ -59,8 +59,7 @@
     },
     "require": {
         "php": "^5.3.3 || ^7.0 || ^8.0",
-        "ext-xml": "*",
-        "laminas/laminas-escaper": "^2.2"
+        "ext-xml": "*"
     },
     "require-dev": {
         "ext-zip": "*",

docs/general.rst

@@ -151,6 +151,14 @@ default font by using the following two functions:
     $phpWord->setDefaultFontName('Times New Roman');
     $phpWord->setDefaultFontSize(12);
 
+When generating html/pdf, you can alter the default handling of white space (normal),
+and/or supply a fallback generic font as follows:
+
+.. code-block:: php
+
+    $phpWord->setDefaultHtmlGenericFont('serif');
+    $phpWord->setDefaultHtmlWhiteSpace('pre-wrap');
+
 Document settings
 -----------------
 Settings for the generated document can be set using ``$phpWord->getSettings()``

docs/styles.rst

@@ -64,6 +64,8 @@ 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).
 
 .. _paragraph-style:
 

src/PhpWord/Element/Cell.php

@@ -32,7 +32,7 @@ class Cell extends AbstractContainer
     /**
      * Cell width
      *
-     * @var int
+     * @var int|null
      */
     private $width = null;
 
@@ -46,7 +46,7 @@ class Cell extends AbstractContainer
     /**
      * Create new instance
      *
-     * @param int $width
+     * @param int|null $width
      * @param array|\PhpOffice\PhpWord\Style\Cell $style
      */
     public function __construct($width = null, $style = null)

src/PhpWord/Element/Title.php

@@ -79,7 +79,7 @@ public function __construct($text, $depth = 1)
     /**
      * Get Title Text content
      *
-     * @return string
+     * @return string|TextRun
      */
     public function getText()
     {

src/PhpWord/PhpWord.php

@@ -286,6 +286,66 @@ public function setDefaultFontName($fontName)
         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
      *

src/PhpWord/Style/Border.php

@@ -25,7 +25,7 @@ class Border extends AbstractStyle
     /**
      * Border Top Size
      *
-     * @var int|float
+     * @var int|float|null
      */
     protected $borderTopSize;
 
@@ -46,7 +46,7 @@ class Border extends AbstractStyle
     /**
      * Border Left Size
      *
-     * @var int|float
+     * @var int|float|null
      */
     protected $borderLeftSize;
 
@@ -67,7 +67,7 @@ class Border extends AbstractStyle
     /**
      * Border Right Size
      *
-     * @var int|float
+     * @var int|float|null
      */
     protected $borderRightSize;
 
@@ -88,7 +88,7 @@ class Border extends AbstractStyle
     /**
      * Border Bottom Size
      *
-     * @var int|float
+     * @var int|float|null
      */
     protected $borderBottomSize;
 
@@ -124,7 +124,7 @@ public function getBorderSize()
     /**
      * Set border size
      *
-     * @param int|float $value
+     * @param int|float|null $value
      * @return self
      */
     public function setBorderSize($value = null)
@@ -202,7 +202,7 @@ public function setBorderStyle($value = null)
     /**
      * Get border top size
      *
-     * @return int|float
+     * @return int|float|null
      */
     public function getBorderTopSize()
     {
@@ -212,7 +212,7 @@ public function getBorderTopSize()
     /**
      * Set border top size
      *
-     * @param int|float $value
+     * @param int|float|null $value
      * @return self
      */
     public function setBorderTopSize($value = null)
@@ -281,7 +281,7 @@ public function getBorderLeftSize()
     /**
      * Set border left size
      *
-     * @param int|float $value
+     * @param int|float|null $value
      * @return self
      */
     public function setBorderLeftSize($value = null)
@@ -340,7 +340,7 @@ public function setBorderLeftStyle($value = null)
     /**
      * Get border right size
      *
-     * @return int|float
+     * @return int|float|null
      */
     public function getBorderRightSize()
     {
@@ -350,7 +350,7 @@ public function getBorderRightSize()
     /**
      * Set border right size
      *
-     * @param int|float $value
+     * @param int|float|null $value
      * @return self
      */
     public function setBorderRightSize($value = null)
@@ -409,7 +409,7 @@ public function setBorderRightStyle($value = null)
     /**
      * Get border bottom size
      *
-     * @return int|float
+     * @return int|float|null
      */
     public function getBorderBottomSize()
     {
@@ -419,7 +419,7 @@ public function getBorderBottomSize()
     /**
      * Set border bottom size
      *
-     * @param int|float $value
+     * @param int|float|null $value
      * @return self
      */
     public function setBorderBottomSize($value = null)

src/PhpWord/Style/Font.php

@@ -248,7 +248,7 @@ class Font extends AbstractStyle
     /**
      * Languages
      *
-     * @var \PhpOffice\PhpWord\Style\Language
+     * @var \PhpOffice\PhpWord\Style\Language|null
      */
     private $lang;
 
@@ -288,6 +288,8 @@ public function __construct($type = 'text', $paragraph = null)
      */
     public function getStyleValues()
     {
+        $hws = 'htmlWhiteSpace';
+        $hgf = 'htmlGenericFont';
         $styles = array(
             'name'          => $this->getStyleName(),
             'basic'         => array(
@@ -319,6 +321,8 @@ public function getStyleValues()
             'rtl'           => $this->isRTL(),
             'shading'       => $this->getShading(),
             'lang'          => $this->getLang(),
+            $hws            => $this->getHtmlWhiteSpace(),
+            $hgf            => $this->getHtmlGenericFont(),
         );
 
         return $styles;
@@ -852,7 +856,7 @@ public function setShading($value = null)
     /**
      * Get language
      *
-     * @return \PhpOffice\PhpWord\Style\Language
+     * @return \PhpOffice\PhpWord\Style\Language|null
      */
     public function getLang()
     {
@@ -992,4 +996,110 @@ public function setPosition($value = null)
 
         return $this;
     }
+
+    /**
+     * Preservation of white space in html
+     *
+     * @var string Value used for css white-space
+     */
+    private $htmlWhiteSpace = '';
+
+    /**
+     * Validate html css white-space value. It is expected that only pre-wrap and normal (default) are useful.
+     *
+     * @param string $value Should be one of pre-wrap, normal, nowrap, pre, pre-line, initial, inherit
+     * @return string value if valid, null string if not
+     */
+    public static function validateWhiteSpace($value)
+    {
+        switch ($value) {
+            case 'pre-wrap':
+            case 'normal':
+            case 'nowrap':
+            case 'pre':
+            case 'pre-line':
+            case 'initial':
+            case 'inherit':
+                return $value;
+            default:
+                return '';
+        }
+    }
+
+    /**
+     * Set html css white-space value. It is expected that only pre-wrap and normal (default) are useful.
+     *
+     * @param string $value Should be one of pre-wrap, normal, nowrap, pre, pre-line, initial, inherit
+     * @return self
+     */
+    public function setHtmlWhiteSpace($value)
+    {
+        $this->htmlWhiteSpace = self::validateWhiteSpace($value);
+
+        return $this;
+    }
+
+    /**
+     * Get html css white-space value
+     *
+     * @return string
+     */
+    public function getHtmlWhiteSpace()
+    {
+        return $this->htmlWhiteSpace;
+    }
+
+    /**
+     * Generic font as fallback for html
+     *
+     * @var string generic font name
+     */
+    private $htmlGenericFont = '';
+
+    /**
+     * Validate generic font for fallback for html.
+     *
+     * @param string $value generic font name
+     * @return string value if legitimate, null string if not
+     */
+    public static function validateGenericFont($value)
+    {
+        switch ($value) {
+            case 'serif':
+            case 'sans-serif':
+            case 'monospace':
+            case 'cursive':
+            case 'fantasy':
+            case 'system-ui':
+            case 'math':
+            case 'emoji':
+            case 'fangsong':
+                return $value;
+            default:
+                return '';
+        }
+    }
+
+    /**
+     * Set generic font for fallback for html.
+     *
+     * @param string $value generic font name
+     * @return self
+     */
+    public function setHtmlGenericFont($value)
+    {
+        $this->htmlGenericFont = self::validateGenericFont($value);
+
+        return $this;
+    }
+
+    /**
+     * Get html fallback generic font
+     *
+     * @return string
+     */
+    public function getHtmlGenericFont()
+    {
+        return $this->htmlGenericFont;
+    }
 }