Merge pull request #4478 from oleibman/hyperlinkstyle

Hyperlink Styles

Author: oleibman

CHANGELOG.md

@@ -34,6 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 - Print Area and Row Break. [Issue #1275](https://github.com/PHPOffice/PhpSpreadsheet/issues/1275) [PR #4450](https://github.com/PHPOffice/PhpSpreadsheet/pull/4450)
 - Copy Styles after insertNewColumnBefore. [Issue #1425](https://github.com/PHPOffice/PhpSpreadsheet/issues/1425) [PR #4468](https://github.com/PHPOffice/PhpSpreadsheet/pull/4468)
 - Xls Writer Treat Hyperlink Starting with # as Internal. [Issue #56](https://github.com/PHPOffice/PhpSpreadsheet/issues/56) [PR #4453](https://github.com/PHPOffice/PhpSpreadsheet/pull/4453)
+- Hyperlink Styles. [Issue #1632](https://github.com/PHPOffice/PhpSpreadsheet/issues/1632) [PR #4478](https://github.com/PHPOffice/PhpSpreadsheet/pull/4478)
 - ODS Handling of Ceiling and Floor. [Issue #477](https://github.com/PHPOffice/PhpSpreadsheet/issues/407) [PR #4466](https://github.com/PHPOffice/PhpSpreadsheet/pull/4466)
 - Xlsx Reader Do Not Process Printer Settings for Dataonly. [Issue #4477](https://github.com/PHPOffice/PhpSpreadsheet/issues/4477) [PR #4480](https://github.com/PHPOffice/PhpSpreadsheet/pull/4480)
 

docs/topics/recipes.md

@@ -20,7 +20,7 @@ finding a specific document in a file repository or a document
 management system. For example Microsoft Sharepoint uses document
 metadata to search for a specific document in its document lists.
 
-<details>
+<details markdown>
   <summary>Click here for details of Spreadsheet Document Properties</summary>
 
 These are accessed in MS Excel from the "Info" option on the "File" menu:
@@ -67,7 +67,7 @@ $spreadsheet->getProperties()
 
 You can choose which properties to set or ignore.
 
-<details>
+<details markdown>
   <summary>Click here for details of Property Getters/Setters</summary>
 
 PhpSpreadsheet provides specific getters/setters for a number of pre-defined properties.
@@ -90,7 +90,7 @@ PhpSpreadsheet provides specific getters/setters for a number of pre-defined pro
 
 </details>
 
-<details>
+<details markdown>
   <summary>Click here for details of Custom Properties</summary>
 
 Additionally, PhpSpreadsheet supports the creation and reading of custom properties for those file formats that accept custom properties.
@@ -143,7 +143,7 @@ $spreadsheet->getProperties()
 
 A Spreadsheet consists of (very rarely) none, one or more Worksheets. If you have 1 or more Worksheets, then one (and only one) of those Worksheets can be "Active" (viewed or updated) at a time, but there will always be an "Active" Worksheet (unless you explicitly delete all of the Worksheets in the Spreadsheet).
 
-<details>
+<details markdown>
   <summary>Click here for details about Worksheets</summary>
 
 When you create a new Spreadsheet in MS Excel, it creates the Spreadsheet with a single Worksheet ("Sheet1")
@@ -278,7 +278,7 @@ define your own values as long as they are a valid MS Excel format.
 PhpSpreadsheet also provides a number of Wizards to help you create
 Date, Time and DateTime format masks.
 
-<details>
+<details markdown>
   <summary>Click here for an example of the Date/Time Wizards</summary>
 
 ```php
@@ -631,17 +631,35 @@ $spreadsheet->getActiveSheet()->getCell('A1')
 You can make a cell a clickable URL by setting its hyperlink property:
 
 ```php
-$spreadsheet->getActiveSheet()->setCellValue('E26', 'www.phpexcel.net');
-$spreadsheet->getActiveSheet()->getCell('E26')->getHyperlink()->setUrl('https://www.example.com');
+$spreadsheet->getActiveSheet()->setCellValue('E26', 'www.example.com');
+$spreadsheet->getActiveSheet()->getCell('E26')
+    ->getHyperlink()
+    ->setUrl('https://www.example.com');
 ```
 
 If you want to make a hyperlink to another worksheet/cell, use the
 following code:
 
 ```php
-$spreadsheet->getActiveSheet()->setCellValue('E26', 'www.phpexcel.net');
-$spreadsheet->getActiveSheet()->getCell('E26')->getHyperlink()->setUrl("sheet://'Sheetname'!A1");
+$spreadsheet->getActiveSheet()
+    ->setCellValue('E27', 'go to another sheet');
+$spreadsheet->getActiveSheet()->getCell('E27')
+    ->getHyperlink()
+    ->setUrl("sheet://'Sheetname'!A1");
+```
+
+Excel automatically supplies a special style when a hyperlink is
+entered into a cell. PhpSpreadsheet cannot do so. However,
+starting with release 4.3,
+you can mimic Excel's behavior with:
+```php
+$spreadsheet->getActiveSheet()
+    ->getStyle('E26')
+    ->getFont()
+    ->setHyperlinkTheme();
 ```
+This will set underline (all formats) and text color (always
+for Xlsx, and usually for other formats).
 
 ## Setting Printer Options for Excel files
 
@@ -824,7 +842,9 @@ $drawing = new \PhpOffice\PhpSpreadsheet\Worksheet\HeaderFooterDrawing();
 $drawing->setName('PhpSpreadsheet logo');
 $drawing->setPath('./images/PhpSpreadsheet_logo.png');
 $drawing->setHeight(36);
-$spreadsheet->getActiveSheet()->getHeaderFooter()->addImage($drawing, \PhpOffice\PhpSpreadsheet\Worksheet\HeaderFooter::IMAGE_HEADER_LEFT);
+$spreadsheet->getActiveSheet()
+    ->getHeaderFooter()
+    ->addImage($drawing, \PhpOffice\PhpSpreadsheet\Worksheet\HeaderFooter::IMAGE_HEADER_LEFT);
 ```
 
 ### Setting printing breaks on a row or column
@@ -2018,7 +2038,11 @@ $richText->createText('This invoice is ');
 $payable = $richText->createTextRun('payable within thirty days after the end of the month');
 $payable->getFont()->setBold(true);
 $payable->getFont()->setItalic(true);
-$payable->getFont()->setColor( new \PhpOffice\PhpSpreadsheet\Style\Color( \PhpOffice\PhpSpreadsheet\Style\Color::COLOR_DARKGREEN ) );
+$payable->getFont()->setColor(
+    new \PhpOffice\PhpSpreadsheet\Style\Color( 
+        \PhpOffice\PhpSpreadsheet\Style\Color::COLOR_DARKGREEN
+    )
+);
 $richText->createText(', unless specified otherwise on the invoice.');
 $spreadsheet->getActiveSheet()->getCell('A18')->setValue($richText);
 ```

mkdocs.yml

@@ -7,3 +7,5 @@ extra_css:
     - extra/extra.css
 extra_javascript:
     - extra/extrajs.js
+markdown_extensions:
+    - md_in_html

samples/Basic/02_Types.php

@@ -142,9 +142,11 @@
     ->getHyperlink()
     ->setUrl('https://github.com/PHPOffice/PhpSpreadsheet')
     ->setTooltip('Navigate to PhpSpreadsheet website');
+$spreadsheet->getActiveSheet()->getStyle('C17')->getFont()->setHyperlinkTheme();
 
 $spreadsheet->getActiveSheet()
     ->setCellValue('C18', '=HYPERLINK("mailto:abc@def.com","abc@def.com")');
+$spreadsheet->getActiveSheet()->getStyle('C18')->getFont()->setHyperlinkTheme();
 
 $spreadsheet->getActiveSheet()
     ->setCellValue('A20', 'String')

samples/templates/sampleSpreadsheet.php

@@ -248,16 +248,18 @@
 
 // Add a hyperlink to the sheet
 $helper->log('Add a hyperlink to an external website');
-$spreadsheet->getActiveSheet()->setCellValue('E26', 'www.phpexcel.net');
+$spreadsheet->getActiveSheet()->setCellValue('E26', 'www.example.com');
 $spreadsheet->getActiveSheet()->getCell('E26')->getHyperlink()->setUrl('https://www.example.com');
 $spreadsheet->getActiveSheet()->getCell('E26')->getHyperlink()->setTooltip('Navigate to website');
 $spreadsheet->getActiveSheet()->getStyle('E26')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
+$spreadsheet->getActiveSheet()->getStyle('E26')->getFont()->setHyperlinkTheme();
 
 $helper->log('Add a hyperlink to another cell on a different worksheet within the workbook');
 $spreadsheet->getActiveSheet()->setCellValue('E27', 'Terms and conditions');
 $spreadsheet->getActiveSheet()->getCell('E27')->getHyperlink()->setUrl("sheet://'Terms and conditions'!A1");
 $spreadsheet->getActiveSheet()->getCell('E27')->getHyperlink()->setTooltip('Review terms and conditions');
 $spreadsheet->getActiveSheet()->getStyle('E27')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
+$spreadsheet->getActiveSheet()->getStyle('E27')->getFont()->setHyperlinkTheme();
 
 // Add a drawing to the worksheet
 $helper->log('Add a drawing to the worksheet');

samples/templates/sampleSpreadsheet2.php

@@ -248,16 +248,18 @@
 
 // Add a hyperlink to the sheet
 $helper->log('Add a hyperlink to an external website');
-$spreadsheet->getActiveSheet()->setCellValue('E26', 'www.phpexcel.net');
+$spreadsheet->getActiveSheet()->setCellValue('E26', 'www.example.com');
 $spreadsheet->getActiveSheet()->getCell('E26')->getHyperlink()->setUrl('https://www.example.com');
 $spreadsheet->getActiveSheet()->getCell('E26')->getHyperlink()->setTooltip('Navigate to website');
 $spreadsheet->getActiveSheet()->getStyle('E26')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
+$spreadsheet->getActiveSheet()->getStyle('E26')->getFont()->setHyperlinkTheme();
 
 $helper->log('Add a hyperlink to another cell on a different worksheet within the workbook');
 $spreadsheet->getActiveSheet()->setCellValue('E27', 'Terms and conditions');
 $spreadsheet->getActiveSheet()->getCell('E27')->getHyperlink()->setUrl("sheet://'Terms and conditions'!A1");
 $spreadsheet->getActiveSheet()->getCell('E27')->getHyperlink()->setTooltip('Review terms and conditions');
 $spreadsheet->getActiveSheet()->getStyle('E27')->getAlignment()->setHorizontal(Alignment::HORIZONTAL_RIGHT);
+$spreadsheet->getActiveSheet()->getStyle('E27')->getFont()->setHyperlinkTheme();
 
 // Add a drawing to the worksheet
 $helper->log('Add a drawing to the worksheet');

src/PhpSpreadsheet/Reader/Xlsx/Styles.php

@@ -104,7 +104,14 @@ public function readFontStyle(Font $fontStyle, SimpleXMLElement $fontStyleXml):
             $attr = $this->getStyleAttributes($fontStyleXml->strike);
             $fontStyle->setStrikethrough(!isset($attr['val']) || self::boolean((string) $attr['val']));
         }
-        $fontStyle->getColor()->setARGB($this->readColor($fontStyleXml->color));
+        $fontStyle->getColor()
+            ->setARGB(
+                $this->readColor($fontStyleXml->color)
+            );
+        $theme = $this->readColorTheme($fontStyleXml->color);
+        if ($theme >= 0) {
+            $fontStyle->getColor()->setTheme($theme);
+        }
 
         if (isset($fontStyleXml->u)) {
             $attr = $this->getStyleAttributes($fontStyleXml->u);
@@ -398,6 +405,17 @@ public function readProtectionHidden(Style $docStyle, SimpleXMLElement $style):
         }
     }
 
+    public function readColorTheme(SimpleXMLElement $color): int
+    {
+        $attr = $this->getStyleAttributes($color);
+        $retVal = -1;
+        if (isset($attr['theme']) && is_numeric((string) $attr['theme']) && !isset($attr['tint'])) {
+            $retVal = (int) $attr['theme'];
+        }
+
+        return $retVal;
+    }
+
     public function readColor(SimpleXMLElement $color, bool $background = false): string
     {
         $attr = $this->getStyleAttributes($color);

src/PhpSpreadsheet/Style/Color.php

@@ -2,6 +2,8 @@
 
 namespace PhpOffice\PhpSpreadsheet\Style;
 
+use PhpOffice\PhpSpreadsheet\Theme;
+
 class Color extends Supervisor
 {
     const NAMED_COLORS = [
@@ -111,6 +113,8 @@ class Color extends Supervisor
 
     private bool $hasChanged = false;
 
+    private int $theme = -1;
+
     /**
      * Create a new Color.
      *
@@ -176,21 +180,28 @@ public function getStyleArray(array $array): array
      * $spreadsheet->getActiveSheet()->getStyle('B2')->getFont()->getColor()->applyFromArray(['rgb' => '808080']);
      * </code>
      *
-     * @param array{rgb?: string, argb?: string} $styleArray Array containing style information
+     * @param array{rgb?: string, argb?: string, theme?: int} $styleArray Array containing style information
      *
      * @return $this
      */
     public function applyFromArray(array $styleArray): static
     {
         if ($this->isSupervisor) {
-            $this->getActiveSheet()->getStyle($this->getSelectedCells())->applyFromArray($this->getStyleArray($styleArray));
+            $this->getActiveSheet()
+                ->getStyle($this->getSelectedCells())
+                ->applyFromArray(
+                    $this->getStyleArray($styleArray)
+                );
         } else {
             if (isset($styleArray['rgb'])) {
                 $this->setRGB($styleArray['rgb']);
             }
             if (isset($styleArray['argb'])) {
                 $this->setARGB($styleArray['argb']);
             }
+            if (isset($styleArray['theme'])) {
+                $this->setTheme($styleArray['theme']);
+            }
         }
 
         return $this;
@@ -237,6 +248,7 @@ public function getARGB(): ?string
     public function setARGB(?string $colorValue = self::COLOR_BLACK, bool $nullStringOkay = false): static
     {
         $this->hasChanged = true;
+        $this->setTheme(-1);
         if (!$nullStringOkay || $colorValue !== '') {
             $colorValue = $this->validateColor($colorValue);
             if ($colorValue === '') {
@@ -402,6 +414,7 @@ public function getHashCode(): string
 
         return md5(
             $this->argb
+            . (string) $this->theme
             . __CLASS__
         );
     }
@@ -411,6 +424,7 @@ protected function exportArray1(): array
     {
         $exportedArray = [];
         $this->exportArray2($exportedArray, 'argb', $this->getARGB());
+        $this->exportArray2($exportedArray, 'theme', $this->getTheme());
 
         return $exportedArray;
     }
@@ -423,4 +437,42 @@ public function getHasChanged(): bool
 
         return $this->hasChanged;
     }
+
+    public function getTheme(): int
+    {
+        if ($this->isSupervisor) {
+            return $this->getSharedComponent()->getTheme();
+        }
+
+        return $this->theme;
+    }
+
+    public function setTheme(int $theme): self
+    {
+        $this->hasChanged = true;
+
+        if ($this->isSupervisor) {
+            $styleArray = $this->getStyleArray(['theme' => $theme]);
+            $this->getActiveSheet()
+                ->getStyle($this->getSelectedCells())
+                ->applyFromArray($styleArray);
+        } else {
+            $this->theme = $theme;
+        }
+
+        return $this;
+    }
+
+    public function setHyperlinkTheme(): self
+    {
+        $rgb = $this->getActiveSheet()
+            ->getParent()
+            ?->getTheme()
+            ->getThemeColors();
+        if (is_array($rgb) && array_key_exists('hlink', $rgb)) {
+            $this->setRGB($rgb['hlink']);
+        }
+
+        return $this->setTheme(Theme::HYPERLINK_THEME);
+    }
 }

src/PhpSpreadsheet/Style/Font.php

@@ -206,7 +206,10 @@ public function applyFromArray(array $styleArray): static
                 $this->setStrikethrough($styleArray['strikethrough']);
             }
             if (isset($styleArray['color'])) {
-                $this->getColor()->applyFromArray($styleArray['color']);
+                /** @var array{rgb?: string, argb?: string, theme?: int} */
+                $temp = $styleArray['color'];
+                $this->getColor()
+                    ->applyFromArray($temp);
             }
             if (isset($styleArray['size'])) {
                 $this->setSize($styleArray['size']);
@@ -398,9 +401,6 @@ public function getBold(): ?bool
      */
     public function setBold(bool $bold): static
     {
-        if ($bold == '') {
-            $bold = false;
-        }
         if ($this->isSupervisor) {
             $styleArray = $this->getStyleArray(['bold' => $bold]);
             $this->getActiveSheet()->getStyle($this->getSelectedCells())->applyFromArray($styleArray);
@@ -430,9 +430,6 @@ public function getItalic(): ?bool
      */
     public function setItalic(bool $italic): static
     {
-        if ($italic == '') {
-            $italic = false;
-        }
         if ($this->isSupervisor) {
             $styleArray = $this->getStyleArray(['italic' => $italic]);
             $this->getActiveSheet()->getStyle($this->getSelectedCells())->applyFromArray($styleArray);
@@ -669,10 +666,6 @@ public function getStrikethrough(): ?bool
      */
     public function setStrikethrough(bool $strikethru): static
     {
-        if ($strikethru == '') {
-            $strikethru = false;
-        }
-
         if ($this->isSupervisor) {
             $styleArray = $this->getStyleArray(['strikethrough' => $strikethru]);
             $this->getActiveSheet()->getStyle($this->getSelectedCells())->applyFromArray($styleArray);
@@ -830,6 +823,14 @@ public function getCap(): ?string
         return $this->cap;
     }
 
+    public function setHyperlinkTheme(): self
+    {
+        $this->color->setHyperlinkTheme();
+        $this->setUnderline(self::UNDERLINE_SINGLE);
+
+        return $this;
+    }
+
     /**
      * Implement PHP __clone to create a deep clone, not just a shallow copy.
      */

src/PhpSpreadsheet/Theme.php

@@ -8,6 +8,7 @@ class Theme
 
     private string $themeFontName = 'Office';
 
+    public const HYPERLINK_THEME = 10;
     public const COLOR_SCHEME_2013_PLUS_NAME = 'Office 2013+';
     public const COLOR_SCHEME_2013_PLUS = [
         'dk1' => '000000',