New drawing shapes (arc, curve, line, polyline, rect, oval)

CHANGELOG.md

@@ -6,7 +6,7 @@ This is the changelog between releases of PHPWord. Releases are listed in revers
 
 ### Features
 
-None yet.
+- Element: Ability to add drawing shapes (arc, curve, line, polyline, rect, oval) using new `Shape` element - @ivanlanin GH-123
 
 ### Bugfixes
 

docs/elements.rst

@@ -47,6 +47,8 @@ column shows the containers while the rows lists the elements.
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
 | 19    | Line            | v         | v        | v        | v       | v          | v          |
 +-------+-----------------+-----------+----------+----------+---------+------------+------------+
+| 20    | Shapes          | v         | v        | v        | v       | v          | v          |
++-------+-----------------+-----------+----------+----------+---------+------------+------------+
 
 Legend:
 
@@ -490,7 +492,12 @@ Fields
 
 To be completed
 
-Line
+Lines
+-----
+
+To be completed
+
+Shapes
 ------
 
 To be completed

docs/intro.rst

@@ -99,11 +99,11 @@ Writers
 +---------------------------+----------------------+--------+-------+-------+--------+-------+
 |                           | Endnote              | ✓      |       |       | ✓      |       |
 +---------------------------+----------------------+--------+-------+-------+--------+-------+
-| **Graphs**                | 2D basic graphs      |        |       |       |        |       |
+| **Graphs**                | 2D basic graphs      | ✓      |       |       |        |       |
 +---------------------------+----------------------+--------+-------+-------+--------+-------+
 |                           | 2D advanced graphs   |        |       |       |        |       |
 +---------------------------+----------------------+--------+-------+-------+--------+-------+
-|                           | 3D graphs            |        |       |       |        |       |
+|                           | 3D graphs            | ✓      |       |       |        |       |
 +---------------------------+----------------------+--------+-------+-------+--------+-------+
 | **Math**                  | OMML support         |        |       |       |        |       |
 +---------------------------+----------------------+--------+-------+-------+--------+-------+

docs/src/documentation.md

@@ -36,6 +36,7 @@ Don't forget to change `code::` directive to `code-block::` in the resulting rst
     - [Textboxes](#textboxes)
     - [Fields](#fields)
     - [Lines](#lines)
+    - [Shapes](#shapes)
 - [Templates](#templates)
 - [Writers & readers](#writers-readers)
     - [OOXML](#ooxml)
@@ -101,9 +102,9 @@ Below are the supported features for each file formats.
 |                         | Footer             | ✓    |     |     |      |     |
 |                         | Footnote           | ✓    |     |     | ✓    |     |
 |                         | Endnote            | ✓    |     |     | ✓    |     |
-| **Graphs**              | 2D basic graphs    |      |     |     |      |     |
+| **Graphs**              | 2D basic graphs    | ✓    |     |     |      |     |
 |                         | 2D advanced graphs |      |     |     |      |     |
-|                         | 3D graphs          |      |     |     |      |     |
+|                         | 3D graphs          | ✓    |     |     |      |     |
 | **Math**                | OMML support       |      |     |     |      |     |
 |                         | MathML support     |      |     |     |      |     |
 | **Bonus**               | Encryption         |      |     |     |      |     |
@@ -465,6 +466,7 @@ Below are the matrix of element availability in each container. The column shows
 | 17  | TextBox       | v       | v      | v      | v    | -        | -        |
 | 18  | Field         | v       | v      | v      | v    | v        | v        |
 | 19  | Line          | v       | v      | v      | v    | v        | v        |
+| 20  | Shape         | v       | v      | v      | v    | v        | v        |
 
 Legend:
 
@@ -850,6 +852,10 @@ To be completed.
 
 To be completed.
 
+## Shapes
+
+To be completed.
+
 # Templates
 
 You can create a docx template with included search-patterns that can be replaced by any value you wish. Only single-line values can be replaced. To load a template file, use the `loadTemplate` method. After loading the docx template, you can use the `setValue` method to change the value of a search pattern. The search-pattern model is: `${search-pattern}`. It is not possible to add new PHPWord elements to a loaded template file.

phpmd.xml.dist

@@ -18,7 +18,7 @@
     <rule ref="rulesets/design.xml/NumberOfChildren">
         <!-- AbstractStyle needs more children (default: 15) -->
         <properties>
-            <property name="minimum" value="20" />
+            <property name="minimum" value="30" />
         </properties>
     </rule>
     <rule ref="rulesets/unusedcode.xml" />

samples/Sample_31_Shape.php

@@ -0,0 +1,82 @@
+<?php
+include_once 'Sample_Header.php';
+
+// New Word document
+echo date('H:i:s'), " Create new PhpWord object", EOL;
+
+$phpWord = new \PhpOffice\PhpWord\PhpWord();
+$phpWord->addTitleStyle(1, array('size' => 14, 'bold' => true));
+
+$section = $phpWord->addSection();
+
+// Arc
+$section->addTitle('Arc', 1);
+$section->addShape(
+    'arc',
+    array(
+        'points' => '-90 20',
+        'frame' => array('width' => 120, 'height' => 120),
+        'outline' => array('color' => '#333333', 'weight' => 2, 'startArrow' => 'oval', 'endArrow' => 'open'),
+    )
+);
+
+// Curve
+$section->addTitle('Curve', 1);
+$section->addShape(
+    'curve',
+    array(
+        'points' => '1,100 200,1 1,50 200,50', 'connector' => 'elbow',
+        'outline' => array('color' => '#66cc00', 'weight' => 2, 'dash' => 'dash', 'startArrow' => 'diamond', 'endArrow' => 'block'),
+    )
+);
+
+// Line
+$section->addTitle('Line', 1);
+$section->addShape(
+    'line',
+    array(
+        'points' => '1,1 150,30',
+        'outline' => array('color' => '#cc00ff', 'line' => 'thickThin', 'weight' => 3, 'startArrow' => 'oval', 'endArrow' => 'classic'),
+    )
+);
+
+// Polyline
+$section->addTitle('Polyline', 1);
+$section->addShape(
+    'polyline',
+    array(
+        'points' => '1,30 20,10 55,20 75,10 100,40 115,50, 120,15 200,50',
+        'outline' => array('color' => '#cc6666', 'weight' => 2, 'startArrow' => 'none', 'endArrow' => 'classic'),
+    )
+);
+
+// Rectangle
+$section->addTitle('Rectangle', 1);
+$section->addShape(
+    'rect',
+    array(
+        'roundness' => 0.2,
+        'frame' => array('width' => 100, 'height' => 100, 'left' => 1, 'top' => 1),
+        'fill' => array('color' => '#FFCC33'),
+        'outline' => array('color' => '#990000', 'weight' => 1),
+        'shadow' => array(),
+    )
+);
+
+// Oval
+$section->addTitle('Oval', 1);
+$section->addShape(
+    'oval',
+    array(
+        'frame' => array('width' => 100, 'height' => 70, 'left' => 1, 'top' => 1),
+        'fill' => array('color' => '#33CC99'),
+        'outline' => array('color' => '#333333', 'weight' => 2),
+        'extrusion' => array(),
+    )
+);
+
+// Save file
+echo write($phpWord, basename(__FILE__, '.php'), $writers);
+if (!CLI) {
+    include_once 'Sample_Footer.php';
+}

src/PhpWord/Element/AbstractContainer.php

@@ -39,6 +39,7 @@
  * @method TextBox addTextBox($style = null)
  * @method Field addField($type = null, $properties = array(), $options = array())
  * @method Line addLine($lineStyle = null)
+ * @method Shape addObject($type, $style = null)
  *
  * @since 0.10.0
  */
@@ -74,7 +75,7 @@ public function __call($function, $args)
     {
         $elements = array('Text', 'TextRun', 'Link', 'PreserveText', 'TextBreak',
             'ListItem', 'ListItemRun', 'Table', 'Image', 'Object', 'Footnote',
-            'Endnote', 'CheckBox', 'TextBox', 'Field', 'Line');
+            'Endnote', 'CheckBox', 'TextBox', 'Field', 'Line', 'Shape');
         $functions = array();
         for ($i = 0; $i < count($elements); $i++) {
             $functions[$i] = 'add' . $elements[$i];
@@ -242,6 +243,7 @@ private function checkValidity($method)
             'Object'        => $allContainers,
             'Field'         => $allContainers,
             'Line'          => $allContainers,
+            'Shape'         => $allContainers,
             'TextRun'       => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),
             'ListItem'      => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),
             'ListItemRun'   => array('Section', 'Header', 'Footer', 'Cell', 'TextBox'),

src/PhpWord/Element/AbstractElement.php

@@ -262,4 +262,25 @@ protected function setStyle($styleObject, $styleValue = null, $returnObject = fa
 
         return $style;
     }
+
+    /**
+     * Set enum value
+     *
+     * @param mixed $value
+     * @param array $enum
+     * @param mixed $default
+     * @return mixed
+     * @throws \InvalidArgumentException
+     * @todo Merge with the same method in AbstractStyle
+     */
+    protected function setEnumVal($value = null, $enum = array(), $default = null)
+    {
+        if ($value != null && trim($value) != '' && !empty($enum) && !in_array($value, $enum)) {
+            throw new \InvalidArgumentException("Invalid style value: {$value}");
+        } elseif ($value === null || trim($value) == '') {
+            $value = $default;
+        }
+
+        return $value;
+    }
 }

src/PhpWord/Element/Shape.php

@@ -0,0 +1,88 @@
+<?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-2014 PHPWord contributors
+ * @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
+ */
+
+namespace PhpOffice\PhpWord\Element;
+
+use PhpOffice\PhpWord\Style\Shape as ShapeStyle;
+
+/**
+ * Shape element
+ *
+ * @since 0.12.0
+ */
+class Shape extends AbstractElement
+{
+    /**
+     * Shape type arc|curve|line|polyline|rect|oval
+     *
+     * @var string
+     */
+    private $type;
+
+    /**
+     * Shape style
+     *
+     * @var \PhpOffice\PhpWord\Style\Shape
+     */
+    private $style;
+
+    /**
+     * Create new instance
+     *
+     * @param string $type
+     * @param mixed $style
+     */
+    public function __construct($type, $style = null)
+    {
+        $this->setType($type);
+        $this->style = $this->setStyle(new ShapeStyle(), $style);
+    }
+
+    /**
+     * Get type
+     *
+     * @return string
+     */
+    public function getType()
+    {
+        return $this->type;
+    }
+
+    /**
+     * Set pattern
+     *
+     * @param string $value
+     * @return self
+     */
+    public function setType($value = null)
+    {
+        $enum = array('arc', 'curve', 'line', 'polyline', 'rect', 'oval');
+        $this->type = $this->setEnumVal($value, $enum, null);
+
+        return $this;
+    }
+
+    /**
+     * Get shape style
+     *
+     * @return \PhpOffice\PhpWord\Style\Shape
+     */
+    public function getStyle()
+    {
+        return $this->style;
+    }
+}

src/PhpWord/Style/AbstractStyle.php

@@ -264,7 +264,7 @@ protected function setFloatVal($value, $default = null)
     protected function setEnumVal($value = null, $enum = array(), $default = null)
     {
         if ($value != null && trim($value) != '' && !empty($enum) && !in_array($value, $enum)) {
-            throw new \InvalidArgumentException('Invalid style value.');
+            throw new \InvalidArgumentException("Invalid style value: {$value}");
         } elseif ($value === null || trim($value) == '') {
             $value = $default;
         }