Add support for comments (PHPOffice#1067)

Just a writer for now, reader to be done

.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:https://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
  *