Cell alignment

This PR adds support for cell alignment for XLSX and ODS files.
You can now align the content of the cells this way:
```
use Box\Spout\Common\Entity\Style\CellAlignment;
use Box\Spout\Writer\Common\Creator\Style\StyleBuilder;

$style = (new StyleBuilder())
    ->setCellAlignment(CellAlignment::RIGHT)
    ->build();
...
```

Possible cell alignments are: LEFT, RIGHT, CENTER and JUSTIFY.

docs/_pages/documentation.md

@@ -117,7 +117,7 @@ $reader->setShouldPreserveEmptyRows(true);
 For fonts and alignments, {{ site.spout_html }} does not support all the possible formatting options yet. But you can find the most important ones:
 
 | Category  | Property       | API
-|:----------|:--------------|:--------------------------------------
+|:----------|:---------------|:--------------------------------------
 | Font      | Bold           | `StyleBuilder::setFontBold()`
 |           | Italic         | `StyleBuilder::setFontItalic()`
 |           | Underline      | `StyleBuilder::setFontUnderline()`
@@ -125,7 +125,8 @@ For fonts and alignments, {{ site.spout_html }} does not support all the possibl
 |           | Font name      | `StyleBuilder::setFontName('Arial')`
 |           | Font size      | `StyleBuilder::setFontSize(14)`
 |           | Font color     | `StyleBuilder::setFontColor(Color::BLUE)`<br>`StyleBuilder::setFontColor(Color::rgb(0, 128, 255))`
-| Alignment | Wrap text     | `StyleBuilder::setShouldWrapText(true|false)`
+| Alignment | Cell alignment | `StyleBuilder::setCellAlignment(CellAlignment::CENTER)`
+|           | Wrap text      | `StyleBuilder::setShouldWrapText(true)`
 
 
 ### Styling rows
@@ -135,6 +136,7 @@ It is possible to apply some formatting options to a row. In this case, all cell
 ```php
 use Box\Spout\Writer\Common\Creator\WriterEntityFactory;
 use Box\Spout\Writer\Common\Creator\Style\StyleBuilder;
+use Box\Spout\Common\Entity\Style\CellAlignment;
 use Box\Spout\Common\Entity\Style\Color;
 
 $writer = WriterEntityFactory::createXLSXWriter();
@@ -146,6 +148,7 @@ $style = (new StyleBuilder())
            ->setFontSize(15)
            ->setFontColor(Color::BLUE)
            ->setShouldWrapText()
+           ->setCellAlignment(CellAlignment::RIGHT)
            ->setBackgroundColor(Color::YELLOW)
            ->build();
 

src/Spout/Common/Entity/Style/CellAlignment.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Box\Spout\Common\Entity\Style;
+
+/**
+ * Class Alignment
+ * This class provides constants to work with text alignment.
+ */
+abstract class CellAlignment
+{
+    const LEFT = 'left';
+    const RIGHT = 'right';
+    const CENTER = 'center';
+    const JUSTIFY = 'justify';
+
+    private static $VALID_ALIGNMENTS = [
+        self::LEFT => 1,
+        self::RIGHT => 1,
+        self::CENTER => 1,
+        self::JUSTIFY => 1,
+    ];
+
+    /**
+     * @param string $cellAlignment
+     *
+     * @return bool Whether the given cell alignment is valid
+     */
+    public static function isValid($cellAlignment)
+    {
+        return isset(self::$VALID_ALIGNMENTS[$cellAlignment]);
+    }
+}

src/Spout/Common/Entity/Style/Color.php

@@ -8,7 +8,7 @@ use Box\Spout\Common\Exception\InvalidColorException;
  * Class Color
  * This class provides constants and functions to work with colors
  */
-class Color
+abstract class Color
 {
     /** Standard colors - based on Office Online */
     const BLACK = '000000';

src/Spout/Common/Entity/Style/Style.php

@@ -8,7 +8,7 @@ namespace Box\Spout\Common\Entity\Style;
  */
 class Style
 {
-    /** Default font values */
+    /** Default values */
     const DEFAULT_FONT_SIZE = 11;
     const DEFAULT_FONT_COLOR = Color::BLACK;
     const DEFAULT_FONT_NAME = 'Arial';
@@ -54,6 +54,13 @@ class Style
     /** @var bool Whether specific font properties should be applied */
     private $shouldApplyFont = false;
 
+    /** @var bool Whether specific cell alignment should be applied */
+    private $shouldApplyCellAlignment = false;
+    /** @var string Cell alignment */
+    private $cellAlignment;
+    /** @var bool Whether the cell alignment property was set */
+    private $hasSetCellAlignment = false;
+
     /** @var bool Whether the text should wrap in the cell (useful for long or multi-lines text) */
     private $shouldWrapText = false;
     /** @var bool Whether the wrap text property was set */
@@ -325,6 +332,44 @@ class Style
         return $this->hasSetFontName;
     }
 
+    /**
+     * @return string
+     */
+    public function getCellAlignment()
+    {
+        return $this->cellAlignment;
+    }
+
+    /**
+     * @param string $cellAlignment The cell alignment
+     *
+     * @return Style
+     */
+    public function setCellAlignment($cellAlignment)
+    {
+        $this->cellAlignment = $cellAlignment;
+        $this->hasSetCellAlignment = true;
+        $this->shouldApplyCellAlignment = true;
+
+        return $this;
+    }
+
+    /**
+     * @return bool
+     */
+    public function hasSetCellAlignment()
+    {
+        return $this->hasSetCellAlignment;
+    }
+
+    /**
+     * @return bool Whether specific cell alignment should be applied
+     */
+    public function shouldApplyCellAlignment()
+    {
+        return $this->shouldApplyCellAlignment;
+    }
+
     /**
      * @return bool
      */

src/Spout/Writer/Common/Creator/Style/StyleBuilder.php

@@ -3,7 +3,9 @@
 namespace Box\Spout\Writer\Common\Creator\Style;
 
 use Box\Spout\Common\Entity\Style\Border;
+use Box\Spout\Common\Entity\Style\CellAlignment;
 use Box\Spout\Common\Entity\Style\Style;
+use Box\Spout\Common\Exception\InvalidArgumentException;
 
 /**
  * Class StyleBuilder
@@ -122,6 +124,25 @@ class StyleBuilder
         return $this;
     }
 
+    /**
+     * Sets the cell alignment.
+     *
+     * @param string $cellAlignment The cell alignment
+     *
+     * @throws InvalidArgumentException If the given cell alignment is not valid
+     * @return StyleBuilder
+     */
+    public function setCellAlignment($cellAlignment)
+    {
+        if (!CellAlignment::isValid($cellAlignment)) {
+            throw new InvalidArgumentException('Invalid cell alignment value');
+        }
+
+        $this->style->setCellAlignment($cellAlignment);
+
+        return $this;
+    }
+
     /**
      * Set a border
      *

src/Spout/Writer/Common/Manager/Style/StyleMerger.php

@@ -85,6 +85,9 @@ class StyleMerger
         if (!$style->hasSetWrapText() && $baseStyle->shouldWrapText()) {
             $styleToUpdate->setShouldWrapText();
         }
+        if (!$style->hasSetCellAlignment() && $baseStyle->shouldApplyCellAlignment()) {
+            $styleToUpdate->setCellAlignment($baseStyle->getCellAlignment());
+        }
         if (!$style->getBorder() && $baseStyle->shouldApplyBorder()) {
             $styleToUpdate->setBorder($baseStyle->getBorder());
         }

src/Spout/Writer/ODS/Manager/Style/StyleManager.php

@@ -3,6 +3,7 @@
 namespace Box\Spout\Writer\ODS\Manager\Style;
 
 use Box\Spout\Common\Entity\Style\BorderPart;
+use Box\Spout\Common\Entity\Style\CellAlignment;
 use Box\Spout\Writer\Common\Entity\Worksheet;
 use Box\Spout\Writer\ODS\Helper\BorderHelper;
 
@@ -199,6 +200,7 @@ EOD;
         $content = '<style:style style:data-style-name="N0" style:family="table-cell" style:name="ce' . $styleIndex . '" style:parent-style-name="Default">';
 
         $content .= $this->getTextPropertiesSectionContent($style);
+        $content .= $this->getParagraphPropertiesSectionContent($style);
         $content .= $this->getTableCellPropertiesSectionContent($style);
 
         $content .= '</style:style>';
@@ -214,26 +216,26 @@ EOD;
      */
     private function getTextPropertiesSectionContent($style)
     {
-        $content = '';
+        if (!$style->shouldApplyFont()) {
-
+            return '';
-        if ($style->shouldApplyFont()) {
-            $content .= $this->getFontSectionContent($style);
         }
 
-        return $content;
+        return '<style:text-properties '
+            . $this->getFontSectionContent($style)
+            . '/>';
     }
 
     /**
-     * Returns the contents of the "<style:text-properties>" section, inside "<style:style>" section
+     * Returns the contents of the fonts definition section, inside "<style:text-properties>" section
      *
      * @param \Box\Spout\Common\Entity\Style\Style $style
+     *
      * @return string
      */
     private function getFontSectionContent($style)
     {
         $defaultStyle = $this->getDefaultStyle();
-
+        $content = '';
-        $content = '<style:text-properties';
 
         $fontColor = $style->getFontColor();
         if ($fontColor !== $defaultStyle->getFontColor()) {
@@ -263,11 +265,60 @@ EOD;
             $content .= ' style:text-line-through-style="solid"';
         }
 
-        $content .= '/>';
-
         return $content;
     }
 
+    /**
+     * Returns the contents of the "<style:paragraph-properties>" section, inside "<style:style>" section
+     *
+     * @param \Box\Spout\Common\Entity\Style\Style $style
+     *
+     * @return string
+     */
+    private function getParagraphPropertiesSectionContent($style)
+    {
+        if (!$style->shouldApplyCellAlignment()) {
+            return '';
+        }
+
+        return '<style:paragraph-properties '
+            . $this->getCellAlignmentSectionContent($style)
+            . '/>';
+    }
+
+    /**
+     * Returns the contents of the cell alignment definition for the "<style:paragraph-properties>" section
+     *
+     * @param \Box\Spout\Common\Entity\Style\Style $style
+     *
+     * @return string
+     */
+    private function getCellAlignmentSectionContent($style)
+    {
+        return sprintf(
+            ' fo:text-align="%s" ',
+            $this->transformCellAlignment($style->getCellAlignment())
+        );
+    }
+
+    /**
+     * Even though "left" and "right" alignments are part of the spec, and interpreted
+     * respectively as "start" and "end", using the recommended values increase compatibility
+     * with software that will read the created ODS file.
+     *
+     * @param string $cellAlignment
+     *
+     * @return string
+     */
+    private function transformCellAlignment($cellAlignment)
+    {
+        switch ($cellAlignment) {
+            case CellAlignment::LEFT: return 'start';
+            case CellAlignment::RIGHT: return 'end';
+            default: return $cellAlignment;
+        }
+    }
+
     /**
      * Returns the contents of the "<style:table-cell-properties>" section, inside "<style:style>" section
      *
@@ -276,7 +327,7 @@ EOD;
      */
     private function getTableCellPropertiesSectionContent($style)
     {
-        $content = '';
+        $content = '<style:table-cell-properties ';
 
         if ($style->shouldWrapText()) {
             $content .= $this->getWrapTextXMLContent();
@@ -290,6 +341,8 @@ EOD;
             $content .= $this->getBackgroundColorXMLContent($style);
         }
 
+        $content .= '/>';
+
         return $content;
     }
 
@@ -300,7 +353,7 @@ EOD;
      */
     private function getWrapTextXMLContent()
     {
-        return '<style:table-cell-properties fo:wrap-option="wrap" style:vertical-align="automatic"/>';
+        return ' fo:wrap-option="wrap" style:vertical-align="automatic" ';
     }
 
     /**
@@ -311,13 +364,11 @@ EOD;
      */
     private function getBorderXMLContent($style)
     {
-        $borderProperty = '<style:table-cell-properties %s />';
-
         $borders = array_map(function (BorderPart $borderPart) {
             return BorderHelper::serializeBorderPart($borderPart);
         }, $style->getBorder()->getParts());
 
-        return sprintf($borderProperty, implode(' ', $borders));
+        return sprintf(' %s ', implode(' ', $borders));
     }
 
     /**
@@ -328,9 +379,6 @@ EOD;
      */
     private function getBackgroundColorXMLContent($style)
     {
-        return sprintf(
+        return sprintf(' fo:background-color="#%s" ', $style->getBackgroundColor());
-            '<style:table-cell-properties fo:background-color="#%s"/>',
-            $style->getBackgroundColor()
-        );
     }
 }

src/Spout/Writer/XLSX/Manager/Style/StyleManager.php

@@ -249,9 +249,16 @@ EOD;
 
             $content .= sprintf(' applyBorder="%d"', $style->shouldApplyBorder() ? 1 : 0);
 
-            if ($style->shouldWrapText()) {
+            if ($style->shouldApplyCellAlignment() || $style->shouldWrapText()) {
                 $content .= ' applyAlignment="1">';
-                $content .= '<alignment wrapText="1"/>';
+                $content .= '<alignment';
+                if ($style->shouldApplyCellAlignment()) {
+                    $content .= sprintf(' horizontal="%s"', $style->getCellAlignment());
+                }
+                if ($style->shouldWrapText()) {
+                    $content .= ' wrapText="1"';
+                }
+                $content .= '/>';
                 $content .= '</xf>';
             } else {
                 $content .= '/>';

tests/Spout/Writer/Common/Creator/StyleBuilderTest.php

@@ -3,7 +3,9 @@
 namespace Box\Spout\Writer\Common\Creator\Style;
 
 use Box\Spout\Common\Entity\Style\Border;
+use Box\Spout\Common\Entity\Style\CellAlignment;
 use Box\Spout\Common\Entity\Style\Color;
+use Box\Spout\Common\Exception\InvalidArgumentException;
 use Box\Spout\Writer\Common\Manager\Style\StyleMerger;
 use PHPUnit\Framework\TestCase;
 
@@ -45,20 +47,18 @@ class StyleBuilderTest extends TestCase
     /**
      * @return void
      */
-    public function testStyleBuilderShouldMergeFormats()
+    public function testStyleBuilderShouldApplyCellAlignment()
     {
-        $baseStyle = (new StyleBuilder())
+        $style = (new StyleBuilder())->setCellAlignment(CellAlignment::CENTER)->build();
-            ->setFontBold()
+        $this->assertTrue($style->shouldApplyCellAlignment());
-            ->setFormat('0.00')
+    }
-            ->build();
 
-        $currentStyle = (new StyleBuilder())->build();
+    /**
-
+     * @return void
-        $styleMerger = new StyleMerger();
+     */
-        $mergedStyle = $styleMerger->merge($currentStyle, $baseStyle);
+    public function testStyleBuilderShouldThrowOnInvalidCellAlignment()
-
+    {
-        $this->assertNull($currentStyle->getFormat(), 'Current style has no border');
+        $this->expectException(InvalidArgumentException::class);
-        $this->assertEquals('0.00', $baseStyle->getFormat(), 'Base style has a format 0.00');
+        (new StyleBuilder())->setCellAlignment('invalid_cell_alignment')->build();
-        $this->assertEquals('0.00', $mergedStyle->getFormat(), 'Merged style has a format 0.00');
     }
 }

tests/Spout/Writer/Common/Manager/Style/StyleMergerTest.php

@@ -45,6 +45,7 @@ class StyleMergerTest extends TestCase
                         ->setFontBold()
                         ->setFontColor(Color::YELLOW)
                         ->setBackgroundColor(Color::BLUE)
+                        ->setFormat('0.00')
                         ->build();
         $currentStyle = (new StyleBuilder())->setFontName('Font')->setFontUnderline()->build();
         $mergedStyle = $this->styleMerger->merge($currentStyle, $baseStyle);
@@ -60,6 +61,7 @@ class StyleMergerTest extends TestCase
         $this->assertTrue($mergedStyle->isFontUnderline());
         $this->assertEquals(Color::YELLOW, $mergedStyle->getFontColor());
         $this->assertEquals(Color::BLUE, $mergedStyle->getBackgroundColor());
+        $this->assertEquals('0.00', $mergedStyle->getFormat());
     }
 
     /**

tests/Spout/Writer/ODS/WriterWithStyleTest.php

@@ -4,6 +4,7 @@ namespace Box\Spout\Writer\ODS;
 
 use Box\Spout\Common\Entity\Row;
 use Box\Spout\Common\Entity\Style\Border;
+use Box\Spout\Common\Entity\Style\CellAlignment;
 use Box\Spout\Common\Entity\Style\Color;
 use Box\Spout\Common\Entity\Style\Style;
 use Box\Spout\Reader\Wrapper\XMLReader;
@@ -204,6 +205,25 @@ class WriterWithStyleTest extends TestCase
         $this->assertFirstChildHasAttributeEquals('wrap', $customStyleElement, 'table-cell-properties', 'fo:wrap-option');
     }
 
+    /**
+     * @return void
+     */
+    public function testAddRowShouldApplyCellAlignment()
+    {
+        $fileName = 'test_add_row_should_apply_cell_alignment.xlsx';
+
+        $rightAlignedStyle = (new StyleBuilder())->setCellAlignment(CellAlignment::RIGHT)->build();
+        $dataRows = $this->createStyledRowsFromValues([['ods--11']], $rightAlignedStyle);
+
+        $this->writeToODSFile($dataRows, $fileName);
+
+        $styleElements = $this->getCellStyleElementsFromContentXmlFile($fileName);
+        $this->assertCount(2, $styleElements, 'There should be 2 styles (default and custom)');
+
+        $customStyleElement = $styleElements[1];
+        $this->assertFirstChildHasAttributeEquals('end', $customStyleElement, 'paragraph-properties', 'fo:text-align');
+    }
+
     /**
      * @return void
      */

tests/Spout/Writer/XLSX/WriterWithStyleTest.php

@@ -4,6 +4,7 @@ namespace Box\Spout\Writer\XLSX;
 
 use Box\Spout\Common\Entity\Row;
 use Box\Spout\Common\Entity\Style\Border;
+use Box\Spout\Common\Entity\Style\CellAlignment;
 use Box\Spout\Common\Entity\Style\Color;
 use Box\Spout\Common\Entity\Style\Style;
 use Box\Spout\Reader\Wrapper\XMLReader;
@@ -287,6 +288,24 @@ class WriterWithStyleTest extends TestCase
         $this->assertFirstChildHasAttributeEquals('1', $xfElement, 'alignment', 'wrapText');
     }
 
+    /**
+     * @return void
+     */
+    public function testAddRowShouldApplyCellAlignment()
+    {
+        $fileName = 'test_add_row_should_apply_cell_alignment.xlsx';
+
+        $rightAlignedStyle = (new StyleBuilder())->setCellAlignment(CellAlignment::RIGHT)->build();
+        $dataRows = $this->createStyledRowsFromValues([['xlsx--11']], $rightAlignedStyle);
+
+        $this->writeToXLSXFile($dataRows, $fileName);
+
+        $cellXfsDomElement = $this->getXmlSectionFromStylesXmlFile($fileName, 'cellXfs');
+        $xfElement = $cellXfsDomElement->getElementsByTagName('xf')->item(1);
+        $this->assertEquals(1, $xfElement->getAttribute('applyAlignment'));
+        $this->assertFirstChildHasAttributeEquals(CellAlignment::RIGHT, $xfElement, 'alignment', 'horizontal');
+    }
+
     /**
      * @return void
      */