Allow to set "autoHyphenation" setting

CHANGELOG.md

@@ -14,6 +14,7 @@ v0.15.0 (?? ??? 2018)
 - Add support for Cell Spacing @dox07 @troosan #1040
 - Add parsing of formatting inside lists @atomicalnet @troosan #594
 - Add support for MACROBUTTON field @phryneas @troosan #1021
+- Add support for Hyphenation @Trainmaster (Document: `autoHyphenation`, `consecutiveHyphenLimit`, `hyphenationZone`, `doNotHyphenateCaps`, Paragraph: `suppressAutoHyphens`)
 
 ### Fixed
 - Fix reading of docx default style - @troosan #1238
@@ -475,4 +476,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

@@ -81,6 +81,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/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/Reader/Word2007/AbstractPart.php

@@ -333,20 +333,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);

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/Style/Paragraph.php

@@ -180,6 +180,13 @@ class Paragraph extends Border
      */
     private $textAlignment;
 
+    /**
+     * Suppress hyphenation for paragraph
+     *
+     * @var bool
+     */
+    private $suppressAutoHyphens = false;
+
     /**
      * Set Style value
      *
@@ -212,27 +219,28 @@ public function setStyleValue($key, $value)
     public function getStyleValues()
     {
         $styles = array(
-            'name'              => $this->getStyleName(),
-            'basedOn'           => $this->getBasedOn(),
-            'next'              => $this->getNext(),
-            'alignment'         => $this->getAlignment(),
-            'indentation'       => $this->getIndentation(),
-            'spacing'           => $this->getSpace(),
-            'pagination'        => array(
-                'widowControl'  => $this->hasWidowControl(),
-                'keepNext'      => $this->isKeepNext(),
-                'keepLines'     => $this->isKeepLines(),
-                'pageBreak'     => $this->hasPageBreakBefore(),
+            'name'                => $this->getStyleName(),
+            'basedOn'             => $this->getBasedOn(),
+            'next'                => $this->getNext(),
+            'alignment'           => $this->getAlignment(),
+            'indentation'         => $this->getIndentation(),
+            'spacing'             => $this->getSpace(),
+            'pagination'          => array(
+                'widowControl'    => $this->hasWidowControl(),
+                'keepNext'        => $this->isKeepNext(),
+                'keepLines'       => $this->isKeepLines(),
+                'pageBreak'       => $this->hasPageBreakBefore(),
             ),
-            'numbering'         => array(
-                'style'         => $this->getNumStyle(),
-                'level'         => $this->getNumLevel(),
+            'numbering'           => array(
+                'style'           => $this->getNumStyle(),
+                'level'           => $this->getNumLevel(),
             ),
-            'tabs'              => $this->getTabs(),
-            'shading'           => $this->getShading(),
-            'contextualSpacing' => $this->hasContextualSpacing(),
-            'bidi'              => $this->isBidi(),
-            'textAlignment'     => $this->getTextAlignment(),
+            'tabs'                => $this->getTabs(),
+            'shading'             => $this->getShading(),
+            'contextualSpacing'   => $this->hasContextualSpacing(),
+            'bidi'                => $this->isBidi(),
+            'textAlignment'       => $this->getTextAlignment(),
+            'suppressAutoHyphens' => $this->hasSuppressAutoHyphens(),
         );
 
         return $styles;
@@ -848,4 +856,20 @@ public function setTextAlignment($textAlignment)
 
         return $this;
     }
+
+    /**
+     * @return bool
+     */
+    public function hasSuppressAutoHyphens()
+    {
+        return $this->suppressAutoHyphens;
+    }
+
+    /**
+     * @param bool $suppressAutoHyphens
+     */
+    public function setSuppressAutoHyphens($suppressAutoHyphens)
+    {
+        $this->suppressAutoHyphens = (bool) $suppressAutoHyphens;
+    }
 }