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*.

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 '8B8B00';
+            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';