Add Support for Various Missing Features in HTML Writer

This PR supersedes PHPOffice#1814, which had become badly out of sync due to recent changes to the repository.

Implement a number of features implemented in PhpWord,
but not yet supported in PhpWord HTML Writer.

1. Use css @page and page declarations for sections.
2. Wrap sections in div, with page break before each (except first).
3. Add ability to specify generic fallback font for html (documentation change).
4. Add ability to specify handling of whitespace in html (documentation change).
   Currently, Word writer preserves space but HTML writer does not.
5. Support for Language, both for document overall and individual text elements.
6. Support for PageBreak for HTML (currently only PDF is supported).
7. Support for Table Border style, color, and size.
8. Support for empty paragraphs (Word writer permits, browsers generally suppress).
9. Default paragraph style should apply to all paragraphs, as well as class Normal.
10. Paragraph style should support line-height.
11. Paragraph style should support indentation.
12. Paragraph style should support page-break-before.
13. Paragraph style should not specify margin-top/bottom when spacing is null.

Author: oleibman

composer.json

@@ -61,8 +61,7 @@
         "php": "^7.1|^8.0",
         "ext-dom": "*",
         "ext-json": "*",
-        "ext-xml": "*",
-        "laminas/laminas-escaper": ">=2.6"
+        "ext-xml": "*"
     },
     "require-dev": {
         "ext-zip": "*",
@@ -74,7 +73,8 @@
         "phpunit/phpunit": ">=7.0",
         "tecnickcom/tcpdf": "^6.5",
         "symfony/process": "^4.4",
-        "friendsofphp/php-cs-fixer": "^3.3"
+        "friendsofphp/php-cs-fixer": "^3.3",
+        "squizlabs/php_codesniffer": "^3.7"
     },
     "suggest": {
         "ext-zip": "Allows writing OOXML and ODF",

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:
 

phpunit.xml.dist

@@ -1,23 +1,16 @@
-<phpunit backupGlobals="false"
-         backupStaticAttributes="false"
-         bootstrap="./tests/bootstrap.php"
-         colors="true"
-         convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
-         processIsolation="false"
-         stopOnFailure="false">
-    <testsuites>
-        <testsuite name="PhpWord Test Suite">
-            <directory>./tests/PhpWordTests</directory>
-        </testsuite>
-    </testsuites>
-    <filter>
-        <whitelist>
-            <directory suffix=".php">./src</directory>
-            <exclude>
-                <directory suffix=".php">./src/PhpWordTests/Shared/PCLZip</directory>
-            </exclude>
-        </whitelist>
-    </filter>
+<?xml version="1.0"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" backupGlobals="false" backupStaticAttributes="false" bootstrap="./tests/bootstrap.php" colors="true" convertErrorsToExceptions="true" convertNoticesToExceptions="true" convertWarningsToExceptions="true" processIsolation="false" stopOnFailure="false" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
+  <coverage>
+    <include>
+      <directory suffix=".php">./src</directory>
+    </include>
+    <exclude>
+      <directory suffix=".php">./src/PhpWordTests/Shared/PCLZip</directory>
+    </exclude>
+  </coverage>
+  <testsuites>
+    <testsuite name="PhpWord Test Suite">
+      <directory>./tests/PhpWordTests</directory>
+    </testsuite>
+  </testsuites>
 </phpunit>

src/PhpWord/Element/Cell.php

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

src/PhpWord/Element/Title.php

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

src/PhpWord/PhpWord.php

@@ -256,6 +256,68 @@ 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.
      *

src/PhpWord/Style/Border.php

@@ -25,7 +25,7 @@ class Border extends AbstractStyle
     /**
      * Border Top Size.
      *
-     * @var float|int
+     * @var null|float|int
      */
     protected $borderTopSize;
 
@@ -46,7 +46,7 @@ class Border extends AbstractStyle
     /**
      * Border Left Size.
      *
-     * @var float|int
+     * @var null|float|int
      */
     protected $borderLeftSize;
 
@@ -67,7 +67,7 @@ class Border extends AbstractStyle
     /**
      * Border Right Size.
      *
-     * @var float|int
+     * @var null|float|int
      */
     protected $borderRightSize;
 
@@ -88,7 +88,7 @@ class Border extends AbstractStyle
     /**
      * Border Bottom Size.
      *
-     * @var float|int
+     * @var null|float|int
      */
     protected $borderBottomSize;
 
@@ -124,7 +124,7 @@ public function getBorderSize()
     /**
      * Set border size.
      *
-     * @param float|int $value
+     * @param null|float|int $value
      *
      * @return self
      */
@@ -205,7 +205,7 @@ public function setBorderStyle($value = null)
     /**
      * Get border top size.
      *
-     * @return float|int
+     * @return null|float|int
      */
     public function getBorderTopSize()
     {
@@ -215,7 +215,7 @@ public function getBorderTopSize()
     /**
      * Set border top size.
      *
-     * @param float|int $value
+     * @param null|float|int $value
      *
      * @return self
      */
@@ -287,7 +287,7 @@ public function getBorderLeftSize()
     /**
      * Set border left size.
      *
-     * @param float|int $value
+     * @param null|float|int $value
      *
      * @return self
      */
@@ -349,7 +349,7 @@ public function setBorderLeftStyle($value = null)
     /**
      * Get border right size.
      *
-     * @return float|int
+     * @return null|float|int
      */
     public function getBorderRightSize()
     {
@@ -421,7 +421,7 @@ public function setBorderRightStyle($value = null)
     /**
      * Get border bottom size.
      *
-     * @return float|int
+     * @return null|float|int
      */
     public function getBorderBottomSize()
     {