SimpleType: Color - Create a simple color type for easily specifying preset color values.

docs/changes/1.x/1.5.0.md

@@ -11,9 +11,11 @@
 ### Miscellaneous
 
 - Update phpstan/phpstan requirement from ^0.12.88 || ^1.0.0 to ^0.12.88 || ^1.0.0 || ^2.0.0 by [@dependabot](https://github.com/dependabot) & [@Progi1984](https://github.com/Progi1984) in [#2736](https://github.com/PHPOffice/PHPWord/pull/2736)
+- SimpleType: Create Color, adding a variety of preset colors for use anywhere a color is specified by [@rasamassen](https://github.com/rasamassen) in [#2839](https://github.com/PHPOffice/PHPWord/pull/2839)
 
 ### Deprecations
+- Style > Font deprecate FGCOLOR constants, replaced by SimpleType > Color by [@rasamassen](https://github.com/rasamassen) in [#2839](https://github.com/PHPOffice/PHPWord/pull/2839)
 
 ### BC Breaks
 
-### Notes
+### Notes

docs/usage/simpletypes/color.md

@@ -0,0 +1,47 @@
+# Colors
+When used in [`Styles > Font`](../styles/font.md) to set the `fgColor`, only certain colors may be used, as identified below.
+
+## Constants
+- `AQUA`.
+- `BLACK`. Possible `fgColor` option.
+- `BLUE`. Possible `fgColor` option.
+- `BROWN`.
+- `CYAN`. Possible `fgColor` option.
+- `DARKBLUE`. Possible `fgColor` option.
+- `DARKCYAN`. Possible `fgColor` option.
+- `DARKGRAY`. Possible `fgColor` option.
+- `DARKGREEN`. Possible `fgColor` option.
+- `DARKMAGENTA`. Possible `fgColor` option.
+- `DARKORANGE`.
+- `DARKRED`. Possible `fgColor` option.
+- `DARKVIOLET`.
+- `DARKYELLOW`. Possible `fgColor` option.
+- `FUCHSIA`.
+- `GOLD`.
+- `GRAY`.
+- `GREEN`. Possible `fgColor` option.
+- `LIGHTBLUE`.
+- `LIGHTCYAN`.
+- `LIGHTGRAY`. Possible `fgColor` option.
+- `LIGHTGREEN`.
+- `LIGHTPINK`.
+- `LIGHTYELLOW`.
+- `LIME`.
+- `MAGENTA`. Possible `fgColor` option.
+- `MAROON`.
+- `NAVY`.
+- `OLIVE`.
+- `ORANGE`.
+- `PINK`.
+- `PURPLE`.
+- `RED`. Possible `fgColor` option.
+- `SILVER`.
+- `TAN`.
+- `TEAL`.
+- `TURQUOISE`.
+- `VIOLET`.
+- `WHITE`. Possible `fgColor` option.
+- `YELLOW`. Possible `fgColor` option.
+
+## Used In
+- Anywhere a hexadecimal color can be specified. e.g. *FF0000*.

samples/Sample_20_BGColor.php

@@ -11,7 +11,7 @@
 
 $section->addText(
     'This is some text highlighted using fgColor (limited to 15 colors)',
-    ['fgColor' => PhpOffice\PhpWord\Style\Font::FGCOLOR_YELLOW]
+    ['fgColor' => PhpOffice\PhpWord\SimpleType\Color::YELLOW]
 );
 $section->addText('This one uses bgColor and is using hex value (0xfbbb10)', ['bgColor' => 'fbbb10']);
 $section->addText('Compatible with font colors', ['color' => '0000ff', 'bgColor' => 'fbbb10']);

src/PhpWord/Shared/Converter.php

@@ -18,6 +18,9 @@
 
 namespace PhpOffice\PhpWord\Shared;
 
+use PhpOffice\PhpWord\SimpleType\Color;
+use PhpOffice\PhpWord\Style\Font as FontColor;
+
 /**
  * Common converter functions.
  */
@@ -305,35 +308,117 @@ public static function angleToDegree($angle = 1)
     public static function stringToRgb($value)
     {
         switch ($value) {
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_YELLOW:
+            case Color::AQUA:
+                return '00FFFF';
+            case Color::BLACK:
+                return '000000';
+            case Color::BLUE:
+                return '0000FF';
+            case Color::BROWN:
+                return 'A52A2A';
+            case Color::CYAN:
+                return '00FFFF';
+            case Color::DARKBLUE:
+                return '00008B';
+            case Color::DARKCYAN:
+                return '008B8B';
+            case Color::DARKGRAY:
+                return 'A9A9A9';
+            case Color::DARKGREEN:
+                return '006400';
+            case Color::DARKMAGENTA:
+                return '8B008B';
+            case Color::DARKORANGE:
+                return 'FF8C00';
+            case Color::DARKRED:
+                return '8B0000';
+            case Color::DARKVIOLET:
+                return '9400D3';
+            case Color::DARKYELLOW:
+                return '808000';
+            case Color::FUCHSIA:
+                return 'FF00FF';
+            case Color::GOLD:
+                return 'FFD700';
+            case Color::GRAY:
+                return '808080';
+            case Color::GREEN:
+                return '008000';
+            case Color::LIGHTBLUE:
+                return 'ADD8E6';
+            case Color::LIGHTCYAN:
+                return 'E0FFFF';
+            case Color::LIGHTGRAY:
+                return 'D3D3D3';
+            case Color::LIGHTGREEN:
+                return '90EE90';
+            case Color::LIGHTPINK:
+                return 'FFB6C1';
+            case Color::LIGHTYELLOW:
+                return 'FFFFE0';
+            case Color::LIME:
+                return '00FF00';
+            case Color::MAGENTA:
+                return 'FF00FF';
+            case Color::MAROON:
+                return '800000';
+            case Color::NAVY:
+                return '000080';
+            case Color::OLIVE:
+                return '808000';
+            case Color::ORANGE:
+                return 'FFA500';
+            case Color::PINK:
+                return 'FFC0CB';
+            case Color::PURPLE:
+                return '800080';
+            case Color::RED:
+                return 'FF0000';
+            case Color::SILVER:
+                return 'C0C0C0';
+            case Color::TAN:
+                return 'D2B48C';
+            case Color::TEAL:
+                return '008080';
+            case Color::TURQUOISE:
+                return '40E0D0';
+            case Color::VIOLET:
+                return 'EE82EE';
+            case Color::WHITE:
+                return 'FFFFFF';
+            case Color::YELLOW:
+                return 'FFFF00';
+
+                // deprecated constants
+            case FontColor::FGCOLOR_YELLOW:
                 return 'FFFF00';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_LIGHTGREEN:
+            case FontColor::FGCOLOR_LIGHTGREEN:
                 return '90EE90';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_CYAN:
+            case FontColor::FGCOLOR_CYAN:
                 return '00FFFF';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_MAGENTA:
+            case FontColor::FGCOLOR_MAGENTA:
                 return 'FF00FF';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_BLUE:
+            case FontColor::FGCOLOR_BLUE:
                 return '0000FF';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_RED:
+            case FontColor::FGCOLOR_RED:
                 return 'FF0000';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_DARKBLUE:
+            case FontColor::FGCOLOR_DARKBLUE:
                 return '00008B';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_DARKCYAN:
+            case FontColor::FGCOLOR_DARKCYAN:
                 return '008B8B';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_DARKGREEN:
+            case FontColor::FGCOLOR_DARKGREEN:
                 return '006400';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_DARKMAGENTA:
+            case FontColor::FGCOLOR_DARKMAGENTA:
                 return '8B008B';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_DARKRED:
+            case FontColor::FGCOLOR_DARKRED:
                 return '8B0000';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_DARKYELLOW:
+            case FontColor::FGCOLOR_DARKYELLOW:
                 return '8B8B00';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_DARKGRAY:
+            case FontColor::FGCOLOR_DARKGRAY:
                 return 'A9A9A9';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_LIGHTGRAY:
+            case FontColor::FGCOLOR_LIGHTGRAY:
                 return 'D3D3D3';
-            case \PhpOffice\PhpWord\Style\Font::FGCOLOR_BLACK:
+            case FontColor::FGCOLOR_BLACK:
                 return '000000';
         }
 

src/PhpWord/SimpleType/Color.php

@@ -0,0 +1,74 @@
+<?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
+ *
+ * @license     http://www.gnu.org/licenses/lgpl.txt LGPL version 3
+ */
+
+namespace PhpOffice\PhpWord\SimpleType;
+
+use PhpOffice\PhpWord\Shared\AbstractEnum;
+
+/**
+ * Colors.
+ * See https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.drawing.presetcolor
+ * See https://www.datypic.com/sc/ooxml/t-a_ST_PresetColorVal.html.
+ * See https://c-rex.net/samples/ooxml/e1/Part4/OOXML_P4_DOCX_ST_PresetColorVal_topic_ID0ELA5NB.html.
+ *
+ * Highlight colors limited to certain select colors.
+ * See https://c-rex.net/samples/ooxml/e1/Part4/OOXML_P4_DOCX_ST_HighlightColor_topic_ID0E4PY2.html.
+ */
+final class Color extends AbstractEnum
+{
+    const AQUA = 'aqua';
+    const BLACK = 'black'; // highlight color
+    const BLUE = 'blue'; // highlight color
+    const BROWN = 'brown';
+    const CYAN = 'cyan'; // highlight color
+    const DARKBLUE = 'darkBlue'; // highlight color
+    const DARKCYAN = 'darkCyan'; // highlight color
+    const DARKGRAY = 'darkGray';
+    const DARKGREEN = 'darkGreen'; // highlight color
+    const DARKMAGENTA = 'darkMagenta'; // highlight color
+    const DARKORANGE = 'darkOrange';
+    const DARKRED = 'darkRed'; // highlight color
+    const DARKVIOLET = 'darkViolet';
+    const DARKYELLOW = 'darkYellow'; // highlight color
+    const FUCHSIA = 'fuchsia';
+    const GOLD = 'gold';
+    const GRAY = 'gray';
+    const GREEN = 'green'; // highlight color
+    const LIGHTBLUE = 'lightBlue';
+    const LIGHTCYAN = 'lightCyan';
+    const LIGHTGRAY = 'lightGray'; // highlight color
+    const LIGHTGREEN = 'lightGreen';
+    const LIGHTPINK = 'lightPink';
+    const LIGHTYELLOW = 'lightYellow';
+    const LIME = 'lime';
+    const MAGENTA = 'magenta'; // highlight color
+    const MAROON = 'maroon';
+    const NAVY = 'navy';
+    const OLIVE = 'olive';
+    const ORANGE = 'orange';
+    const PINK = 'pink';
+    const PURPLE = 'purple';
+    const RED = 'red'; // highlight color
+    const SILVER = 'silver';
+    const TAN = 'tan';
+    const TEAL = 'teal';
+    const TURQUOISE = 'turqoise';
+    const VIOLET = 'violet';
+    const WHITE = 'white'; // highlight color
+    const YELLOW = 'yellow'; // highlight color
+}

src/PhpWord/Style/Font.php

@@ -53,10 +53,12 @@ class Font extends AbstractStyle
     /**
      * Foreground colors.
      *
+     * @deprecated 1.5 use \PhpOffice\PhpWord\SimpleType\Color instead
+     *
      * @const string
      */
     const FGCOLOR_YELLOW = 'yellow';
-    const FGCOLOR_LIGHTGREEN = 'green';
+    const FGCOLOR_LIGHTGREEN = 'lightGreen';
     const FGCOLOR_CYAN = 'cyan';
     const FGCOLOR_MAGENTA = 'magenta';
     const FGCOLOR_BLUE = 'blue';

tests/PhpWordTests/Shared/ConverterTest.php

@@ -19,6 +19,7 @@
 namespace PhpOffice\PhpWordTests\Shared;
 
 use PhpOffice\PhpWord\Shared\Converter;
+use PhpOffice\PhpWord\SimpleType\Color;
 
 /**
  * Test class for PhpOffice\PhpWord\Shared\Converter.
@@ -117,7 +118,55 @@ public function testHtmlToRGB(): void
         self::assertEquals([102, 119, 136], Converter::htmlToRgb('678')); // 3 characters
         self::assertEquals($flse, Converter::htmlToRgb('0F9D')); // 4 characters
         self::assertEquals([0, 0, 0], Converter::htmlToRgb('unknow')); // 6 characters, invalid
-        self::assertEquals([139, 0, 139], Converter::htmlToRgb(\PhpOffice\PhpWord\Style\Font::FGCOLOR_DARKMAGENTA)); // Constant
+        self::assertEquals([139, 0, 139], Converter::htmlToRgb(Color::DARKMAGENTA)); // Constant
+    }
+
+    /**
+     * Test SimpleType::Color. Ensure all colors come out to correct values.
+     * Verified against https://c-rex.net/samples/ooxml/e1/Part4/OOXML_P4_DOCX_ST_PresetColorVal_topic_ID0ELA5NB.html.
+     */
+    public function testBuiltInColors(): void
+    {
+        self::assertEquals([0, 255, 255], Converter::htmlToRgb(Color::AQUA));
+        self::assertEquals([0, 0, 0], Converter::htmlToRgb(Color::BLACK));
+        self::assertEquals([0, 0, 255], Converter::htmlToRgb(Color::BLUE));
+        self::assertEquals([165, 42, 42], Converter::htmlToRgb(Color::BROWN));
+        self::assertEquals([0, 255, 255], Converter::htmlToRgb(Color::CYAN));
+        self::assertEquals([0, 0, 139], Converter::htmlToRgb(Color::DARKBLUE));
+        self::assertEquals([0, 139, 139], Converter::htmlToRgb(Color::DARKCYAN));
+        self::assertEquals([169, 169, 169], Converter::htmlToRgb(Color::DARKGRAY));
+        self::assertEquals([0, 100, 0], Converter::htmlToRgb(Color::DARKGREEN));
+        self::assertEquals([139, 0, 139], Converter::htmlToRgb(Color::DARKMAGENTA));
+        self::assertEquals([255, 140, 0], Converter::htmlToRgb(Color::DARKORANGE));
+        self::assertEquals([139, 0, 0], Converter::htmlToRgb(Color::DARKRED));
+        self::assertEquals([148, 0, 211], Converter::htmlToRgb(Color::DARKVIOLET));
+        self::assertEquals([128, 128, 0], Converter::htmlToRgb(Color::DARKYELLOW));
+        self::assertEquals([255, 0, 255], Converter::htmlToRgb(Color::FUCHSIA));
+        self::assertEquals([255, 215, 0], Converter::htmlToRgb(Color::GOLD));
+        self::assertEquals([128, 128, 128], Converter::htmlToRgb(Color::GRAY));
+        self::assertEquals([0, 128, 0], Converter::htmlToRgb(Color::GREEN));
+        self::assertEquals([173, 216, 230], Converter::htmlToRgb(Color::LIGHTBLUE));
+        self::assertEquals([224, 255, 255], Converter::htmlToRgb(Color::LIGHTCYAN));
+        self::assertEquals([211, 211, 211], Converter::htmlToRgb(Color::LIGHTGRAY));
+        self::assertEquals([144, 238, 144], Converter::htmlToRgb(Color::LIGHTGREEN));
+        self::assertEquals([255, 182, 193], Converter::htmlToRgb(Color::LIGHTPINK));
+        self::assertEquals([255, 255, 224], Converter::htmlToRgb(Color::LIGHTYELLOW));
+        self::assertEquals([0, 255, 0], Converter::htmlToRgb(Color::LIME));
+        self::assertEquals([255, 0, 255], Converter::htmlToRgb(Color::MAGENTA));
+        self::assertEquals([128, 0, 0], Converter::htmlToRgb(Color::MAROON));
+        self::assertEquals([0, 0, 128], Converter::htmlToRgb(Color::NAVY));
+        self::assertEquals([128, 128, 0], Converter::htmlToRgb(Color::OLIVE));
+        self::assertEquals([255, 165, 0], Converter::htmlToRgb(Color::ORANGE));
+        self::assertEquals([255, 192, 203], Converter::htmlToRgb(Color::PINK));
+        self::assertEquals([128, 0, 128], Converter::htmlToRgb(Color::PURPLE));
+        self::assertEquals([255, 0, 0], Converter::htmlToRgb(Color::RED));
+        self::assertEquals([192, 192, 192], Converter::htmlToRgb(Color::SILVER));
+        self::assertEquals([210, 180, 140], Converter::htmlToRgb(Color::TAN));
+        self::assertEquals([0, 128, 128], Converter::htmlToRgb(Color::TEAL));
+        self::assertEquals([64, 224, 208], Converter::htmlToRgb(Color::TURQUOISE));
+        self::assertEquals([238, 130, 238], Converter::htmlToRgb(Color::VIOLET));
+        self::assertEquals([255, 255, 255], Converter::htmlToRgb(Color::WHITE));
+        self::assertEquals([255, 255, 0], Converter::htmlToRgb(Color::YELLOW));
     }
 
     /**

tests/PhpWordTests/Style/FontTest.php

@@ -20,6 +20,7 @@
 
 use PhpOffice\PhpWord\PhpWord;
 use PhpOffice\PhpWord\Settings;
+use PhpOffice\PhpWord\SimpleType\Color;
 use PhpOffice\PhpWord\SimpleType\Jc;
 use PhpOffice\PhpWord\Style\Font;
 use PhpOffice\PhpWord\Style\Language;
@@ -115,7 +116,7 @@ public function testSetStyleValueNormal(): void
             'doubleStrikethrough' => false,
             'smallCaps' => true,
             'allCaps' => false,
-            'fgColor' => Font::FGCOLOR_YELLOW,
+            'fgColor' => Color::YELLOW,
             'bgColor' => 'FFFF00',
             'lineHeight' => 2,
             'scale' => 150,

tests/PhpWordTests/Writer/ODText/Style/FontTest.php

@@ -123,7 +123,7 @@ public static function providerAllNamedColors()
             [Font::FGCOLOR_DARKGREEN, '006400'],
             [Font::FGCOLOR_DARKMAGENTA, '8B008B'],
             [Font::FGCOLOR_DARKRED, '8B0000'],
-            [Font::FGCOLOR_DARKYELLOW, '8B8B00'],
+            [Font::FGCOLOR_DARKYELLOW, '808000'],
             [Font::FGCOLOR_DARKGRAY, 'A9A9A9'],
             [Font::FGCOLOR_LIGHTGRAY, 'D3D3D3'],
             [Font::FGCOLOR_BLACK, '000000'],