Add exportArray Method for Styles (#1580)

Issue #580 has gone stale since I started work on this.
Nevertheless, this implements an exportArray function as an
exact counterpart of applyFromArry.
I chose the name exportArray to avoid confusion with the existing
method getStyleArray, which does something completely different.

This change also increases coverage for all the Style classes to 100%,
with the exception of Style.php itself. There were several (unchanged)
places in Style.php where I did not have sufficient understanding of
what was supposed to be happening, so could not create tests.

All properties used by applyFromArray are exported by this method.
Note that conditional styles are not covered; this is consistent
with the fact that they are not covered by applyFromArray.

The method is implemented as a final public function in Style/Supervisor,
which calls abstract protected function exportArray1, which is implemented
in each of the subclasses, and which calls final protected
function exportArray2 in Style/Supervisor.
So exportArray is usable for any of the subclasses as well.

The new method is added to the documentation.
The existing documentation for applyFromArray was alphabetized to make
it easier to follow.
One property (Style quotePrefix) was added to the documentation.
Some Borders pseudo-properties (vertical, horizontal, and outline) were
documented as usable by applyFromArray,
but aren't actually supported - they were removed.
The documentation of the properties seemed to use setProperty and
getProperty fairly randomly - it now uses setProperty exclusively.

New constants were added for the textRotation "angles" used to create a
"stacked" cell. I felt that changing the readers and writers to use
these constants was beyond the scope of this change, but it is
on my to-do list.

Author: oleibman

docs/topics/recipes.md

@@ -587,6 +587,13 @@ execution whenever you are setting more than one style property. But the
 difference may barely be measurable unless you have many different
 styles in your workbook.
 
+You can perform the opposite function, exporting a Style as an array,
+as follows:
+
+``` php
+$styleArray = $spreadsheet->getActiveSheet()->getStyle('A3')->exportArray();
+```
+
 ### Number formats
 
 You often want to format numbers in Excel. For example you may want a
@@ -753,69 +760,74 @@ another style array.
 
 Array key    | Maps to property
 -------------|-------------------
-fill         | getFill()
-font         | getFont()
-borders      | getBorders()
-alignment    | getAlignment()
-numberFormat | getNumberFormat()
-protection   | getProtection()
+alignment    | setAlignment()
+borders      | setBorders()
+fill         | setFill()
+font         | setFont()
+numberFormat | setNumberFormat()
+protection   | setProtection()
+quotePrefix  | setQuotePrefix()
 
-**\PhpOffice\PhpSpreadsheet\Style\Fill**
+**\PhpOffice\PhpSpreadsheet\Style\Alignment**
 
-Array key  | Maps to property
------------|-------------------
-fillType   | setFillType()
-rotation   | setRotation()
-startColor | getStartColor()
-endColor   | getEndColor()
-color      | getStartColor()
+Array key   | Maps to property
+------------|-------------------
+horizontal  | setHorizontal()
+indent      | setIndent()
+readOrder   | setReadOrder()
+shrinkToFit | setShrinkToFit()
+textRotation| setTextRotation()
+vertical    | setVertical()
+wrapText    | setWrapText()
 
-**\PhpOffice\PhpSpreadsheet\Style\Font**
+**\PhpOffice\PhpSpreadsheet\Style\Border**
 
 Array key   | Maps to property
 ------------|-------------------
-name        | setName()
-bold        | setBold()
-italic      | setItalic()
-underline   | setUnderline()
-strikethrough | setStrikethrough()
-color       | getColor()
-size        | setSize()
-superscript | setSuperscript()
-subscript   | setSubscript()
+borderStyle | setBorderStyle()
+color       | setColor()
 
 **\PhpOffice\PhpSpreadsheet\Style\Borders**
 
 Array key         | Maps to property
 ------------------|-------------------
-allBorders        | getLeft(); getRight(); getTop(); getBottom()
-left              | getLeft()
-right             | getRight()
-top               | getTop()
-bottom            | getBottom()
-diagonal          | getDiagonal()
-vertical          | getVertical()
-horizontal        | getHorizontal()
+allBorders        | setLeft(); setRight(); setTop(); setBottom()
+bottom            | setBottom()
+diagonal          | setDiagonal()
 diagonalDirection | setDiagonalDirection()
-outline           | setOutline()
+left              | setLeft()
+right             | setRight()
+top               | setTop()
 
-**\PhpOffice\PhpSpreadsheet\Style\Border**
+**\PhpOffice\PhpSpreadsheet\Style\Color**
 
 Array key   | Maps to property
 ------------|-------------------
-borderStyle | setBorderStyle()
-color       | getColor()
+argb        | setARGB()
 
-**\PhpOffice\PhpSpreadsheet\Style\Alignment**
+**\PhpOffice\PhpSpreadsheet\Style\Fill**
+
+Array key  | Maps to property
+-----------|-------------------
+color      | getStartColor()
+endColor   | getEndColor()
+fillType   | setFillType()
+rotation   | setRotation()
+startColor | getStartColor()
+
+**\PhpOffice\PhpSpreadsheet\Style\Font**
 
 Array key   | Maps to property
 ------------|-------------------
-horizontal  | setHorizontal()
-vertical    | setVertical()
-textRotation| setTextRotation()
-wrapText    | setWrapText()
-shrinkToFit | setShrinkToFit()
-indent      | setIndent()
+bold        | setBold()
+color       | getColor()
+italic      | setItalic()
+name        | setName()
+size        | setSize()
+strikethrough | setStrikethrough()
+subscript   | setSubscript()
+superscript | setSuperscript()
+underline   | setUnderline()
 
 **\PhpOffice\PhpSpreadsheet\Style\NumberFormat**
 

src/PhpSpreadsheet/Style/Alignment.php

@@ -28,6 +28,10 @@ class Alignment extends Supervisor
     const READORDER_LTR = 1;
     const READORDER_RTL = 2;
 
+    // Special value for Text Rotation
+    const TEXTROTATION_STACK_EXCEL = 255;
+    const TEXTROTATION_STACK_PHPSPREADSHEET = -165; // 90 - 255
+
     /**
      * Horizontal alignment.
      *
@@ -270,12 +274,12 @@ public function getTextRotation()
     public function setTextRotation($pValue)
     {
         // Excel2007 value 255 => PhpSpreadsheet value -165
-        if ($pValue == 255) {
-            $pValue = -165;
+        if ($pValue == self::TEXTROTATION_STACK_EXCEL) {
+            $pValue = self::TEXTROTATION_STACK_PHPSPREADSHEET;
         }
 
         // Set rotation
-        if (($pValue >= -90 && $pValue <= 90) || $pValue == -165) {
+        if (($pValue >= -90 && $pValue <= 90) || $pValue == self::TEXTROTATION_STACK_PHPSPREADSHEET) {
             if ($this->isSupervisor) {
                 $styleArray = $this->getStyleArray(['textRotation' => $pValue]);
                 $this->getActiveSheet()->getStyle($this->getSelectedCells())->applyFromArray($styleArray);
@@ -461,4 +465,18 @@ public function getHashCode()
             __CLASS__
         );
     }
+
+    protected function exportArray1(): array
+    {
+        $exportedArray = [];
+        $this->exportArray2($exportedArray, 'horizontal', $this->getHorizontal());
+        $this->exportArray2($exportedArray, 'indent', $this->getIndent());
+        $this->exportArray2($exportedArray, 'readOrder', $this->getReadOrder());
+        $this->exportArray2($exportedArray, 'shrinkToFit', $this->getShrinkToFit());
+        $this->exportArray2($exportedArray, 'textRotation', $this->getTextRotation());
+        $this->exportArray2($exportedArray, 'vertical', $this->getVertical());
+        $this->exportArray2($exportedArray, 'wrapText', $this->getWrapText());
+
+        return $exportedArray;
+    }
 }

src/PhpSpreadsheet/Style/Border.php

@@ -74,14 +74,6 @@ public function __construct($isSupervisor = false, $isConditional = false)
     public function getSharedComponent()
     {
         switch ($this->parentPropertyName) {
-            case 'allBorders':
-            case 'horizontal':
-            case 'inside':
-            case 'outline':
-            case 'vertical':
-                throw new PhpSpreadsheetException('Cannot get shared component for a pseudo-border.');
-
-                break;
             case 'bottom':
                 return $this->parent->getSharedComponent()->getBottom();
             case 'diagonal':
@@ -93,6 +85,8 @@ public function getSharedComponent()
             case 'top':
                 return $this->parent->getSharedComponent()->getTop();
         }
+
+        throw new PhpSpreadsheetException('Cannot get shared component for a pseudo-border.');
     }
 
     /**
@@ -228,4 +222,13 @@ public function getHashCode()
             __CLASS__
         );
     }
+
+    protected function exportArray1(): array
+    {
+        $exportedArray = [];
+        $this->exportArray2($exportedArray, 'borderStyle', $this->getBorderStyle());
+        $this->exportArray2($exportedArray, 'color', $this->getColor());
+
+        return $exportedArray;
+    }
 }

src/PhpSpreadsheet/Style/Borders.php

@@ -408,4 +408,17 @@ public function getHashCode()
             __CLASS__
         );
     }
+
+    protected function exportArray1(): array
+    {
+        $exportedArray = [];
+        $this->exportArray2($exportedArray, 'bottom', $this->getBottom());
+        $this->exportArray2($exportedArray, 'diagonal', $this->getDiagonal());
+        $this->exportArray2($exportedArray, 'diagonalDirection', $this->getDiagonalDirection());
+        $this->exportArray2($exportedArray, 'left', $this->getLeft());
+        $this->exportArray2($exportedArray, 'right', $this->getRight());
+        $this->exportArray2($exportedArray, 'top', $this->getTop());
+
+        return $exportedArray;
+    }
 }

src/PhpSpreadsheet/Style/Color.php

@@ -71,14 +71,14 @@ public function __construct($pARGB = self::COLOR_BLACK, $isSupervisor = false, $
      */
     public function getSharedComponent()
     {
-        switch ($this->parentPropertyName) {
-            case 'endColor':
-                return $this->parent->getSharedComponent()->getEndColor();
-            case 'color':
-                return $this->parent->getSharedComponent()->getColor();
-            case 'startColor':
-                return $this->parent->getSharedComponent()->getStartColor();
+        if ($this->parentPropertyName === 'endColor') {
+            return $this->parent->getSharedComponent()->getEndColor();
         }
+        if ($this->parentPropertyName === 'startColor') {
+            return $this->parent->getSharedComponent()->getStartColor();
+        }
+
+        return $this->parent->getSharedComponent()->getColor();
     }
 
     /**
@@ -262,6 +262,7 @@ public static function getBlue($RGB, $hex = true)
     public static function changeBrightness($hex, $adjustPercentage)
     {
         $rgba = (strlen($hex) === 8);
+        $adjustPercentage = max(-1.0, min(1.0, $adjustPercentage));
 
         $red = self::getRed($hex, false);
         $green = self::getGreen($hex, false);
@@ -276,22 +277,6 @@ public static function changeBrightness($hex, $adjustPercentage)
             $blue += $blue * $adjustPercentage;
         }
 
-        if ($red < 0) {
-            $red = 0;
-        } elseif ($red > 255) {
-            $red = 255;
-        }
-        if ($green < 0) {
-            $green = 0;
-        } elseif ($green > 255) {
-            $green = 255;
-        }
-        if ($blue < 0) {
-            $blue = 0;
-        } elseif ($blue > 255) {
-            $blue = 255;
-        }
-
         $rgb = strtoupper(
             str_pad(dechex((int) $red), 2, '0', 0) .
             str_pad(dechex((int) $green), 2, '0', 0) .
@@ -404,4 +389,12 @@ public function getHashCode()
             __CLASS__
         );
     }
+
+    protected function exportArray1(): array
+    {
+        $exportedArray = [];
+        $this->exportArray2($exportedArray, 'argb', $this->getARGB());
+
+        return $exportedArray;
+    }
 }

src/PhpSpreadsheet/Style/Fill.php

@@ -311,4 +311,15 @@ public function getHashCode()
             __CLASS__
         );
     }
+
+    protected function exportArray1(): array
+    {
+        $exportedArray = [];
+        $this->exportArray2($exportedArray, 'endColor', $this->getEndColor());
+        $this->exportArray2($exportedArray, 'fillType', $this->getFillType());
+        $this->exportArray2($exportedArray, 'rotation', $this->getRotation());
+        $this->exportArray2($exportedArray, 'startColor', $this->getStartColor());
+
+        return $exportedArray;
+    }
 }

src/PhpSpreadsheet/Style/Font.php

@@ -539,4 +539,20 @@ public function getHashCode()
             __CLASS__
         );
     }
+
+    protected function exportArray1(): array
+    {
+        $exportedArray = [];
+        $this->exportArray2($exportedArray, 'bold', $this->getBold());
+        $this->exportArray2($exportedArray, 'color', $this->getColor());
+        $this->exportArray2($exportedArray, 'italic', $this->getItalic());
+        $this->exportArray2($exportedArray, 'name', $this->getName());
+        $this->exportArray2($exportedArray, 'size', $this->getSize());
+        $this->exportArray2($exportedArray, 'strikethrough', $this->getStrikethrough());
+        $this->exportArray2($exportedArray, 'subscript', $this->getSubscript());
+        $this->exportArray2($exportedArray, 'superscript', $this->getSuperscript());
+        $this->exportArray2($exportedArray, 'underline', $this->getUnderline());
+
+        return $exportedArray;
+    }
 }

src/PhpSpreadsheet/Style/NumberFormat.php

@@ -870,4 +870,12 @@ public static function toFormattedString($value, $format, $callBack = null)
 
         return $value;
     }
+
+    protected function exportArray1(): array
+    {
+        $exportedArray = [];
+        $this->exportArray2($exportedArray, 'formatCode', $this->getFormatCode());
+
+        return $exportedArray;
+    }
 }

src/PhpSpreadsheet/Style/Protection.php

@@ -183,4 +183,13 @@ public function getHashCode()
             __CLASS__
         );
     }
+
+    protected function exportArray1(): array
+    {
+        $exportedArray = [];
+        $this->exportArray2($exportedArray, 'locked', $this->getLocked());
+        $this->exportArray2($exportedArray, 'hidden', $this->getHidden());
+
+        return $exportedArray;
+    }
 }

src/PhpSpreadsheet/Style/Style.php

@@ -636,4 +636,18 @@ public function setIndex($pValue): void
     {
         $this->index = $pValue;
     }
+
+    protected function exportArray1(): array
+    {
+        $exportedArray = [];
+        $this->exportArray2($exportedArray, 'alignment', $this->getAlignment());
+        $this->exportArray2($exportedArray, 'borders', $this->getBorders());
+        $this->exportArray2($exportedArray, 'fill', $this->getFill());
+        $this->exportArray2($exportedArray, 'font', $this->getFont());
+        $this->exportArray2($exportedArray, 'numberFormat', $this->getNumberFormat());
+        $this->exportArray2($exportedArray, 'protection', $this->getProtection());
+        $this->exportArray2($exportedArray, 'quotePrefx', $this->getQuotePrefix());
+
+        return $exportedArray;
+    }
 }