Allow to set "autoHyphenation" setting

.scrutinizer.yml

@@ -1,3 +1,8 @@
+build:
+    nodes:
+        analysis:
+            tests:
+                override: [php-scrutinizer-run]
 filter:
     excluded_paths: [ 'vendor/*', 'tests/*', 'samples/*', 'src/PhpWord/Shared/PCLZip/*' ]
 

.travis.yml

@@ -15,12 +15,9 @@ matrix:
     include:
         - php: 5.6
           env: COVERAGE=1
-    allow_failures:
-        - php: 7.2
 
 cache:
     directories:
-        - vendor
         - $HOME/.composer/cache
         - .php-cs.cache
 
@@ -38,7 +35,7 @@ before_script:
     - if [ -z "$COVERAGE" ]; then phpenv config-rm xdebug.ini ; fi
     ## Composer
     - composer self-update
-    - composer install --prefer-source
+    - travis_wait composer install --prefer-source
     ## PHPDocumentor
     - mkdir -p build/docs
     - mkdir -p build/coverage

CHANGELOG.md

@@ -13,7 +13,9 @@ v0.15.0 (?? ??? 2018)
 - Add support for fixed Table Layout @aoloe @ekopach @troosan #841 #1276
 - Add support for Cell Spacing @dox07 @troosan #1040
 - 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
@@ -23,6 +25,7 @@ v0.15.0 (?? ??? 2018)
 - Fix parsing of `<w:br/>` tag. @troosan #1274
 - Bookmark are not writton as internal link in html writer @troosan #1263
 - It should be possible to add a Footnote in a ListItemRun @troosan #1287 #1287
+- Fix parsing of Heading and Title formating @troosan @gthomas2 #465
 
 ### Changed
 - Remove zend-stdlib dependency @Trainmaster #1284
@@ -475,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/elements.rst

@@ -89,6 +89,7 @@ Titles
 
 If you want to structure your document or build table of contents, you need titles or headings.
 To add a title to the document, use the ``addTitleStyle`` and ``addTitle`` method.
+If `depth` is 0, a Title will be inserted, otherwise a Heading1, Heading2, ...
 
 .. code-block:: php
 
@@ -98,7 +99,7 @@ To add a title to the document, use the ``addTitleStyle`` and ``addTitle`` metho
 - ``depth``.
 - ``$fontStyle``. See :ref:`font-style`.
 - ``$paragraphStyle``. See :ref:`paragraph-style`.
-- ``$text``. Text to be displayed in the document.
+- ``$text``. Text to be displayed in the document. This can be `string` or a `\PhpOffice\PhpWord\Element\TextRun`
 
 It's necessary to add a title style to your document because otherwise the title won't be detected as a real title.
 

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

@@ -59,6 +59,7 @@ Available Font style options:
    See ``\PhpOffice\PhpWord\Style\Font::UNDERLINE_...`` constants for more values
 - ``lang``. Language, either a language code like *en-US*, *fr-BE*, etc. or an object (or as an array) if you need to set eastAsian or bidirectional languages
    See ``\PhpOffice\PhpWord\Style\Language`` class for some language codes.
+- ``position``. The text position, raised or lowered, in half points
 
 .. _paragraph-style:
 
@@ -81,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*.

samples/Sample_17_TitleTOC.php

@@ -12,13 +12,14 @@
 // Define styles
 $fontStyle12 = array('spaceAfter' => 60, 'size' => 12);
 $fontStyle10 = array('size' => 10);
+$phpWord->addTitleStyle(null, array('size' => 22, 'bold' => true));
 $phpWord->addTitleStyle(1, array('size' => 20, 'color' => '333333', 'bold' => true));
 $phpWord->addTitleStyle(2, array('size' => 16, 'color' => '666666'));
 $phpWord->addTitleStyle(3, array('size' => 14, 'italic' => true));
 $phpWord->addTitleStyle(4, array('size' => 12));
 
 // Add text elements
-$section->addText('Table of contents 1');
+$section->addTitle('Table of contents 1', 0);
 $section->addTextBreak(2);
 
 // Add TOC #1

src/PhpWord/Collection/AbstractCollection.php

@@ -27,14 +27,14 @@ abstract class AbstractCollection
     /**
      * Items
      *
-     * @var array
+     * @var \PhpOffice\PhpWord\Element\AbstractContainer[]
      */
     private $items = array();
 
     /**
      * Get items
      *
-     * @return array
+     * @return \PhpOffice\PhpWord\Element\AbstractContainer[]
      */
     public function getItems()
     {
@@ -45,7 +45,7 @@ public function getItems()
      * Get item by index
      *
      * @param int $index
-     * @return mixed
+     * @return \PhpOffice\PhpWord\Element\AbstractContainer
      */
     public function getItem($index)
     {
@@ -60,7 +60,7 @@ public function getItem($index)
      * Set item.
      *
      * @param int $index
-     * @param mixed $item
+     * @param \PhpOffice\PhpWord\Element\AbstractContainer $item
      */
     public function setItem($index, $item)
     {
@@ -72,7 +72,7 @@ public function setItem($index, $item)
     /**
      * Add new item
      *
-     * @param mixed $item
+     * @param \PhpOffice\PhpWord\Element\AbstractContainer $item
      * @return int
      */
     public function addItem($item)

src/PhpWord/Element/AbstractContainer.php

@@ -54,7 +54,7 @@ abstract class AbstractContainer extends AbstractElement
     /**
      * Elements collection
      *
-     * @var array
+     * @var \PhpOffice\PhpWord\Element\AbstractElement[]
      */
     protected $elements = array();
 
@@ -164,6 +164,41 @@ public function getElements()
         return $this->elements;
     }
 
+    /**
+     * Returns the element at the requested position
+     *
+     * @param int $index
+     * @return \PhpOffice\PhpWord\Element\AbstractElement|null
+     */
+    public function getElement($index)
+    {
+        if (array_key_exists($index, $this->elements)) {
+            return $this->elements[$index];
+        }
+
+        return null;
+    }
+
+    /**
+     * Removes the element at requested index
+     *
+     * @param int|\PhpOffice\PhpWord\Element\AbstractElement $toRemove
+     */
+    public function removeElement($toRemove)
+    {
+        if (is_int($toRemove) && array_key_exists($toRemove, $this->elements)) {
+            unset($this->elements[$toRemove]);
+        } elseif ($toRemove instanceof \PhpOffice\PhpWord\Element\AbstractElement) {
+            foreach ($this->elements as $key => $element) {
+                if ($element->getElementId() === $toRemove->getElementId()) {
+                    unset($this->elements[$key]);
+
+                    return;
+                }
+            }
+        }
+    }
+
     /**
      * Count elements
      *

src/PhpWord/Element/Bookmark.php

@@ -43,7 +43,7 @@ class Bookmark extends AbstractElement
      *
      * @param string $name
      */
-    public function __construct($name)
+    public function __construct($name = '')
     {
         $this->name = CommonText::toUTF8($name);
     }

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/Element/ListItem.php

@@ -62,7 +62,7 @@ public function __construct($text, $depth = 0, $fontStyle = null, $listStyle = n
 
         // Version >= 0.10.0 will pass numbering style name. Older version will use old method
         if (!is_null($listStyle) && is_string($listStyle)) {
-            $this->style = new ListItemStyle($listStyle);
+            $this->style = new ListItemStyle($listStyle); // @codeCoverageIgnore
         } else {
             $this->style = $this->setNewStyle(new ListItemStyle(), $listStyle, true);
         }

src/PhpWord/Element/Title.php

@@ -28,7 +28,7 @@ class Title extends AbstractElement
     /**
      * Title Text content
      *
-     * @var string
+     * @var string|TextRun
      */
     private $text;
 
@@ -56,15 +56,25 @@ class Title extends AbstractElement
     /**
      * Create a new Title Element
      *
-     * @param string $text
+     * @param string|TextRun $text
      * @param int $depth
      */
     public function __construct($text, $depth = 1)
     {
-        $this->text = CommonText::toUTF8($text);
+        if (isset($text)) {
+            if (is_string($text)) {
+                $this->text = CommonText::toUTF8($text);
+            } elseif ($text instanceof TextRun) {
+                $this->text = $text;
+            } else {
+                throw new \InvalidArgumentException('Invalid text, should be a string or a TextRun');
+            }
+        }
+
         $this->depth = $depth;
-        if (array_key_exists("Heading_{$this->depth}", Style::getStyles())) {
-            $this->style = "Heading{$this->depth}";
+        $styleName = $depth === 0 ? 'Title' : "Heading_{$this->depth}";
+        if (array_key_exists($styleName, Style::getStyles())) {
+            $this->style = str_replace('_', '', $styleName);
         }
 
         return $this;