Add support for comments (#1067)

Just a writer for now, reader to be done

Author: troosan

.gitignore

@@ -6,6 +6,7 @@ Thumbs.db
 Desktop.ini
 .idea
 _build
+/build
 phpunit.xml
 composer.lock
 composer.phar

composer.json

@@ -42,6 +42,7 @@
     "require-dev": {
         "phpunit/phpunit": "3.7.*",
         "phpdocumentor/phpdocumentor":"2.*",
+        "twig/twig":"1.27",
         "squizlabs/php_codesniffer": "1.*",
         "phpmd/phpmd": "2.*",
         "phploc/phploc": "2.*",

docs/elements.rst

@@ -398,4 +398,27 @@ Available line style attributes:
 - ``endArrow``. End type of arrow: block, open, classic, diamond, oval.
 - ``width``. Line-object width in pt.
 - ``height``. Line-object height in pt.
-- ``flip``. Flip the line element: true, false.
+- ``flip``. Flip the line element: true, false.
+
+Comments
+---------
+
+Comments can be added to a document by using ``addComment``.
+The comment can contain formatted text. Once the comment has been added, it can be linked to any to any element.
+
+.. code-block:: php
+
+    // first create a comment
+    $comment= new \PhpOffice\PhpWord\Element\Comment('Authors name', new \DateTime(), 'my_initials');
+    $comment->addText('Test', array('bold' => true));
+
+    // add it to the document
+    $phpWord->addComment($comment);
+
+    $textrun = $section->addTextRun();
+    $textrun->addText('This ');
+    $text = $textrun->addText('is');
+    // 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.

docs/intro.rst

@@ -49,6 +49,7 @@ Features
 - Insert drawing shapes (arc, curve, line, polyline, rect, oval)
 - Insert charts (pie, doughnut, bar, line, area, scatter, radar)
 - Insert form fields (textinput, checkbox, and dropdown)
+- Insert comments
 - Create document from templates
 - Use XSL 1.0 style sheets to transform headers, main document part, and footers of an OOXML template
 - ... and many more features on progress
@@ -102,6 +103,8 @@ Writers
 +---------------------------+----------------------+--------+-------+-------+--------+-------+
 |                           | Endnote              | ✓      |       |       | ✓      |       |
 +---------------------------+----------------------+--------+-------+-------+--------+-------+
+|                           | Comments             | ✓      |       |       |        |       |
++---------------------------+----------------------+--------+-------+-------+--------+-------+
 | **Graphs**                | 2D basic graphs      | ✓      |       |       |        |       |
 +---------------------------+----------------------+--------+-------+-------+--------+-------+
 |                           | 2D advanced graphs   |        |       |       |        |       |
@@ -161,6 +164,8 @@ Readers
 +---------------------------+----------------------+--------+-------+-------+-------+-------+
 |                           | Endnote              | ✓      |       |       |       |       |
 +---------------------------+----------------------+--------+-------+-------+-------+-------+
+|                           | Comments             |        |       |       |       |       |
++---------------------------+----------------------+--------+-------+-------+-------+-------+
 | **Graphs**                | 2D basic graphs      |        |       |       |       |       |
 +---------------------------+----------------------+--------+-------+-------+-------+-------+
 |                           | 2D advanced graphs   |        |       |       |       |       |

samples/Sample_37_Comments.php

@@ -0,0 +1,63 @@
+<?php
+include_once 'Sample_Header.php';
+
+// New Word Document
+echo date('H:i:s') , ' Create new PhpWord object' , EOL;
+$phpWord = new \PhpOffice\PhpWord\PhpWord();
+
+// A comment
+$comment = new \PhpOffice\PhpWord\Element\Comment('Authors name', new \DateTime(), 'my_initials');
+$comment->addText('Test', array('bold' => true));
+$phpWord->addComment($comment);
+
+$section = $phpWord->addSection();
+
+$textrun = $section->addTextRun();
+$textrun->addText('This ');
+$text = $textrun->addText('is');
+$text->setCommentRangeStart($comment);
+$textrun->addText(' a test');
+
+$section->addTextBreak(2);
+
+// Let's create a comment that we will link to a start element and an end element
+$commentWithStartAndEnd = new \PhpOffice\PhpWord\Element\Comment('Foo Bar', new \DateTime(), '');
+$commentWithStartAndEnd->addText('A comment with a start and an end');
+$phpWord->addComment($commentWithStartAndEnd);
+
+$textrunWithEnd = $section->addTextRun();
+$textrunWithEnd->addText('This ');
+$textToStartOn = $textrunWithEnd->addText('is', array('bold' => true));
+$textToStartOn->setCommentRangeStart($commentWithStartAndEnd);
+$textrunWithEnd->addText(' another', array('italic' => true));
+$textToEndOn = $textrunWithEnd->addText(' test');
+$textToEndOn->setCommentRangeEnd($commentWithStartAndEnd);
+
+$section->addTextBreak(2);
+
+// Let's add a comment on an image
+$commentOnImage = new \PhpOffice\PhpWord\Element\Comment('Mr Smart', new \DateTime(), '');
+$imageComment = $commentOnImage->addTextRun();
+$imageComment->addText('Hey, Mars does look ');
+$imageComment->addText('red', array('color' => 'FF0000'));
+$phpWord->addComment($commentOnImage);
+$image = $section->addImage('resources/_mars.jpg');
+$image->setCommentRangeStart($commentOnImage);
+
+$section->addTextBreak(2);
+
+// We can also do things the other way round, link the comment to the element
+$anotherText = $section->addText("another text");
+
+$comment1 = new \PhpOffice\PhpWord\Element\Comment('Authors name', new \DateTime(), 'my_initials');
+$comment1->addText('Test', array('bold' => true));
+$comment1->setStartElement($anotherText);
+$comment1->setEndElement($anotherText);
+$phpWord->addComment($comment1);
+
+
+// Save file
+echo write($phpWord, basename(__FILE__, '.php'), $writers);
+if (!CLI) {
+    include_once 'Sample_Footer.php';
+}

src/PhpWord/Collection/Comments.php

@@ -0,0 +1,27 @@
+<?php
+/**
+ * This file is part of PHPWord - A pure PHP library for reading and writing
+ * word processing documents.
+ *
+ * PHPWord is free software distributed under the terms of the GNU Lesser
+ * General Public License version 3 as published by the Free Software Foundation.
+ *
+ * For the full copyright and license information, please read the LICENSE
+ * file that was distributed with this source code. For the full list of
+ * contributors, visit https://github.com/PHPOffice/PHPWord/contributors.
+ *
+ * @link        https://github.com/PHPOffice/PHPWord
+ * @copyright   2010-2016 PHPWord contributors
+ * @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
+ */
+
+namespace PhpOffice\PhpWord\Collection;
+
+/**
+ * Comments collection
+ *
+ * @since 0.12.0
+ */
+class Comments extends AbstractCollection
+{
+}

src/PhpWord/Element/AbstractContainer.php

@@ -58,7 +58,7 @@ abstract class AbstractContainer extends AbstractElement
     protected $elements = array();
 
     /**
-     * Container type Section|Header|Footer|Footnote|Endnote|Cell|TextRun|TextBox|ListItemRun
+     * Container type Section|Header|Footer|Footnote|Endnote|Cell|TextRun|TextBox|ListItemRun|TrackChange
      *
      * @var string
      */
@@ -83,7 +83,7 @@ public function __call($function, $args)
             'ListItem', 'ListItemRun', 'Table', 'Image', 'Object',
             'Footnote', 'Endnote', 'CheckBox', 'TextBox', 'Field',
             'Line', 'Shape', 'Title', 'TOC', 'PageBreak',
-            'Chart', 'FormField', 'SDT'
+            'Chart', 'FormField', 'SDT', 'Comment'
         );
         $functions = array();
         foreach ($elements as $element) {
@@ -188,7 +188,7 @@ public function countElements()
     private function checkValidity($method)
     {
         $generalContainers = array(
-            'Section', 'Header', 'Footer', 'Footnote', 'Endnote', 'Cell', 'TextRun', 'TextBox', 'ListItemRun',
+            'Section', 'Header', 'Footer', 'Footnote', 'Endnote', 'Cell', 'TextRun', 'TextBox', 'ListItemRun', 'TrackChange',
         );
 
         $validContainers = array(
@@ -203,7 +203,8 @@ private function checkValidity($method)
             'Shape'         => $generalContainers,
             'FormField'     => $generalContainers,
             'SDT'           => $generalContainers,
-            'TextRun'       => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),
+            'TrackChange'   => $generalContainers,
+            'TextRun'       => array('Section', 'Header', 'Footer', 'Cell', 'TextBox', 'TrackChange'),
             'ListItem'      => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),
             'ListItemRun'   => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),
             'Table'         => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),

src/PhpWord/Element/AbstractElement.php

@@ -108,12 +108,26 @@ abstract class AbstractElement
     protected $mediaRelation = false;
 
     /**
-     * Is part of collection; true for Title, Footnote, Endnote, and Chart
+     * Is part of collection; true for Title, Footnote, Endnote, Chart, and Comment
      *
      * @var bool
      */
     protected $collectionRelation = false;
 
+    /**
+     * The start position for the linked comment
+     * 
+     * @var Comment
+     */
+    protected $commentRangeStart;
+
+    /**
+     * The end position for the linked comment
+     * 
+     * @var Comment
+     */
+    protected $commentRangeEnd;
+
     /**
      * Get PhpWord
      *
@@ -265,6 +279,55 @@ public function getNestedLevel()
         return $this->nestedLevel;
     }
 
+    /**
+     * Get comment start
+     *
+     * @return Comment
+     */
+    public function getCommentRangeStart()
+    {
+        return $this->commentRangeStart;
+    }
+
+    /**
+     * Set comment start
+     * 
+     * @param Comment $value
+     */
+    public function setCommentRangeStart(Comment $value)
+    {
+        if ($this instanceof Comment) {
+            throw new \InvalidArgumentException("Cannot set a Comment on a Comment");
+        }
+        $this->commentRangeStart= $value;
+        $this->commentRangeStart->setStartElement($this);
+    }
+
+    /**
+     * Get comment end
+     *
+     * @return Comment
+     */
+    public function getCommentRangeEnd()
+    {
+        return $this->commentRangeEnd;
+    }
+
+    /**
+     * Set comment end
+     *
+     * @param Comment $value
+     * @return void
+     */
+    public function setCommentRangeEnd(Comment $value)
+    {
+        if ($this instanceof Comment) {
+            throw new \InvalidArgumentException("Cannot set a Comment on a Comment");
+        }
+        $this->commentRangeEnd= $value;
+        $this->commentRangeEnd->setEndElement($this);
+    }
+
     /**
      * Set parent container
      *