Allow to set "autoHyphenation" setting (#1282)

* Allow to set "autoHyphenation" for document
* Allow to set "consecutiveHyphenLimit" for document
* Allow to set "hyphenationZone" for document
* Allow to set "doNotHyphenateCaps" for document
* Allow to set "suppressAutoHyphens" for paragraph
* randomize the tempDir more
* Word2007 parsing title formatting (#1297)
* Improve Title parsing
- Title should be able to contain TextRun
- Style 'Title' should be treated the same with as Heading
- Add tests for Heading/Title reader
* update the documentation and the changelog
* PHP 7.2 build should not fail anymore
* fix parsing of footnotes and endnotes
* add method to remove an element from a section
* add method to allow sorting of sections

Author: Trainmaster

CHANGELOG.md

@@ -15,6 +15,7 @@ v0.15.0 (?? ??? 2018)
 - Add parsing of formatting inside lists @atomicalnet @troosan #594
 - Added support for Vertically Raised or Lowered Text (w:position) @anrikun @troosan #640
 - Add support for MACROBUTTON field @phryneas @troosan #1021
+- Add support for Hyphenation @Trainmaster #1282 (Document: `autoHyphenation`, `consecutiveHyphenLimit`, `hyphenationZone`, `doNotHyphenateCaps`, Paragraph: `suppressAutoHyphens`)
 
 ### Fixed
 - Fix reading of docx default style - @troosan #1238
@@ -477,4 +478,4 @@ This is the first release after a long development hiatus in [CodePlex](https://
 - Basic CI with Travis - @Progi1984
 - Added PHPWord_Exception and exception when could not copy the template - @Progi1984
 - IMPROVED: Moved examples out of Classes directory - @Progi1984
-- IMPROVED: Advanced string replace in setValue for Template - @Esmeraldo [#49](http://phpword.codeplex.com/workitem/49)
+- IMPROVED: Advanced string replace in setValue for Template - @Esmeraldo [#49](http://phpword.codeplex.com/workitem/49)

docs/general.rst

@@ -217,10 +217,10 @@ The default language of the document can be change with the following.
 
     $phpWord->getSettings()->setThemeFontLang(new Language(Language::FR_BE));
 
-``Languge`` has 3 parameters, one for Latin languages, one for East Asian languages and one for Complex (Bi-Directional) languages.
+``Language`` has 3 parameters, one for Latin languages, one for East Asian languages and one for Complex (Bi-Directional) languages.
 A couple of language codes are provided in the ``PhpOffice\PhpWord\ComplexType\Language`` class but any valid code/ID can be used.
 
-In case you are generating an RTF document the Language need to be set differently.
+In case you are generating an RTF document the language need to be set differently.
 
 .. code-block:: php
 
@@ -290,3 +290,45 @@ To force an update of the fields present in the document, set updateFields to tr
 .. code-block:: php
 
     $phpWord->getSettings()->setUpdateFields(true);
+
+Hyphenation
+-----------
+Hyphenation describes the process of breaking words with hyphens. There are several options to control hyphenation.
+
+Auto hyphenation
+~~~~~~~~~~~~~~~~
+
+To automatically hyphenate text set ``autoHyphenation`` to ``true``.
+
+.. code-block:: php
+
+    $phpWord->getSettings()->setAutoHyphenation(true);
+
+Consecutive Hyphen Limit
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The maximum number of consecutive lines of text ending with a hyphen can be controlled by the ``consecutiveHyphenLimit`` option.
+There is no limit if the option is not set or the provided value is ``0``.
+
+.. code-block:: php
+
+    $phpWord->getSettings()->setConsecutiveHyphenLimit(2);
+
+Hyphenation Zone
+~~~~~~~~~~~~~~~~
+
+The hyphenation zone (in *twip*) is the allowed amount of whitespace before hyphenation is applied.
+The smaller the hyphenation zone the more words are hyphenated. Or in other words, the wider the hyphenation zone the less words are hyphenated.
+
+.. code-block:: php
+
+    $phpWord->getSettings()->setHyphenationZone(\PhpOffice\PhpWord\Shared\Converter::cmToTwip(1));
+
+Hyphenate Caps
+~~~~~~~~~~~~~~
+
+To control whether or not words in all capital letters shall be hyphenated use the `doNotHyphenateCaps` option.
+
+.. code-block:: php
+
+    $phpWord->getSettings()->setDoNotHyphenateCaps(true);

docs/styles.rst

@@ -82,6 +82,7 @@ Available Paragraph style options:
 - ``spaceAfter``. Space after paragraph in *twip*.
 - ``spacing``. Space between lines.
 - ``spacingLineRule``. Line Spacing Rule. *auto*, *exact*, *atLeast*
+- ``suppressAutoHyphens``. Hyphenation for paragraph, *true* or *false*.
 - ``tabs``. Set of custom tab stops.
 - ``widowControl``. Allow first/last line to display on a separate page, *true* or *false*.
 - ``contextualSpacing``. Ignore Spacing Above and Below When Using Identical Styles, *true* or *false*.

src/PhpWord/Element/Field.php

@@ -17,8 +17,6 @@
 
 namespace PhpOffice\PhpWord\Element;
 
-use PhpOffice\PhpWord\Style\Font;
-
 /**
  * Field element
  *
@@ -215,46 +213,6 @@ public function getOptions()
         return $this->options;
     }
 
-    /**
-     * Set Text style
-     *
-     * @param \PhpOffice\PhpWord\Style\Font $style
-     * @return \PhpOffice\PhpWord\Style\Font
-     */
-    public function setFontStyle($style = null)
-    {
-        if (!$style instanceof Font) {
-            throw new \InvalidArgumentException('font style must be of type Font');
-        }
-
-        if ($style->isNoProof()) {
-            $this->fontStyle = $style;
-        } else {
-            // make a copy of the font so the original is not altered
-            $this->fontStyle = clone $style;
-            $this->fontStyle->setNoProof(true);
-        }
-
-        return $this->fontStyle;
-    }
-
-    /**
-     * Get Text style
-     *
-     * @return \PhpOffice\PhpWord\Style\Font
-     */
-    public function getFontStyle()
-    {
-        if ($this->fontStyle == null) {
-            $font = new Font();
-            $font->setNoProof(true);
-
-            return $font;
-        }
-
-        return $this->fontStyle;
-    }
-
     /**
      * Set Field text
      *

src/PhpWord/Metadata/Settings.php

@@ -130,6 +130,32 @@ class Settings
      */
     private $decimalSymbol = '.';
 
+    /**
+     * Automatically hyphenate document contents when displayed
+     *
+     * @var bool|null
+     */
+    private $autoHyphenation;
+
+    /**
+     * Maximum number of consecutively hyphenated lines
+     *
+     * @var int|null
+     */
+    private $consecutiveHyphenLimit;
+
+    /**
+     * The allowed amount of whitespace before hyphenation is applied
+     * @var float|null
+     */
+    private $hyphenationZone;
+
+    /**
+     * Do not hyphenate words in all capital letters
+     * @var bool|null
+     */
+    private $doNotHyphenateCaps;
+
     /**
      * @return Protection
      */
@@ -387,4 +413,68 @@ public function setDecimalSymbol($decimalSymbol)
     {
         $this->decimalSymbol = $decimalSymbol;
     }
+
+    /**
+     * @return bool|null
+     */
+    public function hasAutoHyphenation()
+    {
+        return $this->autoHyphenation;
+    }
+
+    /**
+     * @param bool $autoHyphenation
+     */
+    public function setAutoHyphenation($autoHyphenation)
+    {
+        $this->autoHyphenation = (bool) $autoHyphenation;
+    }
+
+    /**
+     * @return int|null
+     */
+    public function getConsecutiveHyphenLimit()
+    {
+        return $this->consecutiveHyphenLimit;
+    }
+
+    /**
+     * @param int $consecutiveHyphenLimit
+     */
+    public function setConsecutiveHyphenLimit($consecutiveHyphenLimit)
+    {
+        $this->consecutiveHyphenLimit = (int) $consecutiveHyphenLimit;
+    }
+
+    /**
+     * @return float|null
+     */
+    public function getHyphenationZone()
+    {
+        return $this->hyphenationZone;
+    }
+
+    /**
+     * @param float $hyphenationZone Measurement unit is twip
+     */
+    public function setHyphenationZone($hyphenationZone)
+    {
+        $this->hyphenationZone = $hyphenationZone;
+    }
+
+    /**
+     * @return null|bool
+     */
+    public function hasDoNotHyphenateCaps()
+    {
+        return $this->doNotHyphenateCaps;
+    }
+
+    /**
+     * @param bool $doNotHyphenateCaps
+     */
+    public function setDoNotHyphenateCaps($doNotHyphenateCaps)
+    {
+        $this->doNotHyphenateCaps = (bool) $doNotHyphenateCaps;
+    }
 }

src/PhpWord/PhpWord.php

@@ -242,6 +242,17 @@ public function addSection($style = null)
         return $section;
     }
 
+    /**
+     * Sorts the sections using the callable passed
+     *
+     * @see http://php.net/manual/en/function.usort.php for usage
+     * @param callable $sorter
+     */
+    public function sortSections($sorter)
+    {
+        usort($this->sections, $sorter);
+    }
+
     /**
      * Get default font name
      *

src/PhpWord/Reader/Word2007/AbstractPart.php

@@ -364,20 +364,21 @@ protected function readParagraphStyle(XMLReader $xmlReader, \DOMElement $domNode
 
         $styleNode = $xmlReader->getElement('w:pPr', $domNode);
         $styleDefs = array(
-            'styleName'         => array(self::READ_VALUE, array('w:pStyle', 'w:name')),
-            'alignment'         => array(self::READ_VALUE, 'w:jc'),
-            'basedOn'           => array(self::READ_VALUE, 'w:basedOn'),
-            'next'              => array(self::READ_VALUE, 'w:next'),
-            'indent'            => array(self::READ_VALUE, 'w:ind', 'w:left'),
-            'hanging'           => array(self::READ_VALUE, 'w:ind', 'w:hanging'),
-            'spaceAfter'        => array(self::READ_VALUE, 'w:spacing', 'w:after'),
-            'spaceBefore'       => array(self::READ_VALUE, 'w:spacing', 'w:before'),
-            'widowControl'      => array(self::READ_FALSE, 'w:widowControl'),
-            'keepNext'          => array(self::READ_TRUE,  'w:keepNext'),
-            'keepLines'         => array(self::READ_TRUE,  'w:keepLines'),
-            'pageBreakBefore'   => array(self::READ_TRUE,  'w:pageBreakBefore'),
-            'contextualSpacing' => array(self::READ_TRUE,  'w:contextualSpacing'),
-            'bidi'              => array(self::READ_TRUE,  'w:bidi'),
+            'styleName'           => array(self::READ_VALUE, array('w:pStyle', 'w:name')),
+            'alignment'           => array(self::READ_VALUE, 'w:jc'),
+            'basedOn'             => array(self::READ_VALUE, 'w:basedOn'),
+            'next'                => array(self::READ_VALUE, 'w:next'),
+            'indent'              => array(self::READ_VALUE, 'w:ind', 'w:left'),
+            'hanging'             => array(self::READ_VALUE, 'w:ind', 'w:hanging'),
+            'spaceAfter'          => array(self::READ_VALUE, 'w:spacing', 'w:after'),
+            'spaceBefore'         => array(self::READ_VALUE, 'w:spacing', 'w:before'),
+            'widowControl'        => array(self::READ_FALSE, 'w:widowControl'),
+            'keepNext'            => array(self::READ_TRUE,  'w:keepNext'),
+            'keepLines'           => array(self::READ_TRUE,  'w:keepLines'),
+            'pageBreakBefore'     => array(self::READ_TRUE,  'w:pageBreakBefore'),
+            'contextualSpacing'   => array(self::READ_TRUE,  'w:contextualSpacing'),
+            'bidi'                => array(self::READ_TRUE,  'w:bidi'),
+            'suppressAutoHyphens' => array(self::READ_TRUE,  'w:suppressAutoHyphens'),
         );
 
         return $this->readStyleDefs($xmlReader, $styleNode, $styleDefs);
@@ -578,7 +579,7 @@ protected function readStyleDefs(XMLReader $xmlReader, \DOMElement $parentNode =
      *
      * @param string $method
      * @ignoreScrutinizerPatch
-     * @param mixed $attributeValue
+     * @param string|null $attributeValue
      * @param mixed $expected
      * @return mixed
      */

src/PhpWord/Reader/Word2007/Settings.php

@@ -29,7 +29,18 @@
  */
 class Settings extends AbstractPart
 {
-    private static $booleanProperties = array('hideSpellingErrors', 'hideGrammaticalErrors', 'trackRevisions', 'doNotTrackMoves', 'doNotTrackFormatting', 'evenAndOddHeaders');
+    private static $booleanProperties = array(
+        'mirrorMargins',
+        'hideSpellingErrors',
+        'hideGrammaticalErrors',
+        'trackRevisions',
+        'doNotTrackMoves',
+        'doNotTrackFormatting',
+        'evenAndOddHeaders',
+        'updateFields',
+        'autoHyphenation',
+        'doNotHyphenateCaps',
+    );
 
     /**
      * Read settings.xml.
@@ -157,4 +168,32 @@ protected function setRevisionView(XMLReader $xmlReader, PhpWord $phpWord, \DOME
         $revisionView->setInkAnnotations(filter_var($xmlReader->getAttribute('w:inkAnnotations', $node), FILTER_VALIDATE_BOOLEAN));
         $phpWord->getSettings()->setRevisionView($revisionView);
     }
+
+    /**
+     * @param XMLReader $xmlReader
+     * @param PhpWord $phpWord
+     * @param \DOMElement $node
+     */
+    protected function setConsecutiveHyphenLimit(XMLReader $xmlReader, PhpWord $phpWord, \DOMElement $node)
+    {
+        $value = $xmlReader->getAttribute('w:val', $node);
+
+        if ($value !== null) {
+            $phpWord->getSettings()->setConsecutiveHyphenLimit($value);
+        }
+    }
+
+    /**
+     * @param XMLReader $xmlReader
+     * @param PhpWord $phpWord
+     * @param \DOMElement $node
+     */
+    protected function setHyphenationZone(XMLReader $xmlReader, PhpWord $phpWord, \DOMElement $node)
+    {
+        $value = $xmlReader->getAttribute('w:val', $node);
+
+        if ($value !== null) {
+            $phpWord->getSettings()->setHyphenationZone($value);
+        }
+    }
 }

src/PhpWord/Shared/Html.php

@@ -252,7 +252,7 @@ private static function parseText($node, $element, &$styles)
         $styles['font'] = self::recursiveParseStylesInHierarchy($node, $styles['font']);
 
         //alignment applies on paragraph, not on font. Let's copy it there
-        if (isset($styles['font']['alignment'])) {
+        if (isset($styles['font']['alignment']) && is_array($styles['paragraph'])) {
             $styles['paragraph']['alignment'] = $styles['font']['alignment'];
         }