Merge pull request #460 from PHPOffice/develop

v0.12.0

.gitignore

@@ -4,12 +4,16 @@
 .Trashes
 Thumbs.db
 Desktop.ini
-composer.phar
+.idea
+_build
 phpunit.xml
+composer.lock
+composer.phar
+vendor
+/report
+/samples/resources
+/samples/results
+/.settings
 phpword.ini
 /.buildpath
-/.idea
-/.project
-/.settings
-/build
-/vendor
+/.project

.travis.yml

@@ -1,7 +1,6 @@
 language: php
 
 php:
-    - 5.3.3
     - 5.3
     - 5.4
     - 5.5
@@ -10,6 +9,7 @@ php:
 
 matrix:
     allow_failures:
+        - php: 5.2
         - php: hhvm
 
 env:
@@ -23,17 +23,6 @@ before_script:
     ## Composer
     - composer self-update
     - composer install --prefer-source --dev
-    ## PHP Copy/Paste Detector
-    - curl -o phpcpd.phar https://phar.phpunit.de/phpcpd.phar
-    ## PHP Mess Detector
-    - pear config-set preferred_state beta
-    - printf "\n" | pecl install imagick
-    - pear channel-discover pear.phpmd.org
-    - pear channel-discover pear.pdepend.org
-    - pear install --alldeps phpmd/PHP_PMD
-    - phpenv rehash
-    ## PHPLOC
-    #- curl -o phploc.phar https://phar.phpunit.de/phploc.phar
     ## PHPDocumentor
     - mkdir -p build/docs
     - mkdir -p build/coverage
@@ -42,15 +31,15 @@ script:
     ## PHP_CodeSniffer
     - ./vendor/bin/phpcs src/ tests/ --standard=PSR2 -n --ignore=src/PhpWord/Shared/PCLZip
     ## PHP Copy/Paste Detector
-    - php phpcpd.phar src/ tests/ --verbose
+    - ./vendor/bin/phpcpd src/ tests/ --verbose
     ## PHP Mess Detector
-    - phpmd src/,tests/ text ./phpmd.xml.dist --exclude pclzip.lib.php
-    ## PHPLOC
-    #- php phploc.phar src/
+    - ./vendor/bin/phpmd src/,tests/ text ./phpmd.xml.dist --exclude pclzip.lib.php
     ## PHPUnit
-    - phpunit -c ./ --coverage-text --coverage-html ./build/coverage
+    - ./vendor/bin/phpunit -c ./ --coverage-text --coverage-html ./build/coverage
+    ## PHPLOC
+    - ./vendor/bin/phploc src/
     ## PHPDocumentor
-    - vendor/bin/phpdoc.php -q -d ./src -t ./build/docs --ignore "*/src/PhpWord/Shared/*/*" --template="responsive-twig"
+    - ./vendor/bin/phpdoc -q -d ./src -t ./build/docs --ignore "*/src/PhpWord/Shared/*/*" --template="responsive-twig"
 
 after_script:
     ## PHPDocumentor

CONTRIBUTING.md

@@ -1,14 +1,14 @@
 # Contributing to PHPWord
 
-PHPWord is build by the crowd and for the crowd. Every contributions are welcomed; either by [submitting](https://github.com/PHPOffice/PHPWord/issues) bug issues or suggesting improvements, or in a more active form like [requesting](https://github.com/PHPOffice/PHPWord/pulls) a pull.
+PHPWord is built by the crowd and for the crowd. Every contribution is welcome; either by [submitting](https://github.com/PHPOffice/PHPWord/issues) bug issues or suggesting improvements, or in a more active form like [requesting](https://github.com/PHPOffice/PHPWord/pulls) a pull.
 
-We want to create a high quality document writer and reader library that people can use with more confidence and less bugs. We want to collaborate happily, code joyfully, and get a life merrily. Thus, below are some guidelines that we expect to be followed by each contributor.
+We want to create a high quality document writer and reader library that people can use with more confidence and less bugs. We want to collaborate happily, code joyfully, and get alive merrily. Thus, below are some guidelines, that we expect to be followed by each contributor.
 
-- **Be brief, but be bold**: State your issues briefly, but speak out your ideas loudly, even if you can't or don't know how to implement it right away. The world will be better with limitless innovations.
-- **Code in PSR**: We use PHP Standards Recommendation (PSR) from as the PHP Framework Interoperability Group (PHP-FIG). If you're not familiar with this standard, please [familiarize yourself now](https://github.com/php-fig/fig-standards). Use [PHPCodeSniffer](http://pear.php.net/package/PHP_CodeSniffer/) to check your code against this standard.
-- **Test your code**: Nobody else knows your code better than you. So, please, test your own code before submitting your pull request. PHPWord uses [PHPUnit](http://phpunit.de/) as our testing framework.
-- **Request pull in separate branch**: Do not submit your request to the master branch, but create a separate branch named specifically for the issue that you addressed. Read [GitHub manual](https://help.github.com/articles/using-pull-requests) to find out more about this. If you are new to GitHub, read [this short manual](https://help.github.com/articles/fork-a-repo) to get you familiar with forks and how git works in general.
+- **Be brief, but be bold**. State your issues briefly. But speak out your ideas loudly, even if you can't or don't know how to implement it right away. The world will be better with limitless innovations.
+- **Follow PHP-FIG standards**. We follow PHP Standards Recommendations (PSRs) by [PHP Framework Interoperability Group](http://www.php-fig.org/). If you're not familiar with these standards, please, [familiarize yourself now](https://github.com/php-fig/fig-standards). Also, please, use [PHPCodeSniffer](http://pear.php.net/package/PHP_CodeSniffer/) to validate your code against PSRs.
+- **Test your code**. Nobody else knows your code better than you. So, it's completely yours mission to test the changes you made before pull request submission. We use [PHPUnit](https://phpunit.de/) for our testing purposes and recommend you using this tool too. [Here](https://phpunit.de/presentations.html) you can find PHPUnit best practices and additional information on effective unit testing, which helps us making PHPWord better day to day. Do not hesitate to smoke it carefully. It's a great investment in quality of your work, and it saves you years of life.
+- **Request pull in separate branch**. Do not submit your request to the master branch. But create a separate branch named specifically for the issue that you addressed. Read [GitHub manual](https://help.github.com/articles/using-pull-requests) to find out more about this. If you are new to GitHub, read [this short manual](https://help.github.com/articles/fork-a-repo) to get yourself familiar with forks and how git works in general. [This video](http://www.youtube.com/watch?v=-zvHQXnBO6c) explains how to synchronize your Github Fork with the Branch of PHPWord.
 
 That's it. Thank you for your interest in PHPWord, and welcome!
 
-May the Force be with you.
+May the Force be with you.

README.md

@@ -11,6 +11,16 @@ PHPWord is a library written in pure PHP that provides a set of classes to write
 
 PHPWord is an open source project licensed under the terms of [LGPL version 3](https://github.com/PHPOffice/PHPWord/blob/develop/COPYING.LESSER). PHPWord is aimed to be a high quality software product by incorporating [continuous integration](https://travis-ci.org/PHPOffice/PHPWord) and [unit testing](http://phpoffice.github.io/PHPWord/coverage/develop/). You can learn more about PHPWord by reading the [Developers' Documentation](http://phpword.readthedocs.org/) and the [API Documentation](http://phpoffice.github.io/PHPWord/docs/develop/).
 
+Read more about PHPWord:
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Getting started](#getting-started)
+- [Contributing](#contributing)
+- [Developers' Documentation](http://phpword.readthedocs.org/)
+- [API Documentation](http://phpoffice.github.io/PHPWord/docs/master/)
+
 ## Features
 
 With PHPWord, you can create DOCX, ODT, or RTF documents dynamically using your PHP 5.3+ scripts. Below are some of the things that you can do with PHPWord library:
@@ -30,6 +40,9 @@ With PHPWord, you can create DOCX, ODT, or RTF documents dynamically using your
 - Insert list items as bulleted, numbered, or multilevel
 - Insert hyperlinks
 - Insert footnotes and endnotes
+- 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)
 - Create document from templates
 - Use XSL 1.0 style sheets to transform main document part of OOXML template
 - ... and many more features on progress
@@ -67,55 +80,97 @@ require_once 'path/to/PhpWord/src/PhpWord/Autoloader.php';
 \PhpOffice\PhpWord\Autoloader::register();
 ```
 
-## Usages
+## Getting started
 
-The following is a basic example of the PHPWord library. More examples are provided in the [samples folder](samples/).
+The following is a basic usage example of the PHPWord library.
 
 ```php
-$phpWord = new \PhpOffice\PhpWord\PhpWord();
-
-// Every element you want to append to the word document is placed in a section.
-// To create a basic section:
-$section = $phpWord->addSection();
-
-// After creating a section, you can append elements:
-$section->addText('Hello world!');
+<?php
+require_once 'src/PhpWord/Autoloader.php';
+\PhpOffice\PhpWord\Autoloader::register();
 
-// You can directly style your text by giving the addText function an array:
-$section->addText('Hello world! I am formatted.',
-    array('name'=>'Tahoma', 'size'=>16, 'bold'=>true));
+// Creating the new document...
+$phpWord = new \PhpOffice\PhpWord\PhpWord();
 
-// If you often need the same style again you can create a user defined style
-// to the word document and give the addText function the name of the style:
-$phpWord->addFontStyle('myOwnStyle',
-    array('name'=>'Verdana', 'size'=>14, 'color'=>'1B2232'));
-$section->addText('Hello world! I am formatted by a user defined style',
-    'myOwnStyle');
+/* Note: any element you append to a document must reside inside of a Section. */
 
-// You can also put the appended element to local object like this:
+// Adding an empty Section to the document...
+$section = $phpWord->addSection();
+// Adding Text element to the Section having font styled by default...
+$section->addText(
+    htmlspecialchars(
+        '"Learn from yesterday, live for today, hope for tomorrow. '
+            . 'The important thing is not to stop questioning." '
+            . '(Albert Einstein)'
+    )
+);
+
+/*
+ * Note: it's possible to customize font style of the Text element you add in three ways:
+ * - inline;
+ * - using named font style (new font style object will be implicitly created);
+ * - using explicitly created font style object.
+ */
+
+// Adding Text element with font customized inline...
+$section->addText(
+    htmlspecialchars(
+        '"Great achievement is usually born of great sacrifice, '
+            . 'and is never the result of selfishness." '
+            . '(Napoleon Hill)'
+    ),
+    array('name' => 'Tahoma', 'size' => 10)
+);
+
+// Adding Text element with font customized using named font style...
+$fontStyleName = 'oneUserDefinedStyle';
+$phpWord->addFontStyle(
+    $fontStyleName,
+    array('name' => 'Tahoma', 'size' => 10, 'color' => '1B2232', 'bold' => true)
+);
+$section->addText(
+    htmlspecialchars(
+        '"The greatest accomplishment is not in never falling, '
+            . 'but in rising again after you fall." '
+            . '(Vince Lombardi)'
+    ),
+    $fontStyleName
+);
+
+// Adding Text element with font customized using explicitly created font style object...
 $fontStyle = new \PhpOffice\PhpWord\Style\Font();
 $fontStyle->setBold(true);
-$fontStyle->setName('Verdana');
-$fontStyle->setSize(22);
-$myTextElement = $section->addText('Hello World!');
+$fontStyle->setName('Tahoma');
+$fontStyle->setSize(13);
+$myTextElement = $section->addText(
+    htmlspecialchars('"Believe you can and you\'re halfway there." (Theodor Roosevelt)')
+);
 $myTextElement->setFontStyle($fontStyle);
 
-// Finally, write the document:
+// Saving the document as OOXML file...
 $objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'Word2007');
 $objWriter->save('helloWorld.docx');
 
+// Saving the document as ODF file...
 $objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'ODText');
 $objWriter->save('helloWorld.odt');
 
-$objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'RTF');
-$objWriter->save('helloWorld.rtf');
+// Saving the document as HTML file...
+$objWriter = \PhpOffice\PhpWord\IOFactory::createWriter($phpWord, 'HTML');
+$objWriter->save('helloWorld.html');
+
+/* Note: we skip RTF, because it's not XML-based and requires a different example. */
+/* Note: we skip PDF, because "HTML-to-PDF" approach is used to create PDF documents. */
 ```
+:warning: Escape any string you pass to OOXML/ODF/HTML document, otherwise it may get broken.
+
+More examples are provided in the [samples folder](samples/). You can also read the [Developers' Documentation](http://phpword.readthedocs.org/) and the [API Documentation](http://phpoffice.github.io/PHPWord/docs/master/) for more detail.
 
 ## Contributing
 
-We welcome everyone to contribute to PHPWord. Below are some of the things that you can do to contribute:
+We welcome everyone to contribute to PHPWord. Below are some of the things that you can do to contribute.
 
-- Read [our contributing guide](https://github.com/PHPOffice/PHPWord/blob/master/CONTRIBUTING.md)
-- [Fork us](https://github.com/PHPOffice/PHPWord/fork) and [request a pull](https://github.com/PHPOffice/PHPWord/pulls) to the [develop](https://github.com/PHPOffice/PHPWord/tree/develop) branch
-- Submit [bug reports or feature requests](https://github.com/PHPOffice/PHPWord/issues) to GitHub
-- Follow [@PHPWord](https://twitter.com/PHPWord) and [@PHPOffice](https://twitter.com/PHPOffice) on Twitter
+- Read [our contributing guide](https://github.com/PHPOffice/PHPWord/blob/master/CONTRIBUTING.md).
+- [Fork us](https://github.com/PHPOffice/PHPWord/fork) and [request a pull](https://github.com/PHPOffice/PHPWord/pulls) to the [develop](https://github.com/PHPOffice/PHPWord/tree/develop) branch.
+- Submit [bug reports or feature requests](https://github.com/PHPOffice/PHPWord/issues) to GitHub.
+- Follow [@PHPWord](https://twitter.com/PHPWord) and [@PHPOffice](https://twitter.com/PHPOffice) on Twitter.

VERSION

@@ -1 +1 @@
-0.11.1
+0.12.0

composer.json

@@ -2,7 +2,7 @@
     "name": "phpoffice/phpword",
     "description": "PHPWord - A pure PHP library for reading and writing word processing documents (DOCX, ODT, RTF, HTML, PDF)",
     "keywords": [
-        "PHP", "PhpOffice", "office", "PhpWord", "word", "template", "reader", "writer",
+        "PHP", "PhpOffice", "office", "PhpWord", "word", "template", "template processor", "reader", "writer",
         "docx", "OOXML", "OpenXML", "Office Open XML", "ISO IEC 29500", "WordprocessingML",
         "RTF", "Rich Text Format", "doc", "odt", "OpenDocument", "PDF", "HTML"
     ],
@@ -39,6 +39,9 @@
         "phpunit/phpunit": "3.7.*",
         "phpdocumentor/phpdocumentor":"2.*",
         "squizlabs/php_codesniffer": "1.*",
+        "phpmd/phpmd": "2.*",
+        "sebastian/phpcpd": "2.*",
+        "phploc/phploc": "2.*",
         "dompdf/dompdf":"0.6.*",
         "tecnick.com/tcpdf": "6.*",
         "mpdf/mpdf": "5.*"
@@ -47,7 +50,7 @@
         "ext-zip": "Used to write DOCX and ODT",
         "ext-gd2": "Used to add images",
         "ext-xmlwriter": "Used to write DOCX and ODT",
-        "ext-xsl": "Used to apply XSL style sheet to template part",
+        "ext-xsl": "Used to apply XSL style sheet to main document part of OOXML template",
         "dompdf/dompdf": "Used to write PDF"
     },
     "autoload": {