Merge remote-tracking branch 'github_troosan/footnote_properties' into develop

README.md

@@ -1,5 +1,7 @@
 # ![PHPWord](https://rawgit.com/PHPOffice/PHPWord/develop/docs/images/phpword.svg "PHPWord")
 
+## :mag_right: PHPWord is looking for a new maintainer :crown: :pencil: ([#948](https://github.com/PHPOffice/PHPWord/issues/948)) 
+
 [![Latest Stable Version](https://poser.pugx.org/phpoffice/phpword/v/stable.png)](https://packagist.org/packages/phpoffice/phpword)
 [![Build Status](https://travis-ci.org/PHPOffice/PHPWord.svg?branch=master)](https://travis-ci.org/PHPOffice/PHPWord)
 [![Code Quality](https://scrutinizer-ci.com/g/PHPOffice/PHPWord/badges/quality-score.png?s=b5997ce59ac2816b4514f3a38de9900f6d492c1d)](https://scrutinizer-ci.com/g/PHPOffice/PHPWord/)

docs/elements.rst

@@ -333,11 +333,28 @@ On text:
     $footnote = $section->addFootnote();
     $footnote->addText('Footnote text.');
 
-The footnote reference number will be displayed with decimal number
+By default the footnote reference number will be displayed with decimal number
-starting from 1. This number use ``FooterReference`` style which you can
+starting from 1. This number uses the ``FooterReference`` style which you can
-redefine by ``addFontStyle`` method. Default value for this style is
+redefine with the ``addFontStyle`` method. Default value for this style is
 ``array('superScript' => true)``;
 
+The footnote numbering can be controlled by setting the FootnoteProperties on the Section.
+
+.. code-block:: php
+
+    $fp = new PhpWord\SimpleType\FootnoteProperties();
+    //sets the position of the footnote (pageBottom (default), beneathText, sectEnd, docEnd) 
+    $fp->setPos(FootnoteProperties::POSITION_DOC_END);
+    //set the number format to use (decimal (default), upperRoman, upperLetter, ...)
+    $fp->setNumFmt(FootnoteProperties::NUMBER_FORMAT_LOWER_ROMAN);
+    //force starting at other than 1
+    $fp->setNumStart(2);
+    //when to restart counting (continuous (default), eachSect, eachPage)
+    $fp->setNumRestart(FootnoteProperties::RESTART_NUMBER_EACH_PAGE);
+    
+    //And finaly, set it on the Section
+    $section->setFootnoteProperties($properties);
+
 Checkboxes
 ----------
 

samples/Sample_06_Footnote.php

@@ -1,4 +1,6 @@
 <?php
+use PhpOffice\PhpWord\SimpleType\FootnoteProperties;
+
 include_once 'Sample_Header.php';
 
 // New Word Document
@@ -42,11 +44,15 @@ $footnote->addText('But you can only put footnote in section, not in header or f
 
 $section->addText(
     'You can also create the footnote directly from the section making it wrap in a paragraph '
-        . 'like the footnote below this paragraph. But is is best used from within a textrun.'
+        . 'like the footnote below this paragraph. But is best used from within a textrun.'
 );
 $footnote = $section->addFootnote();
 $footnote->addText('The reference for this is wrapped in its own line');
 
+$footnoteProperties = new FootnoteProperties();
+$footnoteProperties->setNumFmt(FootnoteProperties::NUMBER_FORMAT_UPPER_ROMAN);
+$section->setFootnoteProperties($footnoteProperties);
+
 // Save file
 echo write($phpWord, basename(__FILE__, '.php'), $writers);
 if (!CLI) {

src/PhpWord/Element/Section.php

@@ -18,6 +18,7 @@
 namespace PhpOffice\PhpWord\Element;
 
 use PhpOffice\PhpWord\Style\Section as SectionStyle;
+use PhpOffice\PhpWord\SimpleType\FootnoteProperties;
 
 class Section extends AbstractContainer
 {
@@ -47,6 +48,13 @@ class Section extends AbstractContainer
      */
     private $footers = array();
 
+    /**
+     * The properties for the footnote of this section
+     * 
+     * @var FootnoteProperties
+     */
+    private $footnoteProperties;
+
     /**
      * Create new instance
      *
@@ -138,6 +146,26 @@ class Section extends AbstractContainer
         return $this->footers;
     }
 
+    /**
+     * Get the footnote properties
+     * 
+     * @return \PhpOffice\PhpWord\Element\FooterProperties
+     */
+    public function getFootnotePropoperties()
+    {
+        return $this->footnoteProperties;
+    }
+
+    /**
+     * Set the footnote properties
+     * 
+     * @param FootnoteProperties $footnoteProperties
+     */
+    public function setFootnoteProperties(FootnoteProperties $footnoteProperties = null)
+    {
+        $this->footnoteProperties = $footnoteProperties;
+    }
+
     /**
      * Is there a header for this section that is for the first page only?
      *

src/PhpWord/SimpleType/FootnoteProperties.php

@@ -0,0 +1,152 @@
+<?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\SimpleType;
+
+/**
+ * Footnote properties
+ *
+ * @see http://www.datypic.com/sc/ooxml/e-w_footnotePr-1.html
+ */
+final class FootnoteProperties
+{
+
+    const RESTART_NUMBER_CONTINUOUS = 'continuous';
+    const RESTART_NUMBER_EACH_SECTION = 'eachSect';
+    const RESTART_NUMBER_EACH_PAGE = 'eachPage';
+
+    const RESTART_NUMBER = array(
+        self::RESTART_NUMBER_CONTINUOUS,
+        self::RESTART_NUMBER_EACH_SECTION,
+        self::RESTART_NUMBER_EACH_PAGE
+    );
+
+    const NUMBER_FORMAT_DECIMAL = 'decimal';
+    const NUMBER_FORMAT_UPPER_ROMAN = 'upperRoman';
+    const NUMBER_FORMAT_LOWER_ROMAN = 'lowerRoman';
+    const NUMBER_FORMAT_UPPER_LETTER = 'upperLetter';
+    const NUMBER_FORMAT_LOWER_LETTER = 'lowerLetter';
+    const NUMBER_FORMAT_ORDINAL = 'ordinal';
+    const NUMBER_FORMAT_CARDINAL_TEXT = 'cardinalText';
+    const NUMBER_FORMAT_ORDINAL_TEXT = 'ordinalText';
+    const NUMBER_FORMAT_NONE = 'none';
+    const NUMBER_FORMAT_BULLET = 'bullet';
+
+    const NUMBER_FORMAT = array(
+        self::NUMBER_FORMAT_DECIMAL,
+        self::NUMBER_FORMAT_UPPER_ROMAN,
+        self::NUMBER_FORMAT_LOWER_ROMAN,
+        self::NUMBER_FORMAT_UPPER_LETTER,
+        self::NUMBER_FORMAT_LOWER_LETTER,
+        self::NUMBER_FORMAT_ORDINAL,
+        self::NUMBER_FORMAT_CARDINAL_TEXT,
+        self::NUMBER_FORMAT_ORDINAL_TEXT,
+        self::NUMBER_FORMAT_NONE,
+        self::NUMBER_FORMAT_BULLET
+    );
+
+    const POSITION_PAGE_BOTTOM = 'pageBottom';
+    const POSITION_BENEATH_TEXT = 'beneathText';
+    const POSITION_SECTION_END = 'sectEnd';
+    const POSITION_DOC_END = 'docEnd';
+
+    const POSITION = array(
+        self::POSITION_PAGE_BOTTOM,
+        self::POSITION_BENEATH_TEXT,
+        self::POSITION_SECTION_END,
+        self::POSITION_DOC_END
+    );
+
+    /**
+     * Footnote Positioning Location
+     *
+     * @var string
+     */
+    private $pos;
+
+    /**
+     * Footnote Numbering Format
+     *
+     * @var string
+     */
+    private $numFmt;
+
+    /**
+     * Footnote and Endnote Numbering Starting Value
+     *
+     * @var decimal
+     */
+    private $numStart;
+
+    /**
+     * Footnote and Endnote Numbering Restart Location
+     *
+     * @var string
+     */
+    private $numRestart;
+
+    public function getPos()
+    {
+        return $this->pos;
+    }
+
+    public function setPos($pos)
+    {
+        if (in_array($pos, self::POSITION)) {
+            $this->pos = $pos;
+        } else {
+            throw new \InvalidArgumentException("Invalid value, on of " . implode(', ', self::POSITION) . " possible");
+        }
+    }
+
+    public function getNumFmt()
+    {
+        return $this->numFmt;
+    }
+
+    public function setNumFmt($numFmt)
+    {
+        if (in_array($numFmt, self::NUMBER_FORMAT)) {
+            $this->numFmt = $numFmt;
+        } else {
+            throw new \InvalidArgumentException("Invalid value, on of " . implode(', ', self::NUMBER_FORMAT) . " possible");
+        }
+    }
+
+    public function getNumStart()
+    {
+        return $this->numStart;
+    }
+
+    public function setNumStart($numStart)
+    {
+        $this->numStart = $numStart;
+    }
+
+    public function getNumRestart()
+    {
+        return $this->numRestart;
+    }
+
+    public function setNumRestart($numRestart)
+    {
+        if (in_array($numRestart, self::RESTART_NUMBER)) {
+            $this->numRestart= $numRestart;
+        } else {
+            throw new \InvalidArgumentException("Invalid value, on of " . implode(', ', self::RESTART_NUMBER) . " possible");
+        }
+    }
+}

src/PhpWord/Writer/Word2007/Part/Document.php

@@ -21,6 +21,7 @@ use PhpOffice\Common\XMLWriter;
 use PhpOffice\PhpWord\Element\Section;
 use PhpOffice\PhpWord\Writer\Word2007\Element\Container;
 use PhpOffice\PhpWord\Writer\Word2007\Style\Section as SectionStyleWriter;
+use PhpOffice\PhpWord\SimpleType\FootnoteProperties;
 
 /**
  * Word2007 document part writer: word/document.xml
@@ -129,6 +130,32 @@ class Document extends AbstractPart
             $xmlWriter->endElement();
         }
 
+        //footnote properties
+        if ($section->getFootnotePropoperties() !== null) {
+            $xmlWriter->startElement('w:footnotePr');
+            if ($section->getFootnotePropoperties()->getPos() != null) {
+                $xmlWriter->startElement('w:pos');
+                $xmlWriter->writeAttribute('w:val', $section->getFootnotePropoperties()->getPos());
+                $xmlWriter->endElement();
+            }
+            if ($section->getFootnotePropoperties()->getNumFmt() != null) {
+                $xmlWriter->startElement('w:numFmt');
+                $xmlWriter->writeAttribute('w:val', $section->getFootnotePropoperties()->getNumFmt());
+                $xmlWriter->endElement();
+            }
+            if ($section->getFootnotePropoperties()->getNumStart() != null) {
+                $xmlWriter->startElement('w:numStart');
+                $xmlWriter->writeAttribute('w:val', $section->getFootnotePropoperties()->getNumStart());
+                $xmlWriter->endElement();
+            }
+            if ($section->getFootnotePropoperties()->getNumRestart() != null) {
+                $xmlWriter->startElement('w:numRestart');
+                $xmlWriter->writeAttribute('w:val', $section->getFootnotePropoperties()->getNumRestart());
+                $xmlWriter->endElement();
+            }
+            $xmlWriter->endElement();
+        }
+
         // Section settings
         $styleWriter = new SectionStyleWriter($xmlWriter, $section->getStyle());
         $styleWriter->write();

tests/PhpWord/SimpleType/FootnotePropertiesTest.php

@@ -0,0 +1,79 @@
+<?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\Style;
+
+use PhpOffice\PhpWord\SimpleType\FootnoteProperties;
+
+/**
+ * Test class for PhpOffice\PhpWord\SimpleType\FootnoteProperties
+ *
+ * @coversDefaultClass \PhpOffice\PhpWord\SimpleType\FootnoteProperties
+ * @runTestsInSeparateProcesses
+ */
+class FootnotePropertiesTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * Test setting style with normal value
+     */
+    public function testSetGetNormal()
+    {
+        $footnoteProp = new FootnoteProperties();
+        $footnoteProp->setPos(FootnoteProperties::POSITION_DOC_END);
+        $footnoteProp->setNumFmt(FootnoteProperties::NUMBER_FORMAT_LOWER_ROMAN);
+        $footnoteProp->setNumStart(2);
+        $footnoteProp->setNumRestart(FootnoteProperties::RESTART_NUMBER_EACH_PAGE);
+
+        $this->assertEquals(FootnoteProperties::POSITION_DOC_END, $footnoteProp->getPos());
+        $this->assertEquals(FootnoteProperties::NUMBER_FORMAT_LOWER_ROMAN, $footnoteProp->getNumFmt());
+        $this->assertEquals(2, $footnoteProp->getNumStart());
+        $this->assertEquals(FootnoteProperties::RESTART_NUMBER_EACH_PAGE, $footnoteProp->getNumRestart());
+    }
+
+    /**
+     * Test throws exception if wrong position given
+     * 
+     * @expectedException \InvalidArgumentException
+     */
+    public function testWrongPos()
+    {
+        $footnoteProp= new FootnoteProperties();
+        $footnoteProp->setPos(FootnoteProperties::NUMBER_FORMAT_LOWER_ROMAN);
+    }
+
+    /**
+     * Test throws exception if wrong number format given
+     * 
+     * @expectedException \InvalidArgumentException
+     */
+    public function testWrongNumFmt()
+    {
+        $footnoteProp= new FootnoteProperties();
+        $footnoteProp->setNumFmt(FootnoteProperties::POSITION_DOC_END);
+    }
+
+    /**
+     * Test throws exception if wrong number restart given
+     * 
+     * @expectedException \InvalidArgumentException
+     */
+    public function testWrongNumRestart()
+    {
+        $footnoteProp= new FootnoteProperties();
+        $footnoteProp->setNumRestart(FootnoteProperties::NUMBER_FORMAT_LOWER_ROMAN);
+    }
+}

tests/PhpWord/Writer/Word2007/Part/DocumentTest.php

@@ -20,6 +20,7 @@ use PhpOffice\PhpWord\PhpWord;
 use PhpOffice\PhpWord\SimpleType\Jc;
 use PhpOffice\PhpWord\Style\Font;
 use PhpOffice\PhpWord\TestHelperDOCX;
+use PhpOffice\PhpWord\SimpleType\FootnoteProperties;
 
 /**
  * Test class for PhpOffice\PhpWord\Writer\Word2007\Part\Document
@@ -57,6 +58,36 @@ class DocumentTest extends \PHPUnit_Framework_TestCase
         $this->assertEquals(2, $element->getAttribute('w:start'));
     }
 
+    /**
+     * Write section footnote properties
+     */
+    public function testSectionFootnoteProperties()
+    {
+        $properties = new FootnoteProperties();
+        $properties->setPos(FootnoteProperties::POSITION_DOC_END);
+        $properties->setNumFmt(FootnoteProperties::NUMBER_FORMAT_LOWER_ROMAN);
+        $properties->setNumStart(1);
+        $properties->setNumRestart(FootnoteProperties::RESTART_NUMBER_EACH_PAGE);
+
+        $phpWord = new PhpWord();
+        $section = $phpWord->addSection();
+        $section->setFootnoteProperties($properties);
+
+        $doc = TestHelperDOCX::getDocument($phpWord);
+
+        $element = $doc->getElement('/w:document/w:body/w:sectPr/w:footnotePr/w:pos');
+        $this->assertEquals(FootnoteProperties::POSITION_DOC_END, $element->getAttribute('w:val'));
+
+        $element = $doc->getElement('/w:document/w:body/w:sectPr/w:footnotePr/w:numFmt');
+        $this->assertEquals(FootnoteProperties::NUMBER_FORMAT_LOWER_ROMAN, $element->getAttribute('w:val'));
+
+        $element = $doc->getElement('/w:document/w:body/w:sectPr/w:footnotePr/w:numStart');
+        $this->assertEquals(1, $element->getAttribute('w:val'));
+
+        $element = $doc->getElement('/w:document/w:body/w:sectPr/w:footnotePr/w:numRestart');
+        $this->assertEquals(FootnoteProperties::RESTART_NUMBER_EACH_PAGE, $element->getAttribute('w:val'));
+    }
+
     /**
      * Write elements
      */