Merge pull request PHPOffice#1569 from troosan/page_vertical_align

implement support for section vAlign

Author: troosan

CHANGELOG.md

@@ -7,6 +7,7 @@ v0.17.0 (?? ??? 2019)
 ----------------------
 ### Added
 - Add RightToLeft table presentation. @troosan #1550
+- Add support for page vertical alignment. @troosan #672 #1569
 
 ### Fixed
 

docs/styles.rst

@@ -32,6 +32,8 @@ Available Section style options:
    See ``\PhpOffice\PhpWord\Style\Section::ORIENTATION_...`` class constants for possible values
 - ``pageSizeH``. Page height in *twip*. Implicitly defined by ``orientation`` option. Any changes are discouraged.
 - ``pageSizeW``. Page width in *twip*. Implicitly defined by ``orientation`` option. Any changes are discouraged.
+- ``vAlign``. Vertical Page Alignment
+   See ``\PhpOffice\PhpWord\SimpleType\VerticalJc`` for possible values
 
 .. _font-style:
 

samples/Sample_03_Sections.php

@@ -1,4 +1,6 @@
 <?php
+use PhpOffice\PhpWord\SimpleType\VerticalJc;
+
 include_once 'Sample_Header.php';
 
 // New Word Document
@@ -21,6 +23,12 @@
 );
 $section->addText('This section uses other margins with folio papersize.');
 
+// The text of this section is vertically centered
+$section = $phpWord->addSection(
+    array('vAlign' => VerticalJc::CENTER)
+);
+$section->addText('This section is vertically centered.');
+
 // New portrait section with Header & Footer
 $section = $phpWord->addSection(
     array(

src/PhpWord/Reader/Word2007/Document.php

@@ -106,6 +106,7 @@ private function readSectionStyle(XMLReader $xmlReader, \DOMElement $domNode)
     {
         $styleDefs = array(
             'breakType'     => array(self::READ_VALUE, 'w:type'),
+            'vAlign'        => array(self::READ_VALUE, 'w:vAlign'),
             'pageSizeW'     => array(self::READ_VALUE, 'w:pgSz', 'w:w'),
             'pageSizeH'     => array(self::READ_VALUE, 'w:pgSz', 'w:h'),
             'orientation'   => array(self::READ_VALUE, 'w:pgSz', 'w:orient'),

src/PhpWord/SimpleType/VerticalJc.php

@@ -0,0 +1,36 @@
+<?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.
+ *
+ * @see         https://github.com/PHPOffice/PHPWord
+ * @copyright   2010-2018 PHPWord contributors
+ * @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
+ */
+
+namespace PhpOffice\PhpWord\SimpleType;
+
+use PhpOffice\PhpWord\Shared\AbstractEnum;
+
+/**
+ * Vertical Alignment Type.
+ *
+ * Introduced in ISO/IEC-29500:2008.
+ *
+ * @see http://www.datypic.com/sc/ooxml/t-w_ST_VerticalJc.html
+ * @since 0.17.0
+ */
+final class VerticalJc extends AbstractEnum
+{
+    const TOP = 'top';
+    const CENTER = 'center';
+    const BOTH = 'both';
+    const BOTTOM = 'bottom';
+}

src/PhpWord/Style/Cell.php

@@ -18,6 +18,7 @@
 namespace PhpOffice\PhpWord\Style;
 
 use PhpOffice\PhpWord\SimpleType\TblWidth;
+use PhpOffice\PhpWord\SimpleType\VerticalJc;
 
 /**
  * Table cell style
@@ -28,10 +29,20 @@ class Cell extends Border
      * Vertical alignment constants
      *
      * @const string
+     * @deprecated Use \PhpOffice\PhpWord\SimpleType\VerticalJc::TOP instead
      */
     const VALIGN_TOP = 'top';
+    /**
+     * @deprecated Use \PhpOffice\PhpWord\SimpleType\VerticalJc::CENTER instead
+     */
     const VALIGN_CENTER = 'center';
+    /**
+     * @deprecated Use \PhpOffice\PhpWord\SimpleType\VerticalJc::BOTTOM instead
+     */
     const VALIGN_BOTTOM = 'bottom';
+    /**
+     * @deprecated Use \PhpOffice\PhpWord\SimpleType\VerticalJc::BOTH instead
+     */
     const VALIGN_BOTH = 'both';
 
     //Text direction constants
@@ -145,8 +156,8 @@ public function getVAlign()
      */
     public function setVAlign($value = null)
     {
-        $enum = array(self::VALIGN_TOP, self::VALIGN_CENTER, self::VALIGN_BOTTOM, self::VALIGN_BOTH);
-        $this->vAlign = $this->setEnumVal($value, $enum, $this->vAlign);
+        VerticalJc::validate($value);
+        $this->vAlign = $this->setEnumVal($value, VerticalJc::values(), $this->vAlign);
 
         return $this;
     }

src/PhpWord/Style/Section.php

@@ -17,6 +17,8 @@
 
 namespace PhpOffice\PhpWord\Style;
 
+use PhpOffice\PhpWord\SimpleType\VerticalJc;
+
 /**
  * Section settings
  */
@@ -166,6 +168,14 @@ class Section extends Border
      */
     private $lineNumbering;
 
+    /**
+     * Vertical Text Alignment on Page
+     * One of \PhpOffice\PhpWord\SimpleType\VerticalJc
+     *
+     * @var string
+     */
+    private $vAlign;
+
     /**
      * Create new instance
      */
@@ -599,4 +609,28 @@ public function setLineNumbering($value = null)
 
         return $this;
     }
+
+    /**
+     * Get vertical alignment
+     *
+     * @return string
+     */
+    public function getVAlign()
+    {
+        return $this->vAlign;
+    }
+
+    /**
+     * Set vertical alignment
+     *
+     * @param string $value
+     * @return self
+     */
+    public function setVAlign($value = null)
+    {
+        VerticalJc::validate($value);
+        $this->vAlign = $value;
+
+        return $this;
+    }
 }

src/PhpWord/Writer/Word2007/Style/Section.php

@@ -48,6 +48,10 @@ public function write()
         $xmlWriter->writeAttribute('w:h', $style->getPageSizeH());
         $xmlWriter->endElement(); // w:pgSz
 
+        // Vertical alignment
+        $vAlign = $style->getVAlign();
+        $xmlWriter->writeElementIf(!is_null($vAlign), 'w:vAlign', 'w:val', $vAlign);
+
         // Margins
         $margins = array(
             'w:top'    => array('getMarginTop', SectionStyle::DEFAULT_MARGIN),

tests/PhpWord/Reader/Word2007/StyleTest.php

@@ -19,6 +19,7 @@
 
 use PhpOffice\PhpWord\AbstractTestReader;
 use PhpOffice\PhpWord\SimpleType\TblWidth;
+use PhpOffice\PhpWord\SimpleType\VerticalJc;
 use PhpOffice\PhpWord\Style;
 use PhpOffice\PhpWord\Style\Table;
 use PhpOffice\PhpWord\Style\TablePosition;
@@ -213,4 +214,16 @@ public function testReadHeading()
         $this->getDocumentFromString(array('styles' => $documentXml));
         $this->assertInstanceOf('PhpOffice\\PhpWord\\Style\\Font', Style::getStyle($name));
     }
+
+    public function testPageVerticalAlign()
+    {
+        $documentXml = '<w:sectPr>
+            <w:vAlign w:val="center"/>
+        </w:sectPr>';
+
+        $phpWord = $this->getDocumentFromString(array('document' => $documentXml));
+
+        $sectionStyle = $phpWord->getSection(0)->getStyle();
+        $this->assertEquals(VerticalJc::CENTER, $sectionStyle->getVAlign());
+    }
 }

tests/PhpWord/Style/CellTest.php

@@ -17,6 +17,8 @@
 
 namespace PhpOffice\PhpWord\Style;
 
+use PhpOffice\PhpWord\SimpleType\VerticalJc;
+
 /**
  * Test class for PhpOffice\PhpWord\Style\Cell
  *
@@ -33,7 +35,7 @@ public function testSetGetNormal()
         $object = new Cell();
 
         $attributes = array(
-            'valign'            => Cell::VALIGN_TOP,
+            'valign'            => VerticalJc::TOP,
             'textDirection'     => Cell::TEXT_DIR_BTLR,
             'bgColor'           => 'FFFF00',
             'borderTopSize'     => 120,