Changes by @Progi1984

docs/changes/1.x/1.2.0.md

@@ -15,6 +15,20 @@
 - 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)
+  - Fixed addHTML (text-align:right in html is not handled correctly) in [#2467](https://github.com/PHPOffice/PHPWord/pull/2467)
+  - HTML Writer : Added ability to specify generic fallback font 
+  - HTML Writer : Added ability to specify handling of whitespace
+  - HTML Writer : Added support for Table Border style, color, and size
+  - HTML Writer : Added support for empty paragraphs (Word writer permits, browsers generally suppress)
+  - HTML Writer : Paragraph style should support indentation, line-height, page-break-before
+  - HTML Writer : Removed margin-top/bottom when spacing is null in Paragraph style
+  - HTML Writer : Added default paragraph style to all paragraphs, as well as class Normal
+  - HTML Writer : Use css @page and page declarations for sections
+  - HTML Writer : Wrap sections in div, with page break before each (except first)
+  - PDF Writer : Added support for PageBreak
+  - PDF Writer : Added callback for modifying the HTML
+  - Added Support for Language, both for document overall and individual text elements
 
 ### Bug fixes
 
@@ -41,4 +55,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 :

phpstan-baseline.neon

@@ -1850,6 +1850,11 @@ parameters:
 			count: 1
 			path: tests/PhpWordTests/Writer/HTML/ElementTest.php
 
+		-
+			message: "#^Parameter \\#2 \\$libraryBaseDir of static method PhpOffice\\\\PhpWord\\\\Settings\\:\\:setPdfRenderer\\(\\) expects string, string\\|false given\\.$#"
+			count: 3
+			path: tests/PhpWordTests/Writer/HTML/Element/PageBreakTest.php
+
 		-
 			message: "#^Method PhpOffice\\\\PhpWordTests\\\\Writer\\\\ODText\\\\Style\\\\FontTest\\:\\:providerAllNamedColors\\(\\) has no return type specified\\.$#"
 			count: 1
@@ -1905,6 +1910,11 @@ parameters:
 			count: 1
 			path: tests/PhpWordTests/Writer/PDF/MPDFTest.php
 
+		-
+			message: "#^Parameter \\#2 \\$libraryBaseDir of static method PhpOffice\\\\PhpWord\\\\Settings\\:\\:setPdfRenderer\\(\\) expects string, string\\|false given\\.$#"
+			count: 1
+			path: tests/PhpWordTests/Writer/PDF/MPDFTest.php
+
 		-
 			message: "#^Parameter \\#2 \\$libraryBaseDir of static method PhpOffice\\\\PhpWord\\\\Settings\\:\\:setPdfRenderer\\(\\) expects string, string\\|false given\\.$#"
 			count: 2
@@ -1915,6 +1925,11 @@ parameters:
 			count: 1
 			path: tests/PhpWordTests/Writer/PDF/TCPDFTest.php
 
+		-
+			message: "#^Parameter \\#2 \\$libraryBaseDir of static method PhpOffice\\\\PhpWord\\\\Settings\\:\\:setPdfRenderer\\(\\) expects string, string\\|false given\\.$#"
+			count: 1
+			path: tests/PhpWordTests/Writer/PDFTest.php
+
 		-
 			message: "#^Method PhpOffice\\\\PhpWordTests\\\\Writer\\\\RTF\\\\ElementTest\\:\\:removeCr\\(\\) has no return type specified\\.$#"
 			count: 1

samples/Sample_52_RTLDefault.php

@@ -5,12 +5,11 @@
 use PhpOffice\PhpWord\PhpWord;
 use PhpOffice\PhpWord\Settings;
 use PhpOffice\PhpWord\Shared\Html as SharedHtml;
-use PhpOffice\PhpWord\Style;
 
 // Suggested by issue 2427.
 echo date('H:i:s'), ' Create new PhpWord object', EOL;
 $phpWord = new PhpWord();
-Style::setDefaultRtl(true);
+Settings::setDefaultRtl(true);
 $phpWord->setDefaultFontName('DejaVu Sans'); // for good rendition of PDF
 $rendererName = Settings::PDF_RENDERER_MPDF;
 $rendererLibraryPath = $vendorDirPath . '/mpdf/mpdf';
@@ -31,4 +30,4 @@
 if (!CLI) {
     include_once 'Sample_Footer.php';
 }
-Style::setDefaultRtl(null);
+Settings::setDefaultRtl(false);

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

@@ -77,6 +77,7 @@ public function __construct()
         // Reset Media and styles
         Media::resetElements();
         Style::resetStyles();
+        Settings::setDefaultRtl(null);
 
         // Collection
         $collections = ['Bookmarks', 'Titles', 'Footnotes', 'Endnotes', 'Charts', 'Comments'];
@@ -256,68 +257,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 +326,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/Settings.php

@@ -131,6 +131,13 @@ class Settings
      */
     private static $defaultPaper = self::DEFAULT_PAPER;
 
+    /**
+     * Is RTL by default ?
+     *
+     * @var ?bool
+     */
+    private static $defaultRtl;
+
     /**
      * The user defined temporary directory.
      *
@@ -387,6 +394,16 @@ public static function setDefaultFontSize($value): bool
         return false;
     }
 
+    public static function setDefaultRtl(?bool $defaultRtl): void
+    {
+        self::$defaultRtl = $defaultRtl;
+    }
+
+    public static function isDefaultRtl(): ?bool
+    {
+        return self::$defaultRtl;
+    }
+
     /**
      * Load setting from phpword.yml or phpword.yml.dist.
      */