Add support for Track changes (#1262)

* add changed information to HTML writer
* add missing writeFontStyle
* refactor track changes
* set the style
* update documentation and release note
* Update the changelog and doc
* fix scrutinizer issues

Author: troosan

CHANGELOG.md

@@ -8,6 +8,7 @@ v0.15.0 (?? ??? 2018)
 ### Added
 - Parsing of "align" HTML attribute - @troosan #1231
 - Parse formatting inside HTML lists - @troosan @samimussbach #1239 #945 #1215 #508
+- Add support for Track changes @Cip @troosan #354 #1262
 
 ### Fixed
 - fix reading of docx default style - @troosan #1238

docs/elements.rst

@@ -31,7 +31,7 @@ column shows the containers while the rows lists the elements.
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
 | 11    | Watermark       | -         | v        | -        | -       | -          | -          |
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
-| 12    | Object          | v         | v        | v        | v       | v          | v          |
+| 12    | OLEObject       | v         | v        | v        | v       | v          | v          |
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
 | 13    | TOC             | v         | -        | -        | -       | -          | -          |
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
@@ -77,6 +77,13 @@ italics, etc) or other elements, e.g. images or links. The syntaxes are as follo
 
 For available styling options see :ref:`font-style` and :ref:`paragraph-style`.
 
+If you want to enable track changes on added text you can mark it as INSERTED or DELETED by a specific user at a given time:
+
+.. code-block:: php
+
+    $text = $section->addText('Hello World!');
+    $text->setChanged(\PhpOffice\PhpWord\Element\ChangedElement::TYPE_INSERTED, 'Fred', (new \DateTime()));
+
 Titles
 ~~~~~~
 
@@ -276,11 +283,11 @@ Objects
 -------
 
 You can add OLE embeddings, such as Excel spreadsheets or PowerPoint
-presentations to the document by using ``addObject`` method.
+presentations to the document by using ``addOLEObject`` method.
 
 .. code-block:: php
 
-    $section->addObject($src, [$style]);
+    $section->addOLEObject($src, [$style]);
 
 Table of contents
 -----------------
@@ -309,7 +316,7 @@ Footnotes & endnotes
 You can create footnotes with ``addFootnote`` and endnotes with
 ``addEndnote`` in texts or textruns, but it's recommended to use textrun
 to have better layout. You can use ``addText``, ``addLink``,
-``addTextBreak``, ``addImage``, ``addObject`` on footnotes and endnotes.
+``addTextBreak``, ``addImage``, ``addOLEObject`` on footnotes and endnotes.
 
 On textrun:
 
@@ -465,4 +472,28 @@ The comment can contain formatted text. Once the comment has been added, it can
     // link the comment to the text you just created
     $text->setCommentStart($comment);
 
-If no end is set for a comment using the ``setCommentEnd``, the comment will be ended automatically at the end of the element it is started on.
+If no end is set for a comment using the ``setCommentEnd``, the comment will be ended automatically at the end of the element it is started on.
+
+Track Changes
+-------------
+
+Track changes can be set on text elements. There are 2 ways to set the change information on an element.
+Either by calling the `setChangeInfo()`, or by setting the `TrackChange` instance on the element with `setTrackChange()`.
+
+.. code-block:: php
+    $phpWord = new \PhpOffice\PhpWord\PhpWord();
+
+    // New portrait section
+    $section = $phpWord->addSection();
+    $textRun = $section->addTextRun();
+
+    $text = $textRun->addText('Hello World! Time to ');
+
+    $text = $textRun->addText('wake ', array('bold' => true));
+    $text->setChangeInfo(TrackChange::INSERTED, 'Fred', time() - 1800);
+
+    $text = $textRun->addText('up');
+    $text->setTrackChange(new TrackChange(TrackChange::INSERTED, 'Fred'));
+
+    $text = $textRun->addText('go to sleep');
+    $text->setChangeInfo(TrackChange::DELETED, 'Barney', new \DateTime('@' . (time() - 3600)));

samples/Sample_16_Object.php

@@ -9,7 +9,7 @@
 $section = $phpWord->addSection();
 $section->addText('You can open this OLE object by double clicking on the icon:');
 $section->addTextBreak(2);
-$section->addObject('resources/_sheet.xls');
+$section->addOLEObject('resources/_sheet.xls');
 
 // Save file
 echo write($phpWord, basename(__FILE__, '.php'), $writers);

samples/Sample_39_TrackChanges.php

@@ -0,0 +1,29 @@
+<?php
+use PhpOffice\PhpWord\Element\TrackChange;
+
+include_once 'Sample_Header.php';
+
+// New Word Document
+echo date('H:i:s') , ' Create new PhpWord object' , EOL;
+$phpWord = new \PhpOffice\PhpWord\PhpWord();
+
+// New portrait section
+$section = $phpWord->addSection();
+$textRun = $section->addTextRun();
+
+$text = $textRun->addText('Hello World! Time to ');
+
+$text = $textRun->addText('wake ', array('bold' => true));
+$text->setChangeInfo(TrackChange::INSERTED, 'Fred', time() - 1800);
+
+$text = $textRun->addText('up');
+$text->setTrackChange(new TrackChange(TrackChange::INSERTED, 'Fred'));
+
+$text = $textRun->addText('go to sleep');
+$text->setChangeInfo(TrackChange::DELETED, 'Barney', new \DateTime('@' . (time() - 3600)));
+
+// Save file
+echo write($phpWord, basename(__FILE__, '.php'), $writers);
+if (!CLI) {
+    include_once 'Sample_Footer.php';
+}

samples/resources/Sample_11_ReadWord2007.docx

@@ -81,7 +81,7 @@ public function __call($function, $args)
     {
         $elements = array(
             'Text', 'TextRun', 'Bookmark', 'Link', 'PreserveText', 'TextBreak',
-            'ListItem', 'ListItemRun', 'Table', 'Image', 'Object',
+            'ListItem', 'ListItemRun', 'Table', 'Image', 'Object', 'OLEObject',
             'Footnote', 'Endnote', 'CheckBox', 'TextBox', 'Field',
             'Line', 'Shape', 'Title', 'TOC', 'PageBreak',
             'Chart', 'FormField', 'SDT', 'Comment',
@@ -157,7 +157,7 @@ protected function addElement($elementName)
     /**
      * Get all elements
      *
-     * @return array
+     * @return \PhpOffice\PhpWord\Element\AbstractElement[]
      */
     public function getElements()
     {

samples/resources/Sample_24_ReadODText.odt

@@ -93,6 +93,13 @@ abstract class AbstractElement
      */
     private $nestedLevel = 0;
 
+    /**
+     * changed element info
+     *
+     * @var TrackChange
+     */
+    private $trackChange;
+
     /**
      * Parent container type
      *
@@ -425,6 +432,38 @@ protected function setNewStyle($styleObject, $styleValue = null, $returnObject =
         return $style;
     }
 
+    /**
+     * Sets the trackChange information
+     *
+     * @param TrackChange $trackChange
+     */
+    public function setTrackChange(TrackChange $trackChange)
+    {
+        $this->trackChange = $trackChange;
+    }
+
+    /**
+     * Gets the trackChange information
+     *
+     * @return TrackChange
+     */
+    public function getTrackChange()
+    {
+        return $this->trackChange;
+    }
+
+    /**
+     * Set changed
+     *
+     * @param string $type INSERTED|DELETED
+     * @param string $author
+     * @param null|int|\DateTime $date allways in UTC
+     */
+    public function setChangeInfo($type, $author, $date = null)
+    {
+        $this->trackChange = new TrackChange($type, $author, $date);
+    }
+
     /**
      * Set enum value
      *

src/PhpWord/Element/AbstractContainer.php

@@ -55,12 +55,12 @@ class Comment extends TrackChange
      * Create a new Comment Element
      *
      * @param string $author
-     * @param \DateTime $date
+     * @param null|\DateTime $date
      * @param string $initials
      */
     public function __construct($author, $date = null, $initials = null)
     {
-        parent::__construct($author, $date);
+        parent::__construct(null, $author, $date);
         $this->initials = $initials;
     }
 

src/PhpWord/Element/AbstractElement.php

@@ -20,14 +20,25 @@
 /**
  * TrackChange element
  * @see http://datypic.com/sc/ooxml/t-w_CT_TrackChange.html
+ * @see http://datypic.com/sc/ooxml/t-w_CT_RunTrackChange.html
  */
 class TrackChange extends AbstractContainer
 {
+    const INSERTED = 'INSERTED';
+    const DELETED = 'DELETED';
+
     /**
      * @var string Container type
      */
     protected $container = 'TrackChange';
 
+    /**
+     * The type of change, (insert or delete), not applicable for PhpOffice\PhpWord\Element\Comment
+     *
+     * @var string
+     */
+    private $changeType;
+
     /**
      * Author
      *
@@ -45,13 +56,17 @@ class TrackChange extends AbstractContainer
     /**
      * Create a new TrackChange Element
      *
+     * @param string $changeType
      * @param string $author
-     * @param \DateTime $date
+     * @param null|int|\DateTime $date
      */
-    public function __construct($author, \DateTime $date = null)
+    public function __construct($changeType = null, $author = null, $date = null)
     {
+        $this->changeType = $changeType;
         $this->author = $author;
-        $this->date = $date;
+        if ($date !== null) {
+            $this->date = ($date instanceof \DateTime) ? $date : new \DateTime('@' . $date);
+        }
     }
 
     /**
@@ -73,4 +88,14 @@ public function getDate()
     {
         return $this->date;
     }
+
+    /**
+     * Get the Change type
+     *
+     * @return string
+     */
+    public function getChangeType()
+    {
+        return $this->changeType;
+    }
 }