├── src
    ├── HtmlProcessor
    │   ├── HtmlNormalizer.php
    │   ├── HtmlPruner.php
    │   ├── CssToAttributeConverter.php
    │   └── AbstractHtmlProcessor.php
    ├── Utilities
    │   ├── ArrayIntersector.php
    │   └── CssConcatenator.php
    ├── Css
    │   ├── StyleRule.php
    │   └── CssDocument.php
    └── CssInliner.php
├── phpunit.xml
├── LICENSE
├── composer.json
├── CHANGELOG.md
└── README.md


/src/HtmlProcessor/HtmlNormalizer.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Pelago\Emogrifier\HtmlProcessor;
 6 | 
 7 | /**
 8 |  * Normalizes HTML:
 9 |  * - add a document type (HTML5) if missing
10 |  * - disentangle incorrectly nested tags
11 |  * - add HEAD and BODY elements (if they are missing)
12 |  * - reformat the HTML
13 |  */
14 | class HtmlNormalizer extends AbstractHtmlProcessor
15 | {
16 | }
17 | 


--------------------------------------------------------------------------------
/phpunit.xml:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="UTF-8"?>
 2 | <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 3 |          xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/8.5/phpunit.xsd"
 4 |          bootstrap="vendor/autoload.php"
 5 |          colors="true"
 6 |          executionOrder="depends,defects"
 7 |          forceCoversAnnotation="true"
 8 |          beStrictAboutCoversAnnotation="true"
 9 |          beStrictAboutOutputDuringTests="true"
10 |          beStrictAboutTodoAnnotatedTests="true"
11 |          verbose="true">
12 |   <testsuites>
13 |     <testsuite name="default">
14 |       <directory>tests</directory>
15 |     </testsuite>
16 |   </testsuites>
17 | 
18 |   <filter>
19 |     <whitelist processUncoveredFilesFromWhitelist="true">
20 |       <directory suffix=".php">src</directory>
21 |     </whitelist>
22 |   </filter>
23 | </phpunit>
24 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2008-2018 Pelago
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/src/Utilities/ArrayIntersector.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Pelago\Emogrifier\Utilities;
 6 | 
 7 | /**
 8 |  * When computing many array intersections using the same array, it is more efficient to use `array_flip()` first and
 9 |  * then `array_intersect_key()`, than `array_intersect()`.  See the discussion at
10 |  * {@link https://stackoverflow.com/questions/6329211/php-array-intersect-efficiency Stack Overflow} for more
11 |  * information.
12 |  *
13 |  * Of course, this is only possible if the arrays contain integer or string values, and either don't contain duplicates,
14 |  * or that fact that duplicates will be removed does not matter.
15 |  *
16 |  * This class takes care of the detail.
17 |  *
18 |  * @internal
19 |  */
20 | class ArrayIntersector
21 | {
22 |     /**
23 |      * the array with which the object was constructed, with all its keys exchanged with their associated values
24 |      *
25 |      * @var array<array-key, array-key>
26 |      */
27 |     private $invertedArray;
28 | 
29 |     /**
30 |      * Constructs the object with the array that will be reused for many intersection computations.
31 |      *
32 |      * @param array<array-key, array-key> $array
33 |      */
34 |     public function __construct(array $array)
35 |     {
36 |         $this->invertedArray = \array_flip($array);
37 |     }
38 | 
39 |     /**
40 |      * Computes the intersection of `$array` and the array with which this object was constructed.
41 |      *
42 |      * @param array<array-key, array-key> $array
43 |      *
44 |      * @return array<array-key, array-key>
45 |      *         Returns an array containing all of the values in `$array` whose values exist in the array
46 |      *         with which this object was constructed.  Note that keys are preserved, order is maintained, but
47 |      *         duplicates are removed.
48 |      */
49 |     public function intersectWith(array $array): array
50 |     {
51 |         $invertedArray = \array_flip($array);
52 | 
53 |         $invertedIntersection = \array_intersect_key($invertedArray, $this->invertedArray);
54 | 
55 |         return \array_flip($invertedIntersection);
56 |     }
57 | }
58 | 


--------------------------------------------------------------------------------
/src/Css/StyleRule.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Pelago\Emogrifier\Css;
 6 | 
 7 | use Sabberworm\CSS\Property\Selector;
 8 | use Sabberworm\CSS\RuleSet\DeclarationBlock;
 9 | 
10 | /**
11 |  * This class represents a CSS style rule, including selectors, a declaration block, and an optional containing at-rule.
12 |  *
13 |  * @internal
14 |  */
15 | class StyleRule
16 | {
17 |     /**
18 |      * @var DeclarationBlock
19 |      */
20 |     private $declarationBlock;
21 | 
22 |     /**
23 |      * @var string
24 |      */
25 |     private $containingAtRule;
26 | 
27 |     /**
28 |      * @param DeclarationBlock $declarationBlock
29 |      * @param string $containingAtRule e.g. `@media screen and (max-width: 480px)`
30 |      */
31 |     public function __construct(DeclarationBlock $declarationBlock, string $containingAtRule = '')
32 |     {
33 |         $this->declarationBlock = $declarationBlock;
34 |         $this->containingAtRule = \trim($containingAtRule);
35 |     }
36 | 
37 |     /**
38 |      * @return array<int, string> the selectors, e.g. `["h1", "p"]`
39 |      */
40 |     public function getSelectors(): array
41 |     {
42 |         /** @var array<int, Selector> $selectors */
43 |         $selectors = $this->declarationBlock->getSelectors();
44 |         return \array_map(
45 |             static function (Selector $selector): string {
46 |                 return (string)$selector;
47 |             },
48 |             $selectors
49 |         );
50 |     }
51 | 
52 |     /**
53 |      * @return string the CSS declarations, separated and followed by a semicolon, e.g., `color: red; height: 4px;`
54 |      */
55 |     public function getDeclarationAsText(): string
56 |     {
57 |         return \implode(' ', $this->declarationBlock->getRules());
58 |     }
59 | 
60 |     /**
61 |      * Checks whether the declaration block has at least one declaration.
62 |      */
63 |     public function hasAtLeastOneDeclaration(): bool
64 |     {
65 |         return $this->declarationBlock->getRules() !== [];
66 |     }
67 | 
68 |     /**
69 |      * @returns string e.g. `@media screen and (max-width: 480px)`, or an empty string
70 |      */
71 |     public function getContainingAtRule(): string
72 |     {
73 |         return $this->containingAtRule;
74 |     }
75 | 
76 |     /**
77 |      * Checks whether the containing at-rule is non-empty and has any non-whitespace characters.
78 |      */
79 |     public function hasContainingAtRule(): bool
80 |     {
81 |         return $this->getContainingAtRule() !== '';
82 |     }
83 | }
84 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
  1 | {
  2 |     "name": "pelago/emogrifier",
  3 |     "description": "Converts CSS styles into inline style attributes in your HTML code",
  4 |     "keywords": [
  5 |         "email",
  6 |         "css",
  7 |         "pre-processing"
  8 |     ],
  9 |     "homepage": "https://www.myintervals.com/emogrifier.php",
 10 |     "license": "MIT",
 11 |     "authors": [
 12 |         {
 13 |             "name": "Oliver Klee",
 14 |             "email": "github@oliverklee.de"
 15 |         },
 16 |         {
 17 |             "name": "Zoli Szabó",
 18 |             "email": "zoli.szabo+github@gmail.com"
 19 |         },
 20 |         {
 21 |             "name": "John Reeve",
 22 |             "email": "jreeve@pelagodesign.com"
 23 |         },
 24 |         {
 25 |             "name": "Jake Hotson",
 26 |             "email": "jake@qzdesign.co.uk"
 27 |         },
 28 |         {
 29 |             "name": "Cameron Brooks"
 30 |         },
 31 |         {
 32 |             "name": "Jaime Prado"
 33 |         }
 34 |     ],
 35 |     "require": {
 36 |         "php": "~7.2.0 || ~7.3.0 || ~7.4.0 || ~8.0.0",
 37 |         "ext-dom": "*",
 38 |         "ext-libxml": "*",
 39 |         "sabberworm/php-css-parser": "^8.3.1",
 40 |         "symfony/css-selector": "^3.4.32 || ^4.4 || ^5.2 || ^6.0"
 41 |     },
 42 |     "require-dev": {
 43 |         "php-parallel-lint/php-parallel-lint": "^1.3.0",
 44 |         "phpunit/phpunit": "^8.5.16",
 45 |         "rawr/cross-data-providers": "^2.3.0"
 46 |     },
 47 |     "config": {
 48 |         "preferred-install": {
 49 |             "*": "dist"
 50 |         },
 51 |         "sort-packages": true
 52 |     },
 53 |     "extra": {
 54 |         "branch-alias": {
 55 |             "dev-main": "6.0.x-dev"
 56 |         }
 57 |     },
 58 |     "autoload": {
 59 |         "psr-4": {
 60 |             "Pelago\\Emogrifier\\": "src/"
 61 |         }
 62 |     },
 63 |     "autoload-dev": {
 64 |         "psr-4": {
 65 |             "Pelago\\Emogrifier\\Tests\\": "tests/"
 66 |         }
 67 |     },
 68 |     "prefer-stable": true,
 69 |     "scripts": {
 70 |         "ci": [
 71 |             "@ci:static",
 72 |             "@ci:dynamic"
 73 |         ],
 74 |         "ci:composer:normalize": "@php \"./.phive/composer-normalize\" --dry-run",
 75 |         "ci:dynamic": [
 76 |             "@ci:tests"
 77 |         ],
 78 |         "ci:php:fixer": "@php \"./.phive/php-cs-fixer\" --config=config/php-cs-fixer.php fix --dry-run -v --show-progress=dots config/ src/ tests/",
 79 |         "ci:php:lint": "\"./vendor/bin/parallel-lint\" config src tests",
 80 |         "ci:php:md": "@php \"./.phive/phpmd\" src text config/phpmd.xml",
 81 |         "ci:php:psalm": "@php \"./.phive/psalm\" --show-info=false",
 82 |         "ci:php:sniff": "@php \"./.phive/phpcs\" config src tests",
 83 |         "ci:static": [
 84 |             "@ci:composer:normalize",
 85 |             "@ci:php:lint",
 86 |             "@ci:php:sniff",
 87 |             "@ci:php:fixer",
 88 |             "@ci:php:md",
 89 |             "@ci:php:psalm"
 90 |         ],
 91 |         "ci:tests": [
 92 |             "@ci:tests:unit"
 93 |         ],
 94 |         "ci:tests:sof": "@php \"./vendor/bin/phpunit\" --stop-on-failure",
 95 |         "ci:tests:unit": "@php \"./vendor/bin/phpunit\"",
 96 |         "composer:normalize": "@php \"./.phive/composer-normalize\"",
 97 |         "php:fix": "@php \"./.phive/php-cs-fixer\" --config=config/php-cs-fixer.php fix config/ src/ tests/",
 98 |         "php:version": "@php -v | grep -Po 'PHP\\s++\\K(?:\\d++\\.)*+\\d++(?:-\\w++)?+'",
 99 |         "psalm:baseline": "@php \"./.phive/psalm\" --set-baseline=psalm.baseline.xml",
100 |         "psalm:cc": "@php \"./.phive/psalm\" --clear-cache"
101 |     },
102 |     "scripts-descriptions": {
103 |         "ci": "Runs all dynamic and static code checks.",
104 |         "ci:composer:normalize": "Checks the formatting and structure of the composer.json.",
105 |         "ci:dynamic": "Runs all dynamic tests (i.e., currently, the unit tests).",
106 |         "ci:php:fixer": "Checks the code style with PHP CS Fixer.",
107 |         "ci:php:lint": "Lints the PHP files for syntax errors.",
108 |         "ci:php:md": "Checks the code complexity with PHPMD.",
109 |         "ci:php:psalm": "Checks the types with Psalm.",
110 |         "ci:php:sniff": "Checks the code style with PHP_CodeSniffer.",
111 |         "ci:static": "Runs all static code analysis checks for the code and the composer.json.",
112 |         "ci:tests": "Runs all dynamic tests (i.e., currently, the unit tests).",
113 |         "ci:tests:sof": "Runs the unit tests and stops at the first failure.",
114 |         "ci:tests:unit": "Runs all unit tests.",
115 |         "composer:normalize": "Reformats and sorts the composer.json file.",
116 |         "php:fix": "Reformats the code with php-cs-fixer.",
117 |         "php:version": "Outputs the installed PHP version.",
118 |         "psalm:baseline": "Updates the Psalm baseline file to match the code.",
119 |         "psalm:cc": "Clears the Psalm cache."
120 |     },
121 |     "support": {
122 |         "issues": "https://github.com/MyIntervals/emogrifier/issues",
123 |         "source": "https://github.com/MyIntervals/emogrifier"
124 |     }
125 | }
126 | 


--------------------------------------------------------------------------------
/src/HtmlProcessor/HtmlPruner.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Pelago\Emogrifier\HtmlProcessor;
  6 | 
  7 | use Pelago\Emogrifier\CssInliner;
  8 | use Pelago\Emogrifier\Utilities\ArrayIntersector;
  9 | 
 10 | /**
 11 |  * This class can remove things from HTML.
 12 |  */
 13 | class HtmlPruner extends AbstractHtmlProcessor
 14 | {
 15 |     /**
 16 |      * We need to look for display:none, but we need to do a case-insensitive search. Since DOMDocument only
 17 |      * supports XPath 1.0, lower-case() isn't available to us. We've thus far only set attributes to lowercase,
 18 |      * not attribute values. Consequently, we need to translate() the letters that would be in 'NONE' ("NOE")
 19 |      * to lowercase.
 20 |      *
 21 |      * @var string
 22 |      */
 23 |     private const DISPLAY_NONE_MATCHER
 24 |         = '//*[@style and contains(translate(translate(@style," ",""),"NOE","noe"),"display:none")'
 25 |         . ' and not(@class and contains(concat(" ", normalize-space(@class), " "), " -emogrifier-keep "))]';
 26 | 
 27 |     /**
 28 |      * Removes elements that have a "display: none;" style.
 29 |      *
 30 |      * @return self fluent interface
 31 |      */
 32 |     public function removeElementsWithDisplayNone(): self
 33 |     {
 34 |         $elementsWithStyleDisplayNone = $this->getXPath()->query(self::DISPLAY_NONE_MATCHER);
 35 |         if ($elementsWithStyleDisplayNone->length === 0) {
 36 |             return $this;
 37 |         }
 38 | 
 39 |         foreach ($elementsWithStyleDisplayNone as $element) {
 40 |             $parentNode = $element->parentNode;
 41 |             if ($parentNode !== null) {
 42 |                 $parentNode->removeChild($element);
 43 |             }
 44 |         }
 45 | 
 46 |         return $this;
 47 |     }
 48 | 
 49 |     /**
 50 |      * Removes classes that are no longer required (e.g. because there are no longer any CSS rules that reference them)
 51 |      * from `class` attributes.
 52 |      *
 53 |      * Note that this does not inspect the CSS, but expects to be provided with a list of classes that are still in use.
 54 |      *
 55 |      * This method also has the (presumably beneficial) side-effect of minifying (removing superfluous whitespace from)
 56 |      * `class` attributes.
 57 |      *
 58 |      * @param array<array-key, string> $classesToKeep names of classes that should not be removed
 59 |      *
 60 |      * @return self fluent interface
 61 |      */
 62 |     public function removeRedundantClasses(array $classesToKeep = []): self
 63 |     {
 64 |         $elementsWithClassAttribute = $this->getXPath()->query('//*[@class]');
 65 | 
 66 |         if ($classesToKeep !== []) {
 67 |             $this->removeClassesFromElements($elementsWithClassAttribute, $classesToKeep);
 68 |         } else {
 69 |             // Avoid unnecessary processing if there are no classes to keep.
 70 |             $this->removeClassAttributeFromElements($elementsWithClassAttribute);
 71 |         }
 72 | 
 73 |         return $this;
 74 |     }
 75 | 
 76 |     /**
 77 |      * Removes classes from the `class` attribute of each element in `$elements`, except any in `$classesToKeep`,
 78 |      * removing the `class` attribute itself if the resultant list is empty.
 79 |      *
 80 |      * @param \DOMNodeList $elements
 81 |      * @param array<array-key, string> $classesToKeep
 82 |      */
 83 |     private function removeClassesFromElements(\DOMNodeList $elements, array $classesToKeep): void
 84 |     {
 85 |         $classesToKeepIntersector = new ArrayIntersector($classesToKeep);
 86 | 
 87 |         /** @var \DOMElement $element */
 88 |         foreach ($elements as $element) {
 89 |             $elementClasses = \preg_split('/\\s++/', \trim($element->getAttribute('class')));
 90 |             $elementClassesToKeep = $classesToKeepIntersector->intersectWith($elementClasses);
 91 |             if ($elementClassesToKeep !== []) {
 92 |                 $element->setAttribute('class', \implode(' ', $elementClassesToKeep));
 93 |             } else {
 94 |                 $element->removeAttribute('class');
 95 |             }
 96 |         }
 97 |     }
 98 | 
 99 |     /**
100 |      * Removes the `class` attribute from each element in `$elements`.
101 |      *
102 |      * @param \DOMNodeList $elements
103 |      */
104 |     private function removeClassAttributeFromElements(\DOMNodeList $elements): void
105 |     {
106 |         /** @var \DOMElement $element */
107 |         foreach ($elements as $element) {
108 |             $element->removeAttribute('class');
109 |         }
110 |     }
111 | 
112 |     /**
113 |      * After CSS has been inlined, there will likely be some classes in `class` attributes that are no longer referenced
114 |      * by any remaining (uninlinable) CSS.  This method removes such classes.
115 |      *
116 |      * Note that it does not inspect the remaining CSS, but uses information readily available from the `CssInliner`
117 |      * instance about the CSS rules that could not be inlined.
118 |      *
119 |      * @param CssInliner $cssInliner object instance that performed the CSS inlining
120 |      *
121 |      * @return self fluent interface
122 |      *
123 |      * @throws \BadMethodCallException if `inlineCss` has not first been called on `$cssInliner`
124 |      */
125 |     public function removeRedundantClassesAfterCssInlined(CssInliner $cssInliner): self
126 |     {
127 |         $classesToKeepAsKeys = [];
128 |         foreach ($cssInliner->getMatchingUninlinableSelectors() as $selector) {
129 |             \preg_match_all('/\\.(-?+[_a-zA-Z][\\w\\-]*+)/', $selector, $matches);
130 |             $classesToKeepAsKeys += \array_fill_keys($matches[1], true);
131 |         }
132 | 
133 |         $this->removeRedundantClasses(\array_keys($classesToKeepAsKeys));
134 | 
135 |         return $this;
136 |     }
137 | }
138 | 


--------------------------------------------------------------------------------
/src/Css/CssDocument.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Pelago\Emogrifier\Css;
  6 | 
  7 | use Sabberworm\CSS\CSSList\AtRuleBlockList as CssAtRuleBlockList;
  8 | use Sabberworm\CSS\CSSList\Document as SabberwormCssDocument;
  9 | use Sabberworm\CSS\Parser as CssParser;
 10 | use Sabberworm\CSS\Property\AtRule as CssAtRule;
 11 | use Sabberworm\CSS\Property\Charset as CssCharset;
 12 | use Sabberworm\CSS\Property\Import as CssImport;
 13 | use Sabberworm\CSS\Renderable as CssRenderable;
 14 | use Sabberworm\CSS\RuleSet\DeclarationBlock as CssDeclarationBlock;
 15 | use Sabberworm\CSS\RuleSet\RuleSet as CssRuleSet;
 16 | 
 17 | /**
 18 |  * Parses and stores a CSS document from a string of CSS, and provides methods to obtain the CSS in parts or as data
 19 |  * structures.
 20 |  *
 21 |  * @internal
 22 |  */
 23 | class CssDocument
 24 | {
 25 |     /**
 26 |      * @var SabberwormCssDocument
 27 |      */
 28 |     private $sabberwormCssDocument;
 29 | 
 30 |     /**
 31 |      * `@import` rules must precede all other types of rules, except `@charset` rules.  This property is used while
 32 |      * rendering at-rules to enforce that.
 33 |      *
 34 |      * @var bool
 35 |      */
 36 |     private $isImportRuleAllowed = true;
 37 | 
 38 |     /**
 39 |      * @param string $css
 40 |      */
 41 |     public function __construct(string $css)
 42 |     {
 43 |         $cssParser = new CssParser($css);
 44 |         /** @var SabberwormCssDocument $sabberwormCssDocument */
 45 |         $sabberwormCssDocument = $cssParser->parse();
 46 |         $this->sabberwormCssDocument = $sabberwormCssDocument;
 47 |     }
 48 | 
 49 |     /**
 50 |      * Collates the media query, selectors and declarations for individual rules from the parsed CSS, in order.
 51 |      *
 52 |      * @param array<array-key, string> $allowedMediaTypes
 53 |      *
 54 |      * @return array<int, StyleRule>
 55 |      */
 56 |     public function getStyleRulesData(array $allowedMediaTypes): array
 57 |     {
 58 |         $ruleMatches = [];
 59 |         /** @var CssRenderable $rule */
 60 |         foreach ($this->sabberwormCssDocument->getContents() as $rule) {
 61 |             if ($rule instanceof CssAtRuleBlockList) {
 62 |                 $containingAtRule = $this->getFilteredAtIdentifierAndRule($rule, $allowedMediaTypes);
 63 |                 if (\is_string($containingAtRule)) {
 64 |                     /** @var CssRenderable $nestedRule */
 65 |                     foreach ($rule->getContents() as $nestedRule) {
 66 |                         if ($nestedRule instanceof CssDeclarationBlock) {
 67 |                             $ruleMatches[] = new StyleRule($nestedRule, $containingAtRule);
 68 |                         }
 69 |                     }
 70 |                 }
 71 |             } elseif ($rule instanceof CssDeclarationBlock) {
 72 |                 $ruleMatches[] = new StyleRule($rule);
 73 |             }
 74 |         }
 75 | 
 76 |         return $ruleMatches;
 77 |     }
 78 | 
 79 |     /**
 80 |      * Renders at-rules from the parsed CSS that are valid and not conditional group rules (i.e. not rules such as
 81 |      * `@media` which contain style rules whose data is returned by {@see getStyleRulesData}).  Also does not render
 82 |      * `@charset` rules; these are discarded (only UTF-8 is supported).
 83 |      *
 84 |      * @return string
 85 |      */
 86 |     public function renderNonConditionalAtRules(): string
 87 |     {
 88 |         $this->isImportRuleAllowed = true;
 89 |         /** @var array<int, CssRenderable> $cssContents */
 90 |         $cssContents = $this->sabberwormCssDocument->getContents();
 91 |         $atRules = \array_filter($cssContents, [$this, 'isValidAtRuleToRender']);
 92 | 
 93 |         if ($atRules === []) {
 94 |             return '';
 95 |         }
 96 | 
 97 |         $atRulesDocument = new SabberwormCssDocument();
 98 |         $atRulesDocument->setContents($atRules);
 99 | 
100 |         /** @var string $renderedRules */
101 |         $renderedRules = $atRulesDocument->render();
102 |         return $renderedRules;
103 |     }
104 | 
105 |     /**
106 |      * @param CssAtRuleBlockList $rule
107 |      * @param array<array-key, string> $allowedMediaTypes
108 |      *
109 |      * @return ?string
110 |      *         If the nested at-rule is supported, it's opening declaration (e.g. "@media (max-width: 768px)") is
111 |      *         returned; otherwise the return value is null.
112 |      */
113 |     private function getFilteredAtIdentifierAndRule(CssAtRuleBlockList $rule, array $allowedMediaTypes): ?string
114 |     {
115 |         $result = null;
116 | 
117 |         if ($rule->atRuleName() === 'media') {
118 |             /** @var string $mediaQueryList */
119 |             $mediaQueryList = $rule->atRuleArgs();
120 |             [$mediaType] = \explode('(', $mediaQueryList, 2);
121 |             if (\trim($mediaType) !== '') {
122 |                 $escapedAllowedMediaTypes = \array_map(
123 |                     static function (string $allowedMediaType): string {
124 |                         return \preg_quote($allowedMediaType, '/');
125 |                     },
126 |                     $allowedMediaTypes
127 |                 );
128 |                 $mediaTypesMatcher = \implode('|', $escapedAllowedMediaTypes);
129 |                 $isAllowed = \preg_match('/^\\s*+(?:only\\s++)?+(?:' . $mediaTypesMatcher . ')/i', $mediaType) > 0;
130 |             } else {
131 |                 $isAllowed = true;
132 |             }
133 | 
134 |             if ($isAllowed) {
135 |                 $result = '@media ' . $mediaQueryList;
136 |             }
137 |         }
138 | 
139 |         return $result;
140 |     }
141 | 
142 |     /**
143 |      * Tests if a CSS rule is an at-rule that should be passed though and copied to a `<style>` element unmodified:
144 |      * - `@charset` rules are discarded - only UTF-8 is supported - `false` is returned;
145 |      * - `@import` rules are passed through only if they satisfy the specification ("user agents must ignore any
146 |      *   '@import' rule that occurs inside a block or after any non-ignored statement other than an '@charset' or an
147 |      *   '@import' rule");
148 |      * - `@media` rules are processed separately to see if their nested rules apply - `false` is returned;
149 |      * - `@font-face` rules are checked for validity - they must contain both a `src` and `font-family` property;
150 |      * - other at-rules are assumed to be valid and treated as a black box - `true` is returned.
151 |      *
152 |      * @param CssRenderable $rule
153 |      *
154 |      * @return bool
155 |      */
156 |     private function isValidAtRuleToRender(CssRenderable $rule): bool
157 |     {
158 |         if ($rule instanceof CssCharset) {
159 |             return false;
160 |         }
161 | 
162 |         if ($rule instanceof CssImport) {
163 |             return $this->isImportRuleAllowed;
164 |         }
165 | 
166 |         $this->isImportRuleAllowed = false;
167 | 
168 |         if (!$rule instanceof CssAtRule) {
169 |             return false;
170 |         }
171 | 
172 |         switch ($rule->atRuleName()) {
173 |             case 'media':
174 |                 $result = false;
175 |                 break;
176 |             case 'font-face':
177 |                 $result = $rule instanceof CssRuleSet
178 |                     && $rule->getRules('font-family') !== []
179 |                     && $rule->getRules('src') !== [];
180 |                 break;
181 |             default:
182 |                 $result = true;
183 |         }
184 | 
185 |         return $result;
186 |     }
187 | }
188 | 


--------------------------------------------------------------------------------
/src/Utilities/CssConcatenator.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Pelago\Emogrifier\Utilities;
  6 | 
  7 | /**
  8 |  * Facilitates building a CSS string by appending rule blocks one at a time, checking whether the media query,
  9 |  * selectors, or declarations block are the same as those from the preceding block and combining blocks in such cases.
 10 |  *
 11 |  * Example:
 12 |  *  $concatenator = new CssConcatenator();
 13 |  *  $concatenator->append(['body'], 'color: blue;');
 14 |  *  $concatenator->append(['body'], 'font-size: 16px;');
 15 |  *  $concatenator->append(['p'], 'margin: 1em 0;');
 16 |  *  $concatenator->append(['ul', 'ol'], 'margin: 1em 0;');
 17 |  *  $concatenator->append(['body'], 'font-size: 14px;', '@media screen and (max-width: 400px)');
 18 |  *  $concatenator->append(['ul', 'ol'], 'margin: 0.75em 0;', '@media screen and (max-width: 400px)');
 19 |  *  $css = $concatenator->getCss();
 20 |  *
 21 |  * `$css` (if unminified) would contain the following CSS:
 22 |  * ` body {
 23 |  * `   color: blue;
 24 |  * `   font-size: 16px;
 25 |  * ` }
 26 |  * ` p, ul, ol {
 27 |  * `   margin: 1em 0;
 28 |  * ` }
 29 |  * ` @media screen and (max-width: 400px) {
 30 |  * `   body {
 31 |  * `     font-size: 14px;
 32 |  * `   }
 33 |  * `   ul, ol {
 34 |  * `     margin: 0.75em 0;
 35 |  * `   }
 36 |  * ` }
 37 |  *
 38 |  * @internal
 39 |  */
 40 | class CssConcatenator
 41 | {
 42 |     /**
 43 |      * Array of media rules in order.  Each element is an object with the following properties:
 44 |      * - string `media` - The media query string, e.g. "@media screen and (max-width:639px)", or an empty string for
 45 |      *   rules not within a media query block;
 46 |      * - object[] `ruleBlocks` - Array of rule blocks in order, where each element is an object with the following
 47 |      *   properties:
 48 |      *   - mixed[] `selectorsAsKeys` - Array whose keys are selectors for the rule block (values are of no
 49 |      *     significance);
 50 |      *   - string `declarationsBlock` - The property declarations, e.g. "margin-top: 0.5em; padding: 0".
 51 |      *
 52 |      * @var array<int, object{
 53 |      *   media: string,
 54 |      *   ruleBlocks: array<int, object{
 55 |      *     selectorsAsKeys: array<string, array-key>,
 56 |      *     declarationsBlock: string
 57 |      *   }>
 58 |      * }>
 59 |      */
 60 |     private $mediaRules = [];
 61 | 
 62 |     /**
 63 |      * Appends a declaration block to the CSS.
 64 |      *
 65 |      * @param array<array-key, string> $selectors
 66 |      *        array of selectors for the rule, e.g. ["ul", "ol", "p:first-child"]
 67 |      * @param string $declarationsBlock
 68 |      *        the property declarations, e.g. "margin-top: 0.5em; padding: 0"
 69 |      * @param string $media
 70 |      *        the media query for the rule, e.g. "@media screen and (max-width:639px)", or an empty string if none
 71 |      */
 72 |     public function append(array $selectors, string $declarationsBlock, string $media = ''): void
 73 |     {
 74 |         $selectorsAsKeys = \array_flip($selectors);
 75 | 
 76 |         $mediaRule = $this->getOrCreateMediaRuleToAppendTo($media);
 77 |         $ruleBlocks = $mediaRule->ruleBlocks;
 78 |         $lastRuleBlock = \end($ruleBlocks);
 79 | 
 80 |         $hasSameDeclarationsAsLastRule = \is_object($lastRuleBlock)
 81 |             && $declarationsBlock === $lastRuleBlock->declarationsBlock;
 82 |         if ($hasSameDeclarationsAsLastRule) {
 83 |             $lastRuleBlock->selectorsAsKeys += $selectorsAsKeys;
 84 |         } else {
 85 |             $lastRuleBlockSelectors = \is_object($lastRuleBlock) ? $lastRuleBlock->selectorsAsKeys : [];
 86 |             $hasSameSelectorsAsLastRule = \is_object($lastRuleBlock)
 87 |                 && self::hasEquivalentSelectors($selectorsAsKeys, $lastRuleBlockSelectors);
 88 |             if ($hasSameSelectorsAsLastRule) {
 89 |                 $lastDeclarationsBlockWithoutSemicolon = \rtrim(\rtrim($lastRuleBlock->declarationsBlock), ';');
 90 |                 $lastRuleBlock->declarationsBlock = $lastDeclarationsBlockWithoutSemicolon . ';' . $declarationsBlock;
 91 |             } else {
 92 |                 $mediaRule->ruleBlocks[] = (object)\compact('selectorsAsKeys', 'declarationsBlock');
 93 |             }
 94 |         }
 95 |     }
 96 | 
 97 |     /**
 98 |      * @return string
 99 |      */
100 |     public function getCss(): string
101 |     {
102 |         return \implode('', \array_map([self::class, 'getMediaRuleCss'], $this->mediaRules));
103 |     }
104 | 
105 |     /**
106 |      * @param string $media The media query for rules to be appended, e.g. "@media screen and (max-width:639px)",
107 |      *        or an empty string if none.
108 |      *
109 |      * @return object{
110 |      *           media: string,
111 |      *           ruleBlocks: array<int, object{
112 |      *             selectorsAsKeys: array<string, array-key>,
113 |      *             declarationsBlock: string
114 |      *           }>
115 |      *         }
116 |      */
117 |     private function getOrCreateMediaRuleToAppendTo(string $media): object
118 |     {
119 |         $lastMediaRule = \end($this->mediaRules);
120 |         if (\is_object($lastMediaRule) && $media === $lastMediaRule->media) {
121 |             return $lastMediaRule;
122 |         }
123 | 
124 |         $newMediaRule = (object)[
125 |             'media' => $media,
126 |             'ruleBlocks' => [],
127 |         ];
128 |         $this->mediaRules[] = $newMediaRule;
129 |         return $newMediaRule;
130 |     }
131 | 
132 |     /**
133 |      * Tests if two sets of selectors are equivalent (i.e. the same selectors, possibly in a different order).
134 |      *
135 |      * @param array<string, array-key> $selectorsAsKeys1
136 |      *        array in which the selectors are the keys, and the values are of no significance
137 |      * @param array<string, array-key> $selectorsAsKeys2 another such array
138 |      *
139 |      * @return bool
140 |      */
141 |     private static function hasEquivalentSelectors(array $selectorsAsKeys1, array $selectorsAsKeys2): bool
142 |     {
143 |         return \count($selectorsAsKeys1) === \count($selectorsAsKeys2)
144 |             && \count($selectorsAsKeys1) === \count($selectorsAsKeys1 + $selectorsAsKeys2);
145 |     }
146 | 
147 |     /**
148 |      * @param object{
149 |      *          media: string,
150 |      *          ruleBlocks: array<int, object{
151 |      *            selectorsAsKeys: array<string, array-key>,
152 |      *            declarationsBlock: string
153 |      *          }>
154 |      *        } $mediaRule
155 |      *
156 |      * @return string CSS for the media rule.
157 |      */
158 |     private static function getMediaRuleCss(object $mediaRule): string
159 |     {
160 |         $ruleBlocks = $mediaRule->ruleBlocks;
161 |         $css = \implode('', \array_map([self::class, 'getRuleBlockCss'], $ruleBlocks));
162 |         $media = $mediaRule->media;
163 |         if ($media !== '') {
164 |             $css = $media . '{' . $css . '}';
165 |         }
166 |         return $css;
167 |     }
168 | 
169 |     /**
170 |      * @param object{selectorsAsKeys: array<string, array-key>, declarationsBlock: string} $ruleBlock
171 |      *
172 |      * @return string CSS for the rule block.
173 |      */
174 |     private static function getRuleBlockCss(object $ruleBlock): string
175 |     {
176 |         $selectorsAsKeys = $ruleBlock->selectorsAsKeys;
177 |         $selectors = \array_keys($selectorsAsKeys);
178 |         $declarationsBlock = $ruleBlock->declarationsBlock;
179 |         return \implode(',', $selectors) . '{' . $declarationsBlock . '}';
180 |     }
181 | }
182 | 


--------------------------------------------------------------------------------
/src/HtmlProcessor/CssToAttributeConverter.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Pelago\Emogrifier\HtmlProcessor;
  6 | 
  7 | /**
  8 |  * This HtmlProcessor can convert style HTML attributes to the corresponding other visual HTML attributes,
  9 |  * e.g. it converts style="width: 100px" to width="100".
 10 |  *
 11 |  * It will only add attributes, but leaves the style attribute untouched.
 12 |  *
 13 |  * To trigger the conversion, call the convertCssToVisualAttributes method.
 14 |  */
 15 | class CssToAttributeConverter extends AbstractHtmlProcessor
 16 | {
 17 |     /**
 18 |      * This multi-level array contains simple mappings of CSS properties to
 19 |      * HTML attributes. If a mapping only applies to certain HTML nodes or
 20 |      * only for certain values, the mapping is an object with a whitelist
 21 |      * of nodes and values.
 22 |      *
 23 |      * @var array<string, array{attribute: string, nodes?: array<int, string>, values?: array<int, string>}>
 24 |      */
 25 |     private $cssToHtmlMap = [
 26 |         'background-color' => [
 27 |             'attribute' => 'bgcolor',
 28 |         ],
 29 |         'text-align' => [
 30 |             'attribute' => 'align',
 31 |             'nodes' => ['p', 'div', 'td', 'th'],
 32 |             'values' => ['left', 'right', 'center', 'justify'],
 33 |         ],
 34 |         'float' => [
 35 |             'attribute' => 'align',
 36 |             'nodes' => ['table', 'img'],
 37 |             'values' => ['left', 'right'],
 38 |         ],
 39 |         'border-spacing' => [
 40 |             'attribute' => 'cellspacing',
 41 |             'nodes' => ['table'],
 42 |         ],
 43 |     ];
 44 | 
 45 |     /**
 46 |      * @var array<string, array<string, string>>
 47 |      */
 48 |     private static $parsedCssCache = [];
 49 | 
 50 |     /**
 51 |      * Maps the CSS from the style nodes to visual HTML attributes.
 52 |      *
 53 |      * @return self fluent interface
 54 |      */
 55 |     public function convertCssToVisualAttributes(): self
 56 |     {
 57 |         /** @var \DOMElement $node */
 58 |         foreach ($this->getAllNodesWithStyleAttribute() as $node) {
 59 |             $inlineStyleDeclarations = $this->parseCssDeclarationsBlock($node->getAttribute('style'));
 60 |             $this->mapCssToHtmlAttributes($inlineStyleDeclarations, $node);
 61 |         }
 62 | 
 63 |         return $this;
 64 |     }
 65 | 
 66 |     /**
 67 |      * Returns a list with all DOM nodes that have a style attribute.
 68 |      *
 69 |      * @return \DOMNodeList
 70 |      */
 71 |     private function getAllNodesWithStyleAttribute(): \DOMNodeList
 72 |     {
 73 |         return $this->getXPath()->query('//*[@style]');
 74 |     }
 75 | 
 76 |     /**
 77 |      * Parses a CSS declaration block into property name/value pairs.
 78 |      *
 79 |      * Example:
 80 |      *
 81 |      * The declaration block
 82 |      *
 83 |      *   "color: #000; font-weight: bold;"
 84 |      *
 85 |      * will be parsed into the following array:
 86 |      *
 87 |      *   "color" => "#000"
 88 |      *   "font-weight" => "bold"
 89 |      *
 90 |      * @param string $cssDeclarationsBlock the CSS declarations block without the curly braces, may be empty
 91 |      *
 92 |      * @return array<string, string>
 93 |      *         the CSS declarations with the property names as array keys and the property values as array values
 94 |      */
 95 |     private function parseCssDeclarationsBlock(string $cssDeclarationsBlock): array
 96 |     {
 97 |         if (isset(self::$parsedCssCache[$cssDeclarationsBlock])) {
 98 |             return self::$parsedCssCache[$cssDeclarationsBlock];
 99 |         }
100 | 
101 |         $properties = [];
102 |         foreach (\preg_split('/;(?!base64|charset)/', $cssDeclarationsBlock) as $declaration) {
103 |             /** @var array<int, string> $matches */
104 |             $matches = [];
105 |             if (!\preg_match('/^([A-Za-z\\-]+)\\s*:\\s*(.+)$/s', \trim($declaration), $matches)) {
106 |                 continue;
107 |             }
108 | 
109 |             $propertyName = \strtolower($matches[1]);
110 |             $propertyValue = $matches[2];
111 |             $properties[$propertyName] = $propertyValue;
112 |         }
113 |         self::$parsedCssCache[$cssDeclarationsBlock] = $properties;
114 | 
115 |         return $properties;
116 |     }
117 | 
118 |     /**
119 |      * Applies $styles to $node.
120 |      *
121 |      * This method maps CSS styles to HTML attributes and adds those to the
122 |      * node.
123 |      *
124 |      * @param array<string, string> $styles the new CSS styles taken from the global styles to be applied to this node
125 |      * @param \DOMElement $node node to apply styles to
126 |      */
127 |     private function mapCssToHtmlAttributes(array $styles, \DOMElement $node): void
128 |     {
129 |         foreach ($styles as $property => $value) {
130 |             // Strip !important indicator
131 |             $value = \trim(\str_replace('!important', '', $value));
132 |             $this->mapCssToHtmlAttribute($property, $value, $node);
133 |         }
134 |     }
135 | 
136 |     /**
137 |      * Tries to apply the CSS style to $node as an attribute.
138 |      *
139 |      * This method maps a CSS rule to HTML attributes and adds those to the node.
140 |      *
141 |      * @param string $property the name of the CSS property to map
142 |      * @param string $value the value of the style rule to map
143 |      * @param \DOMElement $node node to apply styles to
144 |      */
145 |     private function mapCssToHtmlAttribute(string $property, string $value, \DOMElement $node): void
146 |     {
147 |         if (!$this->mapSimpleCssProperty($property, $value, $node)) {
148 |             $this->mapComplexCssProperty($property, $value, $node);
149 |         }
150 |     }
151 | 
152 |     /**
153 |      * Looks up the CSS property in the mapping table and maps it if it matches the conditions.
154 |      *
155 |      * @param string $property the name of the CSS property to map
156 |      * @param string $value the value of the style rule to map
157 |      * @param \DOMElement $node node to apply styles to
158 |      *
159 |      * @return bool true if the property can be mapped using the simple mapping table
160 |      */
161 |     private function mapSimpleCssProperty(string $property, string $value, \DOMElement $node): bool
162 |     {
163 |         if (!isset($this->cssToHtmlMap[$property])) {
164 |             return false;
165 |         }
166 | 
167 |         $mapping = $this->cssToHtmlMap[$property];
168 |         $nodesMatch = !isset($mapping['nodes']) || \in_array($node->nodeName, $mapping['nodes'], true);
169 |         $valuesMatch = !isset($mapping['values']) || \in_array($value, $mapping['values'], true);
170 |         $canBeMapped = $nodesMatch && $valuesMatch;
171 |         if ($canBeMapped) {
172 |             $node->setAttribute($mapping['attribute'], $value);
173 |         }
174 | 
175 |         return $canBeMapped;
176 |     }
177 | 
178 |     /**
179 |      * Maps CSS properties that need special transformation to an HTML attribute.
180 |      *
181 |      * @param string $property the name of the CSS property to map
182 |      * @param string $value the value of the style rule to map
183 |      * @param \DOMElement $node node to apply styles to
184 |      */
185 |     private function mapComplexCssProperty(string $property, string $value, \DOMElement $node): void
186 |     {
187 |         switch ($property) {
188 |             case 'background':
189 |                 $this->mapBackgroundProperty($node, $value);
190 |                 break;
191 |             case 'width':
192 |                 // intentional fall-through
193 |             case 'height':
194 |                 $this->mapWidthOrHeightProperty($node, $value, $property);
195 |                 break;
196 |             case 'margin':
197 |                 $this->mapMarginProperty($node, $value);
198 |                 break;
199 |             case 'border':
200 |                 $this->mapBorderProperty($node, $value);
201 |                 break;
202 |             default:
203 |         }
204 |     }
205 | 
206 |     /**
207 |      * @param \DOMElement $node node to apply styles to
208 |      * @param string $value the value of the style rule to map
209 |      */
210 |     private function mapBackgroundProperty(\DOMElement $node, string $value): void
211 |     {
212 |         // parse out the color, if any
213 |         /** @var array<int, string> $styles */
214 |         $styles = \explode(' ', $value, 2);
215 |         $first = $styles[0];
216 |         if (\is_numeric($first[0]) || \strncmp($first, 'url', 3) === 0) {
217 |             return;
218 |         }
219 | 
220 |         // as this is not a position or image, assume it's a color
221 |         $node->setAttribute('bgcolor', $first);
222 |     }
223 | 
224 |     /**
225 |      * @param \DOMElement $node node to apply styles to
226 |      * @param string $value the value of the style rule to map
227 |      * @param string $property the name of the CSS property to map
228 |      */
229 |     private function mapWidthOrHeightProperty(\DOMElement $node, string $value, string $property): void
230 |     {
231 |         // only parse values in px and %, but not values like "auto"
232 |         if (!\preg_match('/^(\\d+)(\\.(\\d+))?(px|%)$/', $value)) {
233 |             return;
234 |         }
235 | 
236 |         $number = \preg_replace('/[^0-9.%]/', '', $value);
237 |         $node->setAttribute($property, $number);
238 |     }
239 | 
240 |     /**
241 |      * @param \DOMElement $node node to apply styles to
242 |      * @param string $value the value of the style rule to map
243 |      */
244 |     private function mapMarginProperty(\DOMElement $node, string $value): void
245 |     {
246 |         if (!$this->isTableOrImageNode($node)) {
247 |             return;
248 |         }
249 | 
250 |         $margins = $this->parseCssShorthandValue($value);
251 |         if ($margins['left'] === 'auto' && $margins['right'] === 'auto') {
252 |             $node->setAttribute('align', 'center');
253 |         }
254 |     }
255 | 
256 |     /**
257 |      * @param \DOMElement $node node to apply styles to
258 |      * @param string $value the value of the style rule to map
259 |      */
260 |     private function mapBorderProperty(\DOMElement $node, string $value): void
261 |     {
262 |         if (!$this->isTableOrImageNode($node)) {
263 |             return;
264 |         }
265 | 
266 |         if ($value === 'none' || $value === '0') {
267 |             $node->setAttribute('border', '0');
268 |         }
269 |     }
270 | 
271 |     /**
272 |      * @param \DOMElement $node
273 |      *
274 |      * @return bool
275 |      */
276 |     private function isTableOrImageNode(\DOMElement $node): bool
277 |     {
278 |         return $node->nodeName === 'table' || $node->nodeName === 'img';
279 |     }
280 | 
281 |     /**
282 |      * Parses a shorthand CSS value and splits it into individual values.  For example: `padding: 0 auto;` - `0 auto` is
283 |      * split into top: 0, left: auto, bottom: 0, right: auto.
284 |      *
285 |      * @param string $value a CSS property value with 1, 2, 3 or 4 sizes
286 |      *
287 |      * @return array<string, string>
288 |      *         an array of values for top, right, bottom and left (using these as associative array keys)
289 |      */
290 |     private function parseCssShorthandValue(string $value): array
291 |     {
292 |         /** @var array<int, string> $values */
293 |         $values = \preg_split('/\\s+/', $value);
294 | 
295 |         $css = [];
296 |         $css['top'] = $values[0];
297 |         $css['right'] = (\count($values) > 1) ? $values[1] : $css['top'];
298 |         $css['bottom'] = (\count($values) > 2) ? $values[2] : $css['top'];
299 |         $css['left'] = (\count($values) > 3) ? $values[3] : $css['right'];
300 | 
301 |         return $css;
302 |     }
303 | }
304 | 


--------------------------------------------------------------------------------
/src/HtmlProcessor/AbstractHtmlProcessor.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Pelago\Emogrifier\HtmlProcessor;
  6 | 
  7 | /**
  8 |  * Base class for HTML processor that e.g., can remove, add or modify nodes or attributes.
  9 |  *
 10 |  * The "vanilla" subclass is the HtmlNormalizer.
 11 |  *
 12 |  * @psalm-consistent-constructor
 13 |  */
 14 | abstract class AbstractHtmlProcessor
 15 | {
 16 |     /**
 17 |      * @var string
 18 |      */
 19 |     protected const DEFAULT_DOCUMENT_TYPE = '<!DOCTYPE html>';
 20 | 
 21 |     /**
 22 |      * @var string
 23 |      */
 24 |     protected const CONTENT_TYPE_META_TAG = '<meta http-equiv="Content-Type" content="text/html; charset=utf-8">';
 25 | 
 26 |     /**
 27 |      * @var string Regular expression part to match tag names that PHP's DOMDocument implementation is not aware are
 28 |      *      self-closing. These are mostly HTML5 elements, but for completeness <command> (obsolete) and <keygen>
 29 |      *      (deprecated) are also included.
 30 |      *
 31 |      * @see https://bugs.php.net/bug.php?id=73175
 32 |      */
 33 |     protected const PHP_UNRECOGNIZED_VOID_TAGNAME_MATCHER = '(?:command|embed|keygen|source|track|wbr)';
 34 | 
 35 |     /**
 36 |      * Regular expression part to match tag names that may appear before the start of the `<body>` element.  A start tag
 37 |      * for any other element would implicitly start the `<body>` element due to tag omission rules.
 38 |      *
 39 |      * @var string
 40 |      */
 41 |     protected const TAGNAME_ALLOWED_BEFORE_BODY_MATCHER
 42 |         = '(?:html|head|base|command|link|meta|noscript|script|style|template|title)';
 43 | 
 44 |     /**
 45 |      * regular expression pattern to match an HTML comment, including delimiters and modifiers
 46 |      *
 47 |      * @var string
 48 |      */
 49 |     protected const HTML_COMMENT_PATTERN = '/<!--[^-]*+(?:-(?!->)[^-]*+)*+(?:-->|$)/';
 50 | 
 51 |     /**
 52 |      * regular expression pattern to match an HTML `<template>` element, including delimiters and modifiers
 53 |      *
 54 |      * @var string
 55 |      */
 56 |     protected const HTML_TEMPLATE_ELEMENT_PATTERN
 57 |         = '%<template[\\s>][^<]*+(?:<(?!/template>)[^<]*+)*+(?:</template>|$)%i';
 58 | 
 59 |     /**
 60 |      * @var ?\DOMDocument
 61 |      */
 62 |     protected $domDocument = null;
 63 | 
 64 |     /**
 65 |      * @var ?\DOMXPath
 66 |      */
 67 |     private $xPath = null;
 68 | 
 69 |     /**
 70 |      * The constructor.
 71 |      *
 72 |      * Please use `::fromHtml` or `::fromDomDocument` instead.
 73 |      */
 74 |     private function __construct()
 75 |     {
 76 |     }
 77 | 
 78 |     /**
 79 |      * Builds a new instance from the given HTML.
 80 |      *
 81 |      * @param string $unprocessedHtml raw HTML, must be UTF-encoded, must not be empty
 82 |      *
 83 |      * @return static
 84 |      *
 85 |      * @throws \InvalidArgumentException if $unprocessedHtml is anything other than a non-empty string
 86 |      */
 87 |     public static function fromHtml(string $unprocessedHtml): self
 88 |     {
 89 |         if ($unprocessedHtml === '') {
 90 |             throw new \InvalidArgumentException('The provided HTML must not be empty.', 1515763647);
 91 |         }
 92 | 
 93 |         $instance = new static();
 94 |         $instance->setHtml($unprocessedHtml);
 95 | 
 96 |         return $instance;
 97 |     }
 98 | 
 99 |     /**
100 |      * Builds a new instance from the given DOM document.
101 |      *
102 |      * @param \DOMDocument $document a DOM document returned by getDomDocument() of another instance
103 |      *
104 |      * @return static
105 |      */
106 |     public static function fromDomDocument(\DOMDocument $document): self
107 |     {
108 |         $instance = new static();
109 |         $instance->setDomDocument($document);
110 | 
111 |         return $instance;
112 |     }
113 | 
114 |     /**
115 |      * Sets the HTML to process.
116 |      *
117 |      * @param string $html the HTML to process, must be UTF-8-encoded
118 |      */
119 |     private function setHtml(string $html): void
120 |     {
121 |         $this->createUnifiedDomDocument($html);
122 |     }
123 | 
124 |     /**
125 |      * Provides access to the internal DOMDocument representation of the HTML in its current state.
126 |      *
127 |      * @return \DOMDocument
128 |      *
129 |      * @throws \UnexpectedValueException
130 |      */
131 |     public function getDomDocument(): \DOMDocument
132 |     {
133 |         if (!$this->domDocument instanceof \DOMDocument) {
134 |             $message = self::class . '::setDomDocument() has not yet been called on ' . static::class;
135 |             throw new \UnexpectedValueException($message, 1570472239);
136 |         }
137 | 
138 |         return $this->domDocument;
139 |     }
140 | 
141 |     /**
142 |      * @param \DOMDocument $domDocument
143 |      */
144 |     private function setDomDocument(\DOMDocument $domDocument): void
145 |     {
146 |         $this->domDocument = $domDocument;
147 |         $this->xPath = new \DOMXPath($this->domDocument);
148 |     }
149 | 
150 |     /**
151 |      * @return \DOMXPath
152 |      *
153 |      * @throws \UnexpectedValueException
154 |      */
155 |     protected function getXPath(): \DOMXPath
156 |     {
157 |         if (!$this->xPath instanceof \DOMXPath) {
158 |             $message = self::class . '::setDomDocument() has not yet been called on ' . static::class;
159 |             throw new \UnexpectedValueException($message, 1617819086);
160 |         }
161 | 
162 |         return $this->xPath;
163 |     }
164 | 
165 |     /**
166 |      * Renders the normalized and processed HTML.
167 |      *
168 |      * @return string
169 |      */
170 |     public function render(): string
171 |     {
172 |         $htmlWithPossibleErroneousClosingTags = $this->getDomDocument()->saveHTML();
173 | 
174 |         return $this->removeSelfClosingTagsClosingTags($htmlWithPossibleErroneousClosingTags);
175 |     }
176 | 
177 |     /**
178 |      * Renders the content of the BODY element of the normalized and processed HTML.
179 |      *
180 |      * @return string
181 |      */
182 |     public function renderBodyContent(): string
183 |     {
184 |         $htmlWithPossibleErroneousClosingTags = $this->getDomDocument()->saveHTML($this->getBodyElement());
185 |         $bodyNodeHtml = $this->removeSelfClosingTagsClosingTags($htmlWithPossibleErroneousClosingTags);
186 | 
187 |         return \preg_replace('%</?+body(?:\\s[^>]*+)?+>%', '', $bodyNodeHtml);
188 |     }
189 | 
190 |     /**
191 |      * Eliminates any invalid closing tags for void elements from the given HTML.
192 |      *
193 |      * @param string $html
194 |      *
195 |      * @return string
196 |      */
197 |     private function removeSelfClosingTagsClosingTags(string $html): string
198 |     {
199 |         return \preg_replace('%</' . self::PHP_UNRECOGNIZED_VOID_TAGNAME_MATCHER . '>%', '', $html);
200 |     }
201 | 
202 |     /**
203 |      * Returns the BODY element.
204 |      *
205 |      * This method assumes that there always is a BODY element.
206 |      *
207 |      * @return \DOMElement
208 |      *
209 |      * @throws \RuntimeException
210 |      */
211 |     private function getBodyElement(): \DOMElement
212 |     {
213 |         $node = $this->getDomDocument()->getElementsByTagName('body')->item(0);
214 |         if (!$node instanceof \DOMElement) {
215 |             throw new \RuntimeException('There is no body element.', 1617922607);
216 |         }
217 | 
218 |         return $node;
219 |     }
220 | 
221 |     /**
222 |      * Creates a DOM document from the given HTML and stores it in $this->domDocument.
223 |      *
224 |      * The DOM document will always have a BODY element and a document type.
225 |      *
226 |      * @param string $html
227 |      */
228 |     private function createUnifiedDomDocument(string $html): void
229 |     {
230 |         $this->createRawDomDocument($html);
231 |         $this->ensureExistenceOfBodyElement();
232 |     }
233 | 
234 |     /**
235 |      * Creates a DOMDocument instance from the given HTML and stores it in $this->domDocument.
236 |      *
237 |      * @param string $html
238 |      */
239 |     private function createRawDomDocument(string $html): void
240 |     {
241 |         $domDocument = new \DOMDocument();
242 |         $domDocument->strictErrorChecking = false;
243 |         $domDocument->formatOutput = true;
244 |         $libXmlState = \libxml_use_internal_errors(true);
245 |         $domDocument->loadHTML($this->prepareHtmlForDomConversion($html));
246 |         \libxml_clear_errors();
247 |         \libxml_use_internal_errors($libXmlState);
248 | 
249 |         $this->setDomDocument($domDocument);
250 |     }
251 | 
252 |     /**
253 |      * Returns the HTML with added document type, Content-Type meta tag, and self-closing slashes, if needed,
254 |      * ensuring that the HTML will be good for creating a DOM document from it.
255 |      *
256 |      * @param string $html
257 |      *
258 |      * @return string the unified HTML
259 |      */
260 |     private function prepareHtmlForDomConversion(string $html): string
261 |     {
262 |         $htmlWithSelfClosingSlashes = $this->ensurePhpUnrecognizedSelfClosingTagsAreXml($html);
263 |         $htmlWithDocumentType = $this->ensureDocumentType($htmlWithSelfClosingSlashes);
264 | 
265 |         return $this->addContentTypeMetaTag($htmlWithDocumentType);
266 |     }
267 | 
268 |     /**
269 |      * Makes sure that the passed HTML has a document type, with lowercase "html".
270 |      *
271 |      * @param string $html
272 |      *
273 |      * @return string HTML with document type
274 |      */
275 |     private function ensureDocumentType(string $html): string
276 |     {
277 |         $hasDocumentType = \stripos($html, '<!DOCTYPE') !== false;
278 |         if ($hasDocumentType) {
279 |             return $this->normalizeDocumentType($html);
280 |         }
281 | 
282 |         return self::DEFAULT_DOCUMENT_TYPE . $html;
283 |     }
284 | 
285 |     /**
286 |      * Makes sure the document type in the passed HTML has lowercase "html".
287 |      *
288 |      * @param string $html
289 |      *
290 |      * @return string HTML with normalized document type
291 |      */
292 |     private function normalizeDocumentType(string $html): string
293 |     {
294 |         // Limit to replacing the first occurrence: as an optimization; and in case an example exists as unescaped text.
295 |         return \preg_replace(
296 |             '/<!DOCTYPE\\s++html(?=[\\s>])/i',
297 |             '<!DOCTYPE html',
298 |             $html,
299 |             1
300 |         );
301 |     }
302 | 
303 |     /**
304 |      * Adds a Content-Type meta tag for the charset.
305 |      *
306 |      * This method also ensures that there is a HEAD element.
307 |      *
308 |      * @param string $html
309 |      *
310 |      * @return string the HTML with the meta tag added
311 |      */
312 |     private function addContentTypeMetaTag(string $html): string
313 |     {
314 |         if ($this->hasContentTypeMetaTagInHead($html)) {
315 |             return $html;
316 |         }
317 | 
318 |         // We are trying to insert the meta tag to the right spot in the DOM.
319 |         // If we just prepended it to the HTML, we would lose attributes set to the HTML tag.
320 |         $hasHeadTag = \preg_match('/<head[\\s>]/i', $html);
321 |         $hasHtmlTag = \stripos($html, '<html') !== false;
322 | 
323 |         if ($hasHeadTag) {
324 |             $reworkedHtml = \preg_replace(
325 |                 '/<head(?=[\\s>])([^>]*+)>/i',
326 |                 '<head$1>' . self::CONTENT_TYPE_META_TAG,
327 |                 $html
328 |             );
329 |         } elseif ($hasHtmlTag) {
330 |             $reworkedHtml = \preg_replace(
331 |                 '/<html(.*?)>/is',
332 |                 '<html$1><head>' . self::CONTENT_TYPE_META_TAG . '</head>',
333 |                 $html
334 |             );
335 |         } else {
336 |             $reworkedHtml = self::CONTENT_TYPE_META_TAG . $html;
337 |         }
338 | 
339 |         return $reworkedHtml;
340 |     }
341 | 
342 |     /**
343 |      * Tests whether the given HTML has a valid `Content-Type` metadata element within the `<head>` element.  Due to tag
344 |      * omission rules, HTML parsers are expected to end the `<head>` element and start the `<body>` element upon
345 |      * encountering a start tag for any element which is permitted only within the `<body>`.
346 |      *
347 |      * @param string $html
348 |      *
349 |      * @return bool
350 |      */
351 |     private function hasContentTypeMetaTagInHead(string $html): bool
352 |     {
353 |         \preg_match('%^.*?(?=<meta(?=\\s)[^>]*\\shttp-equiv=(["\']?+)Content-Type\\g{-1}[\\s/>])%is', $html, $matches);
354 |         if (isset($matches[0])) {
355 |             $htmlBefore = $matches[0];
356 |             try {
357 |                 $hasContentTypeMetaTagInHead = !$this->hasEndOfHeadElement($htmlBefore);
358 |             } catch (\RuntimeException $exception) {
359 |                 // If something unexpected occurs, assume the `Content-Type` that was found is valid.
360 |                 \trigger_error($exception->getMessage());
361 |                 $hasContentTypeMetaTagInHead = true;
362 |             }
363 |         } else {
364 |             $hasContentTypeMetaTagInHead = false;
365 |         }
366 | 
367 |         return $hasContentTypeMetaTagInHead;
368 |     }
369 | 
370 |     /**
371 |      * Tests whether the `<head>` element ends within the given HTML.  Due to tag omission rules, HTML parsers are
372 |      * expected to end the `<head>` element and start the `<body>` element upon encountering a start tag for any element
373 |      * which is permitted only within the `<body>`.
374 |      *
375 |      * @param string $html
376 |      *
377 |      * @return bool
378 |      *
379 |      * @throws \RuntimeException
380 |      */
381 |     private function hasEndOfHeadElement(string $html): bool
382 |     {
383 |         $headEndTagMatchCount
384 |             = \preg_match('%<(?!' . self::TAGNAME_ALLOWED_BEFORE_BODY_MATCHER . '[\\s/>])\\w|</head>%i', $html);
385 |         if (\is_int($headEndTagMatchCount) && $headEndTagMatchCount > 0) {
386 |             // An exception to the implicit end of the `<head>` is any content within a `<template>` element, as well in
387 |             // comments.  As an optimization, this is only checked for if a potential `<head>` end tag is found.
388 |             $htmlWithoutCommentsOrTemplates = $this->removeHtmlTemplateElements($this->removeHtmlComments($html));
389 |             $hasEndOfHeadElement = $htmlWithoutCommentsOrTemplates === $html
390 |                 || $this->hasEndOfHeadElement($htmlWithoutCommentsOrTemplates);
391 |         } else {
392 |             $hasEndOfHeadElement = false;
393 |         }
394 | 
395 |         return $hasEndOfHeadElement;
396 |     }
397 | 
398 |     /**
399 |      * Removes comments from the given HTML, including any which are unterminated, for which the remainder of the string
400 |      * is removed.
401 |      *
402 |      * @param string $html
403 |      *
404 |      * @return string
405 |      *
406 |      * @throws \RuntimeException
407 |      */
408 |     private function removeHtmlComments(string $html): string
409 |     {
410 |         $result = \preg_replace(self::HTML_COMMENT_PATTERN, '', $html);
411 |         if (!\is_string($result)) {
412 |             throw new \RuntimeException('Internal PCRE error', 1616521475);
413 |         }
414 | 
415 |         return $result;
416 |     }
417 | 
418 |     /**
419 |      * Removes `<template>` elements from the given HTML, including any without an end tag, for which the remainder of
420 |      * the string is removed.
421 |      *
422 |      * @param string $html
423 |      *
424 |      * @return string
425 |      *
426 |      * @throws \RuntimeException
427 |      */
428 |     private function removeHtmlTemplateElements(string $html): string
429 |     {
430 |         $result = \preg_replace(self::HTML_TEMPLATE_ELEMENT_PATTERN, '', $html);
431 |         if (!\is_string($result)) {
432 |             throw new \RuntimeException('Internal PCRE error', 1616519652);
433 |         }
434 | 
435 |         return $result;
436 |     }
437 | 
438 |     /**
439 |      * Makes sure that any self-closing tags not recognized as such by PHP's DOMDocument implementation have a
440 |      * self-closing slash.
441 |      *
442 |      * @param string $html
443 |      *
444 |      * @return string HTML with problematic tags converted.
445 |      */
446 |     private function ensurePhpUnrecognizedSelfClosingTagsAreXml(string $html): string
447 |     {
448 |         return \preg_replace(
449 |             '%<' . self::PHP_UNRECOGNIZED_VOID_TAGNAME_MATCHER . '\\b[^>]*+(?<!/)(?=>)%',
450 |             '$0/',
451 |             $html
452 |         );
453 |     }
454 | 
455 |     /**
456 |      * Checks that $this->domDocument has a BODY element and adds it if it is missing.
457 |      *
458 |      * @throws \UnexpectedValueException
459 |      */
460 |     private function ensureExistenceOfBodyElement(): void
461 |     {
462 |         if ($this->getDomDocument()->getElementsByTagName('body')->item(0) instanceof \DOMElement) {
463 |             return;
464 |         }
465 | 
466 |         $htmlElement = $this->getDomDocument()->getElementsByTagName('html')->item(0);
467 |         if (!$htmlElement instanceof \DOMElement) {
468 |             throw new \UnexpectedValueException('There is no HTML element although there should be one.', 1569930853);
469 |         }
470 |         $htmlElement->appendChild($this->getDomDocument()->createElement('body'));
471 |     }
472 | }
473 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
  1 | # Emogrifier Change Log
  2 | 
  3 | All notable changes to this project will be documented in this file.
  4 | This project adheres to [Semantic Versioning](https://semver.org/).
  5 | 
  6 | ## x.y.z
  7 | 
  8 | ### Added
  9 | - Allow installation together with Symfony 6 (#1065)
 10 | - Support more file types in the `.editorconfig` (#1035)
 11 | - Set `align` attribute of `<th>` elements with `CssToAttributeConverter` (#1008)
 12 | 
 13 | ### Changed
 14 | - Use `sabberworm/php-css-parser` to parse the CSS (#1015)
 15 | - Also check the unit test code with Psalm (#1003)
 16 | 
 17 | ### Deprecated
 18 | - Support for PHP 7.2 will be removed in Emogrifier 7.0.
 19 | 
 20 | ### Removed
 21 | - Remove a redundant CSS data cache (#1018)
 22 | - Drop support for Symfony 5.1 (#972)
 23 | - Drop support for PHP 7.1 (#967)
 24 | 
 25 | ### Fixed
 26 | - Allow `@import` after ignored invalid `@charset` (@1081)
 27 | - Allow line feeds within `<html>` tag (#987)
 28 | 
 29 | ## 5.0.1
 30 | 
 31 | ### Changed
 32 | - Switch the default branch from `master` to `main` (#951)
 33 | 
 34 | ### Fixed
 35 | - Ignore `http-equiv` `Content-Type` in `<body>` (#961)
 36 | - Allow "Content-Type" in content (#959)
 37 | 
 38 | ## 5.0.0
 39 | 
 40 | ### Added
 41 | - Add an `.editorconfig` file (#940)
 42 | - Support PHP 8.0 (#926)
 43 | - Run the CI build once a week (#933)
 44 | - Move more development tools to PHIVE (#894, #907)
 45 | 
 46 | ### Changed
 47 | - Automatically add a backslash for global functions (#909)
 48 | - Update the development tools (#898, #895)
 49 | - Upgrade to PHPUnit 7.5 (#888)
 50 | - Enforce constant visibility (#892)
 51 | - Rename the PHPCS configuration file (#891, #896)
 52 | - Make use of PHP 7.1 language features (#883)
 53 | 
 54 | ### Deprecated
 55 | - Support for PHP 7.1 will be removed in Emogrifier 6.0.
 56 | 
 57 | ### Removed
 58 | - Drop support for Symfony 4.3 and 5.0 (#936)
 59 | - Stop checking `tests/` with Psalm (#885)
 60 | - Drop support for PHP 7.0 (#880)
 61 | 
 62 | ### Fixed
 63 | - Fix a nonsensical code example in the README (#920, #935)
 64 | - Remove `!important` from `style` attributes also when uppercase, mixed case or
 65 |   having whitespace after `!` (#911)
 66 | - Copy rules using `:...of-type` without a type to the `<style>` element (#904)
 67 | - Support combinator followed by dynamic pseudo-class in minified CSS (#903)
 68 | - Preserve all uninlinable (or otherwise unprocessed) at-rules (#899)
 69 | - Allow Windows CLI to run development tools installed through PHIVE (#900)
 70 | - Switch to a maintained package for parallel PHP linting (#884)
 71 | - Add `.0` version suffixes to PHP version requirements (#881)
 72 | 
 73 | ## 4.0.0
 74 | 
 75 | ### Added
 76 | - Extract and inject `@font-face` rules into head (#870)
 77 | - Test tag omission in conformant supplied HTML (#868)
 78 | - Check for missing return type hint annotations in the code sniffs (#860)
 79 | - Support `:only-of-type` (with a type) (#849, #856)
 80 | - Configuration setting methods now all return `$this` to allow chaining (#824, #854)
 81 | - Disable php-cs-fixer Yoda conditions (#791, #794)
 82 | - Check the code with psalm (#537, #779)
 83 | - Composer script to run tests with `--stop-on-failure` (#782)
 84 | - Test universal selector with combinators (#776)
 85 | 
 86 | ### Changed
 87 | - Normalize DOCTYPE declaration according to polyglot markup recommendation (#866)
 88 | - Upgrade to V2 of the PHP setup GitHub action (#861)
 89 | - Move the development tools to PHIVE (#850, #851)
 90 | - Switch the parallel linting to a maintained fork (#842)
 91 | - Move continuous integration from Travis CI to GitHub actions (#832, #834, #838, #839, #840, #841, #843, #846, #849)
 92 | - Clean up the folder structure and autoloading configuration (#529, #785)
 93 | - Use `self` as the return type for `fromHtml` (#784)
 94 | - Make use of PHP 7.0 language features (#777)
 95 | 
 96 | ### Deprecated
 97 | - Support for PHP 7.0 will be removed in Emogrifier 5.0.
 98 | 
 99 | ### Removed
100 | - Drop support for Symfony versions that have reached their end of life (#847)
101 | - Drop the `Emogrifier` class (#774)
102 | - Drop support for PHP 5.6 (#773)
103 | 
104 | ### Fixed
105 | - Allow `:last-of-type` etc. without type, without causing exception (#875)
106 | - Make sure to use the Composer-installed development tools (#862, #865)
107 | - Add missing `<head>` element when there's a `<header>` element (#844, #853)
108 | - Fix mapping width/height when decimal is used (#845)
109 | - Actually use the specified PHP version on GitHub actions (#836)
110 | - Support `ci:php:lint` on Windows (#740, #780)
111 | 
112 | ## 3.1.0
113 | 
114 | ### Added
115 | - Add support for PHP 7.4 (#821, #829)
116 | 
117 | ### Changed
118 | - Upgrade to Symfony 5.0 (#820)
119 | 
120 | ## 3.0.0
121 | 
122 | ### Added
123 | - Test and document excluding entire subtree with `addExcludedSelector()` (#347, #768)
124 | - Test that rules with `:optional` or `:required` are copied to the `<style>`
125 |   element (#748, #765)
126 | - Test that rules with `:only-of-type` are copied to the `<style>` element (#748, #760)
127 | - Support `:last-of-type` (#748, #758)
128 | - Support `:first-of-type` (#748, #757)
129 | - Support `:empty` (#748, #756)
130 | - Test that rules with `:any-link` are copied to the `<style>` element (#748, #755)
131 | - Support and test `:only-child` (#747, #754)
132 | - Support and test `:nth-last-of-type` (#747, #751)
133 | - Support and test `:nth-last-child` (#747, #750)
134 | - Support and test general sibling combinator (#723, #745)
135 | - Test universal selector with combinators (#723, #743)
136 | - Preserve `display: none` elements with `-emogrifier-keep` class (#252, #737)
137 | - Preserve valid `@import` rules (#338, #334, #732, #735)
138 | - Add `HtmlPruner::removeRedundantClassesAfterCssInlined` (#380, #724)
139 | - Check on Travis that PHP-CS-Fixer will not change anything (#727)
140 | - Support `:not(…)` as an entire selector (#469, #725)
141 | - Add `HtmlPruner::removeRedundantClasses` (#380, #708)
142 | - Support multiple attributes selectors (#385, #721)
143 | - Support `> :first-child` and `> :last-child` in selectors (#384, #720)
144 | - Add an `ArrayIntersector` class (#708, #710)
145 | - Add `CssInliner::getMatchingUninlinableSelectors` (#380, #707)
146 | - Add tests for `:nth-child` and `:nth-of-type` (#71, #698)
147 | 
148 | ### Changed
149 | - Relax the dependency on `symfony/css-selector` (#762)
150 | - Rename `HtmlPruner::removeInvisibleNodes` to
151 |   `HtmlPruner::removeElementsWithDisplayNone` (#717, #718)
152 | - Mark the utility classes as internal (#715)
153 | - Move utility classes to the `Pelago\Emogrifier\Utilities` namespace (#712)
154 | - Make the `$css` parameter of the `inlineCss` method optional (#700)
155 | - Update the development dependencies (#691)
156 | 
157 | ### Deprecated
158 | - Support for PHP 5.6 will be removed in Emogrifier 4.0.
159 | - Deprecate the `Emogrifier` class (#701)
160 | 
161 | ### Removed
162 | - Drop `enableCssToHtmlMapping` and `disableInvisibleNodeRemoval` (#692)
163 | - Drop support for PHP 5.5 (#690)
164 | 
165 | ### Fixed
166 | - Fix PhpStorm code inspection warnings (#729, #770)
167 | - Uppercase type combined with class or ID in selector (#590, #769)
168 | - Dynamic pseudo-class combined with static one (rules copied to `<style>`
169 |   element, #746)
170 | - Descendant attribute selectors (such as `html input[disabled]`) (#375, #709)
171 | - Attribute selectors with hyphen in attribute name (#284, #540, #704)
172 | - Attribute selectors with space, hyphen, colon, semicolon or (most) other
173 |   non-alphanumeric characters in attribute value (#284, #333, #550, #540, #704)
174 | - Don’t create empty `style` attributes for unparsable declarations (#259, #702)
175 | - Allow `:not(:behavioural-pseudo-class)` in selectors (#697, #703)
176 | 
177 | ## 2.2.0
178 | 
179 | ### Added
180 | - Add a `HtmlPruner` class (#679)
181 | - Add `AbstractHtmlProcessor::fromDomDocument` (#676)
182 | - Add `AbstractHtmlProcessor::fromHtml` (#675)
183 | 
184 | ### Changed
185 | - Make the closures static (#674)
186 | - Keep `<wbr>` elements by default with `CssInliner` (#665)
187 | - Make the `CssInliner` inherit `AbstractHtmlProcessor` (#660)
188 | - Separate `CssInliner::inlineCss` and the rendering (#654)
189 | 
190 | ### Removed
191 | - Drop the removal of unprocessable tags from `CssInliner` (#685)
192 | - Drop the removal of invisible nodes from `CssInliner` (#684)
193 | 
194 | ### Fixed
195 | - Remove opening `<body>` tag from `body` content when element has attribute(s) (#677, #683)
196 | - Keep development files out of the Composer packages (#678)
197 | - Call all static methods statically in `CssConcatenator` (#670)
198 | - Support all HTML5 self-closing tags, including `<embed>`, `<source>`,
199 |   `<track>` and `<wbr>` (#653)
200 | - Remove all "unprocessable" (e.g. `<wbr>`) tags (#650)
201 | - Correct translated xpath of `:nth-child` selector (#648)
202 | 
203 | ## 2.1.1
204 | 
205 | ### Changed
206 | - Add a test that a missing document type gets added (#641)
207 | 
208 | ### Fixed
209 | - Keep the `style` element the `head` (#642)
210 | 
211 | ## 2.1.0
212 | 
213 | ### Added
214 | - PHP 7.3 support (#638)
215 |   - Allow PHP 7.3 in `composer.json`
216 |   - Test in Travis for PHP 7.3
217 | - Add a `renderBodyContent()` method (#633)
218 | - Add a `getDomDocument()` method (#630)
219 | - Add a Composer script for PHP CS Fixer (#607)
220 | - Copy matching rules with dynamic pseudo-classes or pseudo-elements in
221 |   selectors to the style element (#280, #562, #567)
222 | - Add a CssToAttributeConverter (#546)
223 | - Expose the DOMDocument in AbstractHtmlProcessor (#520)
224 | - Add an HtmlNormalizer class (#513, #516)
225 | - Add a CssInliner class (#514, #522)
226 | - Composer scripts for the various CI build steps
227 | - Validate the composer.json on Travis (#476)
228 | 
229 | ### Changed
230 | - Mark the work-in-progress classes as `@internal` (#640)
231 | - Remove the unprocessable tags from the DOM, not from the raw HTML (#627)
232 | - Reject empty HTML in `setHtml()` (#622)
233 | - Stop passing the DOM document around (#618)
234 | - Improve performance by using explicit namespaces for PHP functions (#573, #576)
235 | - Add type hint checking to the code sniffs (#566)
236 | - Check the code with PHPMD (#561)
237 | - Add the cyclomatic complexity to the checked code sniffs (#558)
238 | - Use the Symfony CSS selector component (#540)
239 | 
240 | ### Deprecated
241 | - Support for PHP 5.5 will be removed in Emogrifier 3.0.
242 | - Support for PHP 5.6 will be removed in Emogrifier 4.0.
243 | - The removal of invisible nodes will be removed in Emogrifier 3.0. (#473)
244 | - Converting CSS styles to (non-CSS) HTML attributes will be removed
245 |   in Emogrifier 3.0. Please use the new CssToAttributeConverter instead. (#474)
246 | - Emogrifier 3.x.y will be the last release that supports usage without
247 |   Composer (i.e., you can still require the class file).
248 |   Starting with version 4.0, Emogrifier will only work with Composer.
249 | - The Emogrifier class will be superseded by CssInliner class in
250 |   Emogrifier 3.0. For this, the Emogrifier class will be deprecated for
251 |   version 3.0 and removed for version 4.0.
252 | 
253 | ### Removed
254 | - Drop the `@version` PHPDoc annotations (#637)
255 | - Drop the destructors (#619)
256 | 
257 | ### Fixed
258 | - Add required XML PHP extension to `composer.json` (#614)
259 | - Add required DOM PHP extension to `composer.json` (#595)
260 | - Escape hyphens in regular expressions (#588)
261 | - Fix Travis for PHP 5.x (#589)
262 | - Allow CSS between empty `@media` rule and another `@media` rule (#534)
263 | - Allow additional whitespace in media-query-list of disallowed `@media` rules (#532)
264 | - Allow multiple minified `@import` rules in the CSS without error (note:
265 |   `@import`s are currently ignored, #527)
266 | - Style property ordering when multiple mixed individual and shorthand
267 |   properties apply (#511, #508)
268 | - Calculation of selector precedence for selectors involving pseudo-classes
269 |   and/or attributes (#502)
270 | - Allow `@charset` in the CSS without error (note: its value is currently
271 |   ignored, #507)
272 | - Allow attribute selectors in descendants (#506, #381, #443)
273 | - Allow adjacent sibling CSS selector combinator in minified CSS (#505)
274 | - Allow CSS property values containing newlines (#504)
275 | 
276 | ## 2.0.0
277 | 
278 | ### Added
279 | - Support for CSS :not() selector (#431)
280 | - Automatically remove !important annotations from final inline style declarations (#420)
281 | - Automatically move `<style>` block from `<head>` to `<body>` (#396)
282 | - PHP 7.2 support (#398)
283 |   - Allow PHP 7.2 in `composer.json`, cleaner PHP version constraint
284 |   - Test in Travis for PHP 7.2
285 | - Debug mode. Throw debug exceptions only if debug is active. (#392)
286 | 
287 | ### Changed
288 | - Test with latest and oldest dependencies on Travis (#463)
289 | - Always enable the debug mode in the tests (#448)
290 | - Optimize the string operations (#430)
291 | 
292 | ### Deprecated
293 | - Support for PHP 5.5 will be removed in Emogrifier 3.0.
294 | - Support for PHP 5.6 will be removed in Emogrifier 4.0.
295 | 
296 | ### Removed
297 | - Drop support for PHP 5.4 (#422)
298 | - Drop support for HHVM (#386)
299 | 
300 | ### Fixed
301 | - Handle invalid/unrecognized selectors in media query blocks (#442)
302 | - Throw (the correct) exception for invalid excluded selectors (#437)
303 | - emogrifyBody must not encode umlaut entities (#414)
304 | - Fix mapped HTML attribute values (#405)
305 | - Make sure the HTML always has a BODY element (#410)
306 | - Make inline style priority higher than css block priority (#404)
307 | - Fix media regex parsing (#402)
308 | - Silence purposefully ignored PHP Warnings (#400)
309 | 
310 | ## 1.2.0 (2017-03-02)
311 | 
312 | ### Added
313 | - Handling invalid xPath expression warnings (#361)
314 | 
315 | ### Deprecated
316 | - Support for PHP 5.5 will be removed in Emogrifier 3.0.
317 | - Support for PHP 5.4 will be removed in Emogrifier 2.0.
318 | 
319 | ### Fixed
320 | - Allow colon (`:`) and semi-colon (`;`) when using the `*=` selector (#371)
321 | - Ignore "auto" width and height (#365)
322 | 
323 | ## 1.1.0 (2016-09-18)
324 | 
325 | ### Added
326 | - Add support for PHP 7.1 (#342)
327 | - Support the attr|=value selector (#337)
328 | - Support the attr*=value selector (#330)
329 | - Support the attr$=value selector (#329)
330 | - Support the attr^=value selector (#324)
331 | - Support the attr~=value selector (#323)
332 | - Add CSS to HTML attribute mapper (#288)
333 | 
334 | ### Changed
335 | - Remove composer dependency from PHP mbstring extension (Actual code dependency were removed a lot of time ago) (#295)
336 | 
337 | ### Deprecated
338 | - Support for PHP 5.5 will be removed in Emogrifier 3.0.
339 | - Support for PHP 5.4 will be removed in Emogrifier 2.0.
340 | 
341 | ### Fixed
342 | - Method emogrifyBodyContent() doesn't keeps utf8 umlauts (#349)
343 | - Ignore value with words more than one in the attribute selector (#327)
344 | - Ignore spaces around the > in the direct child selector (#322)
345 | - Ignore empty media queries (#307) (#237)
346 | - Ignore pseudo-class when combined with pseudo-element (#308)
347 | - First-child and last-child selectors are broken (#293)
348 | - Second !important rule needs to overwrite the first one (#292)
349 | 
350 | ## 1.0.0 (2015-10-15)
351 | 
352 | ### Added
353 | - Add branch alias (#231)
354 | - Remove media queries which do not impact the document (#217)
355 | - Allow elements to be excluded from emogrification (#215)
356 | - Handle !important (#214)
357 | - emogrifyBodyContent() method (#206)
358 | - Cache combinedStyles (#211)
359 | - Allow user to define media types to keep (#200)
360 | - Ignore invalid CSS selectors (#194)
361 | - isRemoveDisplayNoneEnabled option (#162)
362 | - Allow disabling of "inline style" and "style block" parsing (#156)
363 | - Preserve @media if necessary (#62)
364 | - Add extraction of style blocks within the HTML
365 | - Add several new pseudo-selectors (first-child, last-child, nth-child,
366 |   and nth-of-type)
367 | 
368 | ### Changed
369 | - Make HTML5 the default document type (#245)
370 | - Make copyCssWithMediaToStyleNode private (#218)
371 | - Stop encoding umlauts and dollar signs (#170)
372 | - Convert the classes to namespaces (#41)
373 | 
374 | ### Deprecated
375 | - Support for PHP 5.4 will be removed in Emogrifier 2.0.
376 | 
377 | ### Removed
378 | - Drop support for PHP 5.3 (#114)
379 | - Support for character sets other than UTF-8 was removed.
380 | 
381 | ### Fixed
382 | - Fix failing tests on Windows due to line endings (#263)
383 | - Parsing CSS declaration blocks (#261)
384 | - Fix first-child and last-child selectors (#257)
385 | - Fix parsing of CSS for data URIs (#243)
386 | - Fix multi-line media queries (#241)
387 | - Keep CSS media queries even if followed by CSS comments (#201)
388 | - Fix CSS selectors with exact attribute only (#197)
389 | - Properly handle UTF-8 characters and entities (#189)
390 | - Add mbstring extension to composer.json (#93)
391 | - Prevent incorrectly capitalized CSS selectors from being stripped (#85)
392 | - Fix CSS selectors with exact attribute only (#197)
393 | - Wrong selector extraction from minified CSS (#69)
394 | - Restore libxml error handler state after clearing (#65)
395 | - Ignore all warnings produced by DOMDocument::loadHTML() (#63)
396 | - Style tags in HTML cause an Xpath invalid query error (#60)
397 | - Fix PHP warnings with PHP 5.5 (#26)
398 | - Make removal of invisible nodes operate in a case-insensitive manner
399 | - Fix a bug that was overwriting existing inline styles from the original HTML
400 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Emogrifier
  2 | 
  3 | [![Build Status](https://github.com/MyIntervals/emogrifier/workflows/CI/badge.svg?branch=main)](https://github.com/MyIntervals/emogrifier/actions/)
  4 | [![Latest Stable Version](https://poser.pugx.org/pelago/emogrifier/v/stable.svg)](https://packagist.org/packages/pelago/emogrifier)
  5 | [![Total Downloads](https://poser.pugx.org/pelago/emogrifier/downloads.svg)](https://packagist.org/packages/pelago/emogrifier)
  6 | [![Latest Unstable Version](https://poser.pugx.org/pelago/emogrifier/v/unstable.svg)](https://packagist.org/packages/pelago/emogrifier)
  7 | [![License](https://poser.pugx.org/pelago/emogrifier/license.svg)](https://packagist.org/packages/pelago/emogrifier)
  8 | 
  9 | _n. e•mog•ri•fi•er [\ē-'mä-grƏ-,fī-Ər\] - a utility for changing completely the
 10 | nature or appearance of HTML email, esp. in a particularly fantastic or bizarre
 11 | manner_
 12 | 
 13 | Emogrifier converts CSS styles into inline style attributes in your HTML code.
 14 | This ensures proper display on email and mobile device readers that lack
 15 | stylesheet support.
 16 | 
 17 | This utility was developed as part of [Intervals](http://www.myintervals.com/)
 18 | to deal with the problems posed by certain email clients (namely Outlook 2007
 19 | and GoogleMail) when it comes to the way they handle styling contained in HTML
 20 | emails. As many web developers and designers already know, certain email
 21 | clients are notorious for their lack of CSS support. While attempts are being
 22 | made to develop common [email standards](http://www.email-standards.org/),
 23 | implementation is still a ways off.
 24 | 
 25 | The primary problem with uncooperative email clients is that most tend to only
 26 | regard inline CSS, discarding all `<style>` elements and links to stylesheets
 27 | in `<link>` elements. Emogrifier solves this problem by converting CSS styles
 28 | into inline style attributes in your HTML code.
 29 | 
 30 | - [How it works](#how-it-works)
 31 | - [Installation](#installation)
 32 | - [Usage](#usage)
 33 | - [Supported CSS selectors](#supported-css-selectors)
 34 | - [Caveats](#caveats)
 35 | - [Steps to release a new version](#steps-to-release-a-new-version)
 36 | - [Maintainers](#maintainers)
 37 | 
 38 | ## How it Works
 39 | 
 40 | Emogrifier automagically transmogrifies your HTML by parsing your CSS and
 41 | inserting your CSS definitions into tags within your HTML based on your CSS
 42 | selectors.
 43 | 
 44 | ## Installation
 45 | 
 46 | For installing emogrifier, either add `pelago/emogrifier` to the `require`
 47 | section in your project's `composer.json`, or you can use composer as below:
 48 | 
 49 | ```bash
 50 | composer require pelago/emogrifier
 51 | ```
 52 | 
 53 | See https://getcomposer.org/ for more information and documentation.
 54 | 
 55 | ## Usage
 56 | 
 57 | ### Inlining Css
 58 | 
 59 | The most basic way to use the `CssInliner` class is to create an instance with
 60 | the original HTML, inline the external CSS, and then get back the resulting
 61 | HTML:
 62 | 
 63 | ```php
 64 | use Pelago\Emogrifier\CssInliner;
 65 | 
 66 | …
 67 | 
 68 | $visualHtml = CssInliner::fromHtml($html)->inlineCss($css)->render();
 69 | ```
 70 | 
 71 | If there is no external CSS file and all CSS is located within `<style>`
 72 | elements in the HTML, you can omit the `$css` parameter:
 73 | 
 74 | ```php
 75 | $visualHtml = CssInliner::fromHtml($html)->inlineCss()->render();
 76 | ```
 77 | 
 78 | If you would like to get back only the content of the `<body>` element instead
 79 | of the complete HTML document, you can use the `renderBodyContent` method
 80 | instead:
 81 | 
 82 | ```php
 83 | $bodyContent = $visualHtml = CssInliner::fromHtml($html)->inlineCss()
 84 |   ->renderBodyContent();
 85 | ```
 86 | 
 87 | If you would like to modify the inlining process with any of the available
 88 | [options](#options), you will need to call the corresponding methods
 89 | before inlining the CSS. The code then would look like this:
 90 | 
 91 | ```php
 92 | $visualHtml = CssInliner::fromHtml($html)->disableStyleBlocksParsing()
 93 |   ->inlineCss($css)->render();
 94 | ```
 95 | 
 96 | There are also some other HTML-processing classes available
 97 | (all of which are subclasses of `AbstractHtmlProcessor`) which you can use
 98 | to further change the HTML after inlining the CSS.
 99 | (For more details on the classes, please have a look at the sections below.)
100 | `CssInliner` and all HTML-processing classes can share the same `DOMDocument`
101 | instance to work on:
102 | 
103 | ```php
104 | use Pelago\Emogrifier\CssInliner;
105 | use Pelago\Emogrifier\HtmlProcessor\CssToAttributeConverter;
106 | use Pelago\Emogrifier\HtmlProcessor\HtmlPruner;
107 | 
108 | …
109 | 
110 | $cssInliner = CssInliner::fromHtml($html)->inlineCss($css);
111 | $domDocument = $cssInliner->getDomDocument();
112 | HtmlPruner::fromDomDocument($domDocument)->removeElementsWithDisplayNone()
113 |   ->removeRedundantClassesAfterCssInlined($cssInliner);
114 | $finalHtml = CssToAttributeConverter::fromDomDocument($domDocument)
115 |   ->convertCssToVisualAttributes()->render();
116 | ```
117 | 
118 | ### Normalizing and cleaning up HTML
119 | 
120 | The `HtmlNormalizer` class normalizes the given HTML in the following ways:
121 | 
122 | - add a document type (HTML5) if missing
123 | - disentangle incorrectly nested tags
124 | - add HEAD and BODY elements (if they are missing)
125 | - reformat the HTML
126 | 
127 | The class can be used like this:
128 | 
129 | ```php
130 | use Pelago\Emogrifier\HtmlProcessor\HtmlNormalizer;
131 | 
132 | …
133 | 
134 | $cleanHtml = HtmlNormalizer::fromHtml($rawHtml)->render();
135 | ```
136 | 
137 | ### Converting CSS styles to visual HTML attributes
138 | 
139 | The `CssToAttributeConverter` converts a few style attributes values to visual
140 | HTML attributes. This allows to get at least a bit of visual styling for email
141 | clients that do not support CSS well. For example, `style="width: 100px"`
142 | will be converted to `width="100"`.
143 | 
144 | The class can be used like this:
145 | 
146 | ```php
147 | use Pelago\Emogrifier\HtmlProcessor\CssToAttributeConverter;
148 | 
149 | …
150 | 
151 | $visualHtml = CssToAttributeConverter::fromHtml($rawHtml)
152 |   ->convertCssToVisualAttributes()->render();
153 | ```
154 | 
155 | You can also have the `CssToAttributeConverter` work on a `DOMDocument`:
156 | 
157 | ```php
158 | $visualHtml = CssToAttributeConverter::fromDomDocument($domDocument)
159 |   ->convertCssToVisualAttributes()->render();
160 | ```
161 | 
162 | ### Removing redundant content and attributes from the HTML
163 | 
164 | The `HtmlPruner` class can reduce the size of the HTML by removing elements with
165 | a `display: none` style declaration, and/or removing classes from `class`
166 | attributes that are not required.
167 | 
168 | It can be used like this:
169 | 
170 | ```php
171 | use Pelago\Emogrifier\HtmlProcessor\HtmlPruner;
172 | 
173 | …
174 | 
175 | $prunedHtml = HtmlPruner::fromHtml($html)->removeElementsWithDisplayNone()
176 |   ->removeRedundantClasses($classesToKeep)->render();
177 | ```
178 | 
179 | The `removeRedundantClasses` method accepts a whitelist of names of classes that
180 | should be retained.  If this is a post-processing step after inlining CSS, you
181 | can alternatively use `removeRedundantClassesAfterCssInlined`, passing it the
182 | `CssInliner` instance that has inlined the CSS (and having the `HtmlPruner` work
183 | on the `DOMDocument`).  This will use information from the `CssInliner` to
184 | determine which classes are still required (namely, those used in uninlinable
185 | rules that have been copied to a `<style>` element):
186 | 
187 | ```php
188 | $prunedHtml = HtmlPruner::fromDomDocument($cssInliner->getDomDocument())
189 |   ->removeElementsWithDisplayNone()
190 |   ->removeRedundantClassesAfterCssInlined($cssInliner)->render();
191 | ```
192 | 
193 | The `removeElementsWithDisplayNone` method will not remove any elements which
194 | have the class `-emogrifier-keep`.  So if, for example, there are elements which
195 | by default have `display: none` but are revealed by an `@media` rule, or which
196 | are intended as a preheader, you can add that class to those elements.  The
197 | paragraph in this HTML snippet will not be removed even though it has
198 | `display: none` (which has presumably been applied by `CssInliner::inlineCss()`
199 | from a CSS rule `.preheader { display: none; }`):
200 | 
201 | ```html
202 | <p class="preheader -emogrifier-keep" style="display: none;">
203 |   Hello World!
204 | </p>
205 | ```
206 | 
207 | The `removeRedundantClassesAfterCssInlined` (or `removeRedundantClasses`)
208 | method, if invoked after `removeElementsWithDisplayNone`, will remove the
209 | `-emogrifier-keep` class.
210 | 
211 | ### Options
212 | 
213 | There are several options that you can set on the `CssInliner` instance before
214 | calling the `inlineCss` method:
215 | 
216 | * `->disableStyleBlocksParsing()` - By default, `CssInliner` will grab
217 |   all `<style>` blocks in the HTML and will apply the CSS styles as inline
218 |   "style" attributes to the HTML. The `<style>` blocks will then be removed
219 |   from the HTML. If you want to disable this functionality so that `CssInliner`
220 |   leaves these `<style>` blocks in the HTML and does not parse them, you should
221 |   use this option. If you use this option, the contents of the `<style>` blocks
222 |   will _not_ be applied as inline styles and any CSS you want `CssInliner` to
223 |   use must be passed in as described in the [Usage section](#usage) above.
224 | * `->disableInlineStyleAttributesParsing()` - By default, `CssInliner`
225 |   preserves all of the "style" attributes on tags in the HTML you pass to it.
226 |   However if you want to discard all existing inline styles in the HTML before
227 |   the CSS is applied, you should use this option.
228 | * `->addAllowedMediaType(string $mediaName)` - By default, `CssInliner`
229 |   will keep only media types `all`, `screen` and `print`. If you want to keep
230 |   some others, you can use this method to define them.
231 | * `->removeAllowedMediaType(string $mediaName)` - You can use this
232 |   method to remove media types that Emogrifier keeps.
233 | * `->addExcludedSelector(string $selector)` - Keeps elements from
234 |   being affected by CSS inlining.  Note that only elements matching the supplied
235 |   selector(s) will be excluded from CSS inlining, not necessarily their
236 |   descendants.  If you wish to exclude an entire subtree, you should provide
237 |   selector(s) which will match all elements in the subtree, for example by using
238 |   the universal selector:
239 |   ```php
240 |   $cssInliner->addExcludedSelector('.message-preview');
241 |   $cssInliner->addExcludedSelector('.message-preview *');
242 |   ```
243 | 
244 | ### Migrating from the dropped `Emogrifier` class to the `CssInliner` class
245 | 
246 | #### Minimal example
247 | 
248 | Old code using `Emogrifier`:
249 | 
250 | ```php
251 | $emogrifier = new Emogrifier($html);
252 | $html = $emogrifier->emogrify();
253 | ```
254 | 
255 | New code using `CssInliner`:
256 | 
257 | ```php
258 | $html = CssInliner::fromHtml($html)->inlineCss()->render();
259 | ```
260 | 
261 | NB: In this example, the old code removes elements with `display: none;`
262 | while the new code does not, as the default behaviors of the old and
263 | the new class differ in this regard.
264 | 
265 | #### More complex example
266 | 
267 | Old code using `Emogrifier`:
268 | 
269 | ```php
270 | $emogrifier = new Emogrifier($html, $css);
271 | $emogrifier->enableCssToHtmlMapping();
272 | 
273 | $html = $emogrifier->emogrify();
274 | ```
275 | 
276 | New code using `CssInliner` and family:
277 | 
278 | ```php
279 | $domDocument = CssInliner::fromHtml($html)->inlineCss($css)->getDomDocument();
280 | 
281 | HtmlPruner::fromDomDocument($domDocument)->removeElementsWithDisplayNone();
282 | $html = CssToAttributeConverter::fromDomDocument($domDocument)
283 |   ->convertCssToVisualAttributes()->render();
284 | ```
285 | 
286 | ## Supported CSS selectors
287 | 
288 | Emogrifier currently supports the following
289 | [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors):
290 | 
291 |  * [type](https://developer.mozilla.org/en-US/docs/Web/CSS/Type_selectors)
292 |  * [class](https://developer.mozilla.org/en-US/docs/Web/CSS/Class_selectors)
293 |  * [ID](https://developer.mozilla.org/en-US/docs/Web/CSS/ID_selectors)
294 |  * [universal](https://developer.mozilla.org/en-US/docs/Web/CSS/Universal_selectors)
295 |  * [attribute](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors):
296 |     * presence
297 |     * exact value match
298 |     * value with `~` (one word within a whitespace-separated list of words)
299 |     * value with `|` (either exact value match or prefix followed by a hyphen)
300 |     * value with `^` (prefix match)
301 |     * value with `$` (suffix match)
302 |     * value with `*` (substring match)
303 |  * [adjacent](https://developer.mozilla.org/en-US/docs/Web/CSS/Adjacent_sibling_selectors)
304 |  * [general sibling](https://developer.mozilla.org/en-US/docs/Web/CSS/General_sibling_combinator)
305 |  * [child](https://developer.mozilla.org/en-US/docs/Web/CSS/Child_selectors)
306 |  * [descendant](https://developer.mozilla.org/en-US/docs/Web/CSS/Descendant_selectors)
307 |  * [pseudo-classes](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes):
308 |    * [empty](https://developer.mozilla.org/en-US/docs/Web/CSS/:empty)
309 |    * [first-child](https://developer.mozilla.org/en-US/docs/Web/CSS/:first-child)
310 |    * [first-of-type](https://developer.mozilla.org/en-US/docs/Web/CSS/:first-of-type)
311 |      (with a type, e.g. `p:first-of-type` but not `*:first-of-type`)
312 |    * [last-child](https://developer.mozilla.org/en-US/docs/Web/CSS/:last-child)
313 |    * [last-of-type](https://developer.mozilla.org/en-US/docs/Web/CSS/:last-of-type)
314 |      (with a type)
315 |    * [not()](https://developer.mozilla.org/en-US/docs/Web/CSS/:not)
316 |    * [nth-child()](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-child)
317 |    * [nth-last-child()](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-last-child)
318 |    * [nth-last-of-type()](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-last-of-type)
319 |      (with a type)
320 |    * [nth-of-type()](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-of-type)
321 |      (with a type)
322 |    * [only-child](https://developer.mozilla.org/en-US/docs/Web/CSS/:only-child)
323 |    * [only-of-type](https://developer.mozilla.org/en-US/docs/Web/CSS/:only-of-type)
324 |      (with a type)
325 | 
326 | The following selectors are not implemented yet:
327 | 
328 |  * [case-insensitive attribute value](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors#case-insensitive)
329 |  * static [pseudo-classes](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes)
330 |    not listed above as supported – rules involving them will nonetheless be
331 |    preserved and copied to a `<style>` element in the HTML – including (but not
332 |    necessarily limited to) the following:
333 |    * [any-link](https://developer.mozilla.org/en-US/docs/Web/CSS/:any-link)
334 |    * [first-of-type](https://developer.mozilla.org/en-US/docs/Web/CSS/:first-of-type)
335 |      without a type
336 |    * [last-of-type](https://developer.mozilla.org/en-US/docs/Web/CSS/:last-of-type)
337 |      without a type
338 |    * [nth-last-of-type()](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-last-of-type)
339 |      without a type
340 |    * [nth-of-type()](https://developer.mozilla.org/en-US/docs/Web/CSS/:nth-of-type)
341 |      without a type
342 |    * [only-of-type()](https://developer.mozilla.org/en-US/docs/Web/CSS/:only-of-type)
343 |      without a type
344 |    * [optional](https://developer.mozilla.org/en-US/docs/Web/CSS/:optional)
345 |    * [required](https://developer.mozilla.org/en-US/docs/Web/CSS/:required)
346 | 
347 | Rules involving the following selectors cannot be applied as inline styles.
348 | They will, however, be preserved and copied to a `<style>` element in the HTML:
349 | 
350 |  * dynamic [pseudo-classes](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes)
351 |    (such as `:hover`)
352 |  * [pseudo-elements](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-elements)
353 |    (such as `::after`)
354 | 
355 | ## Caveats
356 | 
357 | * Emogrifier requires the HTML and the CSS to be UTF-8. Encodings like
358 |   ISO8859-1 or ISO8859-15 are not supported.
359 | * Emogrifier preserves all valuable `@media` rules.  Media queries can be very
360 |   useful in responsive email design.  See
361 |   [media query support](https://litmus.com/help/email-clients/media-query-support/).
362 |   However, in order for them to be effective, you may need to add `!important`
363 |   to some of the declarations within them so that they will override CSS styles
364 |   that have been inlined.  For example, with the following CSS, the `font-size`
365 |   declaration in the `@media` rule would not override the font size for `p`
366 |   elements from the preceding rule after that has been inlined as
367 |   `<p style="font-size: 16px;">` in the HTML, without the `!important` directive
368 |   (even though `!important` would not be necessary if the CSS were not inlined):
369 |   ```css
370 |   p {
371 |     font-size: 16px;
372 |   }
373 |   @media (max-width: 640px) {
374 |     p {
375 |       font-size: 14px !important;
376 |     }
377 |   }
378 |   ```
379 | * Emogrifier cannot inline CSS rules involving selectors with pseudo-elements
380 |   (such as `::after`) or dynamic pseudo-classes (such as `:hover`) – it is
381 |   impossible.  However, such rules will be preserved and copied to a `<style>`
382 |   element, as for `@media` rules.  The same caveat about the possible need for
383 |   the `!important` directive also applies with pseudo-classes.
384 | * Emogrifier will grab existing inline style attributes _and_ will
385 |   grab `<style>` blocks from your HTML, but it will not grab CSS files
386 |   referenced in `<link>` elements or `@import` rules (though it will leave them
387 |   intact for email clients that support them).
388 | * Even with styles inline, certain CSS properties are ignored by certain email
389 |   clients. For more information, refer to these resources:
390 |     * [http://www.email-standards.org/](http://www.email-standards.org/)
391 |     * [https://www.campaignmonitor.com/css/](https://www.campaignmonitor.com/css/)
392 |     * [http://templates.mailchimp.com/resources/email-client-css-support/](http://templates.mailchimp.com/resources/email-client-css-support/)
393 | * All CSS attributes that apply to an element will be applied, even if they are
394 |   redundant. For example, if you define a font attribute _and_ a font-size
395 |   attribute, both attributes will be applied to that element (in other words,
396 |   the more specific attribute will not be combined into the more general
397 |   attribute).
398 | * There's a good chance you might encounter problems if your HTML is not
399 |   well-formed and valid (DOMDocument might complain). If you get problems like
400 |   this, consider running your HTML through
401 |   [Tidy](http://php.net/manual/en/book.tidy.php) before you pass it to
402 |   Emogrifier.
403 | * Emogrifier automatically converts the provided (X)HTML into HTML5, i.e.,
404 |   self-closing tags will lose their slash. To keep your HTML valid, it is
405 |   recommended to use HTML5 instead of one of the XHTML variants.
406 | 
407 | ## Steps to release a new version
408 | 
409 | 1. In the [composer.json](composer.json), update the `branch-alias` entry to
410 |    point to the release _after_ the upcoming release.
411 | 1. In the [CHANGELOG.md](CHANGELOG.md), create a new section with subheadings
412 |    for changes _after_ the upcoming release, set the version number for the
413 |    upcoming release, and remove any empty sections.
414 | 1. Create a pull request "Prepare release of version x.y.z" with those
415 |    changes.
416 | 1. Have the pull request reviewed and merged.
417 | 1. Tag the new release.
418 | 1. In the [Releases tab](https://github.com/MyIntervals/emogrifier/releases),
419 |    create a new release and copy the change log entries to the new release.
420 | 1. Post about the new release on social media.
421 | 
422 | ## Maintainers
423 | 
424 | * [Oliver Klee](https://github.com/oliverklee)
425 | * [Zoli Szabó](https://github.com/zoliszabo)
426 | * [Jake Hotson](https://github.com/JakeQZ)
427 | * [John Reeve](https://github.com/jjriv)
428 | 


--------------------------------------------------------------------------------
/src/CssInliner.php:
--------------------------------------------------------------------------------
   1 | <?php
   2 | 
   3 | declare(strict_types=1);
   4 | 
   5 | namespace Pelago\Emogrifier;
   6 | 
   7 | use Pelago\Emogrifier\Css\CssDocument;
   8 | use Pelago\Emogrifier\HtmlProcessor\AbstractHtmlProcessor;
   9 | use Pelago\Emogrifier\Utilities\CssConcatenator;
  10 | use Symfony\Component\CssSelector\CssSelectorConverter;
  11 | use Symfony\Component\CssSelector\Exception\ParseException;
  12 | 
  13 | /**
  14 |  * This class provides functions for converting CSS styles into inline style attributes in your HTML code.
  15 |  */
  16 | class CssInliner extends AbstractHtmlProcessor
  17 | {
  18 |     /**
  19 |      * @var int
  20 |      */
  21 |     private const CACHE_KEY_SELECTOR = 0;
  22 | 
  23 |     /**
  24 |      * @var int
  25 |      */
  26 |     private const CACHE_KEY_CSS_DECLARATIONS_BLOCK = 1;
  27 | 
  28 |     /**
  29 |      * @var int
  30 |      */
  31 |     private const CACHE_KEY_COMBINED_STYLES = 2;
  32 | 
  33 |     /**
  34 |      * Regular expression component matching a static pseudo class in a selector, without the preceding ":",
  35 |      * for which the applicable elements can be determined (by converting the selector to an XPath expression).
  36 |      * (Contains alternation without a group and is intended to be placed within a capturing, non-capturing or lookahead
  37 |      * group, as appropriate for the usage context.)
  38 |      *
  39 |      * @var string
  40 |      */
  41 |     private const PSEUDO_CLASS_MATCHER
  42 |         = 'empty|(?:first|last|nth(?:-last)?+|only)-(?:child|of-type)|not\\([[:ascii:]]*\\)';
  43 | 
  44 |     /**
  45 |      * This regular expression componenet matches an `...of-type` pseudo class name, without the preceding ":".  These
  46 |      * pseudo-classes can currently online be inlined if they have an associated type in the selector expression.
  47 |      *
  48 |      * @var string
  49 |      */
  50 |     private const OF_TYPE_PSEUDO_CLASS_MATCHER = '(?:first|last|nth(?:-last)?+|only)-of-type';
  51 | 
  52 |     /**
  53 |      * regular expression component to match a selector combinator
  54 |      *
  55 |      * @var string
  56 |      */
  57 |     private const COMBINATOR_MATCHER = '(?:\\s++|\\s*+[>+~]\\s*+)(?=[[:alpha:]_\\-.#*:\\[])';
  58 | 
  59 |     /**
  60 |      * @var array<string, bool>
  61 |      */
  62 |     private $excludedSelectors = [];
  63 | 
  64 |     /**
  65 |      * @var array<string, bool>
  66 |      */
  67 |     private $allowedMediaTypes = ['all' => true, 'screen' => true, 'print' => true];
  68 | 
  69 |     /**
  70 |      * @var array{
  71 |      *         0: array<string, int>,
  72 |      *         1: array<string, array<string, string>>,
  73 |      *         2: array<string, string>
  74 |      *      }
  75 |      */
  76 |     private $caches = [
  77 |         self::CACHE_KEY_SELECTOR => [],
  78 |         self::CACHE_KEY_CSS_DECLARATIONS_BLOCK => [],
  79 |         self::CACHE_KEY_COMBINED_STYLES => [],
  80 |     ];
  81 | 
  82 |     /**
  83 |      * @var ?CssSelectorConverter
  84 |      */
  85 |     private $cssSelectorConverter = null;
  86 | 
  87 |     /**
  88 |      * the visited nodes with the XPath paths as array keys
  89 |      *
  90 |      * @var array<string, \DOMElement>
  91 |      */
  92 |     private $visitedNodes = [];
  93 | 
  94 |     /**
  95 |      * the styles to apply to the nodes with the XPath paths as array keys for the outer array
  96 |      * and the attribute names/values as key/value pairs for the inner array
  97 |      *
  98 |      * @var array<string, array<string, string>>
  99 |      */
 100 |     private $styleAttributesForNodes = [];
 101 | 
 102 |     /**
 103 |      * Determines whether the "style" attributes of tags in the the HTML passed to this class should be preserved.
 104 |      * If set to false, the value of the style attributes will be discarded.
 105 |      *
 106 |      * @var bool
 107 |      */
 108 |     private $isInlineStyleAttributesParsingEnabled = true;
 109 | 
 110 |     /**
 111 |      * Determines whether the `<style>` blocks in the HTML passed to this class should be parsed.
 112 |      *
 113 |      * If set to true, the `<style>` blocks will be removed from the HTML and their contents will be applied to the HTML
 114 |      * via inline styles.
 115 |      *
 116 |      * If set to false, the `<style>` blocks will be left as they are in the HTML.
 117 |      *
 118 |      * @var bool
 119 |      */
 120 |     private $isStyleBlocksParsingEnabled = true;
 121 | 
 122 |     /**
 123 |      * For calculating selector precedence order.
 124 |      * Keys are a regular expression part to match before a CSS name.
 125 |      * Values are a multiplier factor per match to weight specificity.
 126 |      *
 127 |      * @var array<string, int>
 128 |      */
 129 |     private $selectorPrecedenceMatchers = [
 130 |         // IDs: worth 10000
 131 |         '\\#' => 10000,
 132 |         // classes, attributes, pseudo-classes (not pseudo-elements) except `:not`: worth 100
 133 |         '(?:\\.|\\[|(?<!:):(?!not\\())' => 100,
 134 |         // elements (not attribute values or `:not`), pseudo-elements: worth 1
 135 |         '(?:(?<![="\':\\w\\-])|::)' => 1,
 136 |     ];
 137 | 
 138 |     /**
 139 |      * array of data describing CSS rules which apply to the document but cannot be inlined, in the format returned by
 140 |      * {@see collateCssRules}
 141 |      *
 142 |      * @var array<array-key, array{
 143 |      *          media: string,
 144 |      *          selector: string,
 145 |      *          hasUnmatchablePseudo: bool,
 146 |      *          declarationsBlock: string,
 147 |      *          line: int
 148 |      *      }>|null
 149 |      */
 150 |     private $matchingUninlinableCssRules = null;
 151 | 
 152 |     /**
 153 |      * Emogrifier will throw Exceptions when it encounters an error instead of silently ignoring them.
 154 |      *
 155 |      * @var bool
 156 |      */
 157 |     private $debug = false;
 158 | 
 159 |     /**
 160 |      * Inlines the given CSS into the existing HTML.
 161 |      *
 162 |      * @param string $css the CSS to inline, must be UTF-8-encoded
 163 |      *
 164 |      * @return self fluent interface
 165 |      *
 166 |      * @throws ParseException in debug mode, if an invalid selector is encountered
 167 |      * @throws \RuntimeException in debug mode, if an internal PCRE error occurs
 168 |      */
 169 |     public function inlineCss(string $css = ''): self
 170 |     {
 171 |         $this->clearAllCaches();
 172 |         $this->purgeVisitedNodes();
 173 | 
 174 |         $this->normalizeStyleAttributesOfAllNodes();
 175 | 
 176 |         $combinedCss = $css;
 177 |         // grab any existing style blocks from the HTML and append them to the existing CSS
 178 |         // (these blocks should be appended so as to have precedence over conflicting styles in the existing CSS)
 179 |         if ($this->isStyleBlocksParsingEnabled) {
 180 |             $combinedCss .= $this->getCssFromAllStyleNodes();
 181 |         }
 182 |         $parsedCss = new CssDocument($combinedCss);
 183 | 
 184 |         $excludedNodes = $this->getNodesToExclude();
 185 |         $cssRules = $this->collateCssRules($parsedCss);
 186 |         $cssSelectorConverter = $this->getCssSelectorConverter();
 187 |         foreach ($cssRules['inlinable'] as $cssRule) {
 188 |             try {
 189 |                 $nodesMatchingCssSelectors = $this->getXPath()
 190 |                     ->query($cssSelectorConverter->toXPath($cssRule['selector']));
 191 | 
 192 |                 /** @var \DOMElement $node */
 193 |                 foreach ($nodesMatchingCssSelectors as $node) {
 194 |                     if (\in_array($node, $excludedNodes, true)) {
 195 |                         continue;
 196 |                     }
 197 |                     $this->copyInlinableCssToStyleAttribute($node, $cssRule);
 198 |                 }
 199 |             } catch (ParseException $e) {
 200 |                 if ($this->debug) {
 201 |                     throw $e;
 202 |                 }
 203 |             }
 204 |         }
 205 | 
 206 |         if ($this->isInlineStyleAttributesParsingEnabled) {
 207 |             $this->fillStyleAttributesWithMergedStyles();
 208 |         }
 209 | 
 210 |         $this->removeImportantAnnotationFromAllInlineStyles();
 211 | 
 212 |         $this->determineMatchingUninlinableCssRules($cssRules['uninlinable']);
 213 |         $this->copyUninlinableCssToStyleNode($parsedCss);
 214 | 
 215 |         return $this;
 216 |     }
 217 | 
 218 |     /**
 219 |      * Disables the parsing of inline styles.
 220 |      *
 221 |      * @return self fluent interface
 222 |      */
 223 |     public function disableInlineStyleAttributesParsing(): self
 224 |     {
 225 |         $this->isInlineStyleAttributesParsingEnabled = false;
 226 | 
 227 |         return $this;
 228 |     }
 229 | 
 230 |     /**
 231 |      * Disables the parsing of `<style>` blocks.
 232 |      *
 233 |      * @return self fluent interface
 234 |      */
 235 |     public function disableStyleBlocksParsing(): self
 236 |     {
 237 |         $this->isStyleBlocksParsingEnabled = false;
 238 | 
 239 |         return $this;
 240 |     }
 241 | 
 242 |     /**
 243 |      * Marks a media query type to keep.
 244 |      *
 245 |      * @param string $mediaName the media type name, e.g., "braille"
 246 |      *
 247 |      * @return self fluent interface
 248 |      */
 249 |     public function addAllowedMediaType(string $mediaName): self
 250 |     {
 251 |         $this->allowedMediaTypes[$mediaName] = true;
 252 | 
 253 |         return $this;
 254 |     }
 255 | 
 256 |     /**
 257 |      * Drops a media query type from the allowed list.
 258 |      *
 259 |      * @param string $mediaName the tag name, e.g., "braille"
 260 |      *
 261 |      * @return self fluent interface
 262 |      */
 263 |     public function removeAllowedMediaType(string $mediaName): self
 264 |     {
 265 |         if (isset($this->allowedMediaTypes[$mediaName])) {
 266 |             unset($this->allowedMediaTypes[$mediaName]);
 267 |         }
 268 | 
 269 |         return $this;
 270 |     }
 271 | 
 272 |     /**
 273 |      * Adds a selector to exclude nodes from emogrification.
 274 |      *
 275 |      * Any nodes that match the selector will not have their style altered.
 276 |      *
 277 |      * @param string $selector the selector to exclude, e.g., ".editor"
 278 |      *
 279 |      * @return self fluent interface
 280 |      */
 281 |     public function addExcludedSelector(string $selector): self
 282 |     {
 283 |         $this->excludedSelectors[$selector] = true;
 284 | 
 285 |         return $this;
 286 |     }
 287 | 
 288 |     /**
 289 |      * No longer excludes the nodes matching this selector from emogrification.
 290 |      *
 291 |      * @param string $selector the selector to no longer exclude, e.g., ".editor"
 292 |      *
 293 |      * @return self fluent interface
 294 |      */
 295 |     public function removeExcludedSelector(string $selector): self
 296 |     {
 297 |         if (isset($this->excludedSelectors[$selector])) {
 298 |             unset($this->excludedSelectors[$selector]);
 299 |         }
 300 | 
 301 |         return $this;
 302 |     }
 303 | 
 304 |     /**
 305 |      * Sets the debug mode.
 306 |      *
 307 |      * @param bool $debug set to true to enable debug mode
 308 |      *
 309 |      * @return self fluent interface
 310 |      */
 311 |     public function setDebug(bool $debug): self
 312 |     {
 313 |         $this->debug = $debug;
 314 | 
 315 |         return $this;
 316 |     }
 317 | 
 318 |     /**
 319 |      * Gets the array of selectors present in the CSS provided to `inlineCss()` for which the declarations could not be
 320 |      * applied as inline styles, but which may affect elements in the HTML.  The relevant CSS will have been placed in a
 321 |      * `<style>` element.  The selectors may include those used within `@media` rules or those involving dynamic
 322 |      * pseudo-classes (such as `:hover`) or pseudo-elements (such as `::after`).
 323 |      *
 324 |      * @return array<array-key, string>
 325 |      *
 326 |      * @throws \BadMethodCallException if `inlineCss` has not been called first
 327 |      */
 328 |     public function getMatchingUninlinableSelectors(): array
 329 |     {
 330 |         return \array_column($this->getMatchingUninlinableCssRules(), 'selector');
 331 |     }
 332 | 
 333 |     /**
 334 |      * @return array<array-key, array{
 335 |      *             media: string,
 336 |      *             selector: string,
 337 |      *             hasUnmatchablePseudo: bool,
 338 |      *             declarationsBlock: string,
 339 |      *             line: int
 340 |      *         }>
 341 |      *
 342 |      * @throws \BadMethodCallException if `inlineCss` has not been called first
 343 |      */
 344 |     private function getMatchingUninlinableCssRules(): array
 345 |     {
 346 |         if (!\is_array($this->matchingUninlinableCssRules)) {
 347 |             throw new \BadMethodCallException('inlineCss must be called first', 1568385221);
 348 |         }
 349 | 
 350 |         return $this->matchingUninlinableCssRules;
 351 |     }
 352 | 
 353 |     /**
 354 |      * Clears all caches.
 355 |      */
 356 |     private function clearAllCaches(): void
 357 |     {
 358 |         $this->caches = [
 359 |             self::CACHE_KEY_SELECTOR => [],
 360 |             self::CACHE_KEY_CSS_DECLARATIONS_BLOCK => [],
 361 |             self::CACHE_KEY_COMBINED_STYLES => [],
 362 |         ];
 363 |     }
 364 | 
 365 |     /**
 366 |      * Purges the visited nodes.
 367 |      */
 368 |     private function purgeVisitedNodes(): void
 369 |     {
 370 |         $this->visitedNodes = [];
 371 |         $this->styleAttributesForNodes = [];
 372 |     }
 373 | 
 374 |     /**
 375 |      * Parses the document and normalizes all existing CSS attributes.
 376 |      * This changes 'DISPLAY: none' to 'display: none'.
 377 |      * We wouldn't have to do this if DOMXPath supported XPath 2.0.
 378 |      * Also stores a reference of nodes with existing inline styles so we don't overwrite them.
 379 |      */
 380 |     private function normalizeStyleAttributesOfAllNodes(): void
 381 |     {
 382 |         /** @var \DOMElement $node */
 383 |         foreach ($this->getAllNodesWithStyleAttribute() as $node) {
 384 |             if ($this->isInlineStyleAttributesParsingEnabled) {
 385 |                 $this->normalizeStyleAttributes($node);
 386 |             }
 387 |             // Remove style attribute in every case, so we can add them back (if inline style attributes
 388 |             // parsing is enabled) to the end of the style list, thus keeping the right priority of CSS rules;
 389 |             // else original inline style rules may remain at the beginning of the final inline style definition
 390 |             // of a node, which may give not the desired results
 391 |             $node->removeAttribute('style');
 392 |         }
 393 |     }
 394 | 
 395 |     /**
 396 |      * Returns a list with all DOM nodes that have a style attribute.
 397 |      *
 398 |      * @return \DOMNodeList
 399 |      *
 400 |      * @throws \RuntimeException
 401 |      */
 402 |     private function getAllNodesWithStyleAttribute(): \DOMNodeList
 403 |     {
 404 |         $query = '//*[@style]';
 405 |         $matches = $this->getXPath()->query($query);
 406 |         if (!$matches instanceof \DOMNodeList) {
 407 |             throw new \RuntimeException('XPatch query failed: ' . $query, 1618577797);
 408 |         }
 409 | 
 410 |         return $matches;
 411 |     }
 412 | 
 413 |     /**
 414 |      * Normalizes the value of the "style" attribute and saves it.
 415 |      *
 416 |      * @param \DOMElement $node
 417 |      */
 418 |     private function normalizeStyleAttributes(\DOMElement $node): void
 419 |     {
 420 |         $normalizedOriginalStyle = \preg_replace_callback(
 421 |             '/-?+[_a-zA-Z][\\w\\-]*+(?=:)/S',
 422 |             /** @param array<int, string> $propertyNameMatches */
 423 |             static function (array $propertyNameMatches): string {
 424 |                 return \strtolower($propertyNameMatches[0]);
 425 |             },
 426 |             $node->getAttribute('style')
 427 |         );
 428 | 
 429 |         // In order to not overwrite existing style attributes in the HTML, we have to save the original HTML styles.
 430 |         /** @var ?string $nodePath */
 431 |         $nodePath = $node->getNodePath();
 432 |         if (\is_string($nodePath) && !isset($this->styleAttributesForNodes[$nodePath])) {
 433 |             $this->styleAttributesForNodes[$nodePath] = $this->parseCssDeclarationsBlock($normalizedOriginalStyle);
 434 |             $this->visitedNodes[$nodePath] = $node;
 435 |         }
 436 | 
 437 |         $node->setAttribute('style', $normalizedOriginalStyle);
 438 |     }
 439 | 
 440 |     /**
 441 |      * Parses a CSS declaration block into property name/value pairs.
 442 |      *
 443 |      * Example:
 444 |      *
 445 |      * The declaration block
 446 |      *
 447 |      *   "color: #000; font-weight: bold;"
 448 |      *
 449 |      * will be parsed into the following array:
 450 |      *
 451 |      *   "color" => "#000"
 452 |      *   "font-weight" => "bold"
 453 |      *
 454 |      * @param string $cssDeclarationsBlock the CSS declarations block without the curly braces, may be empty
 455 |      *
 456 |      * @return array<string, string>
 457 |      *         the CSS declarations with the property names as array keys and the property values as array values
 458 |      */
 459 |     private function parseCssDeclarationsBlock(string $cssDeclarationsBlock): array
 460 |     {
 461 |         if (isset($this->caches[self::CACHE_KEY_CSS_DECLARATIONS_BLOCK][$cssDeclarationsBlock])) {
 462 |             return $this->caches[self::CACHE_KEY_CSS_DECLARATIONS_BLOCK][$cssDeclarationsBlock];
 463 |         }
 464 | 
 465 |         $properties = [];
 466 |         foreach (\preg_split('/;(?!base64|charset)/', $cssDeclarationsBlock) as $declaration) {
 467 |             /** @var array<int, string> $matches */
 468 |             $matches = [];
 469 |             if (!\preg_match('/^([A-Za-z\\-]+)\\s*:\\s*(.+)$/s', \trim($declaration), $matches)) {
 470 |                 continue;
 471 |             }
 472 | 
 473 |             $propertyName = \strtolower($matches[1]);
 474 |             $propertyValue = $matches[2];
 475 |             $properties[$propertyName] = $propertyValue;
 476 |         }
 477 |         $this->caches[self::CACHE_KEY_CSS_DECLARATIONS_BLOCK][$cssDeclarationsBlock] = $properties;
 478 | 
 479 |         return $properties;
 480 |     }
 481 | 
 482 |     /**
 483 |      * Returns CSS content.
 484 |      *
 485 |      * @return string
 486 |      */
 487 |     private function getCssFromAllStyleNodes(): string
 488 |     {
 489 |         $styleNodes = $this->getXPath()->query('//style');
 490 |         if ($styleNodes === false) {
 491 |             return '';
 492 |         }
 493 | 
 494 |         $css = '';
 495 |         foreach ($styleNodes as $styleNode) {
 496 |             $css .= "\n\n" . $styleNode->nodeValue;
 497 |             $parentNode = $styleNode->parentNode;
 498 |             if ($parentNode instanceof \DOMNode) {
 499 |                 $parentNode->removeChild($styleNode);
 500 |             }
 501 |         }
 502 | 
 503 |         return $css;
 504 |     }
 505 | 
 506 |     /**
 507 |      * Find the nodes that are not to be emogrified.
 508 |      *
 509 |      * @return array<int, \DOMElement>
 510 |      *
 511 |      * @throws ParseException
 512 |      * @throws \UnexpectedValueException
 513 |      */
 514 |     private function getNodesToExclude(): array
 515 |     {
 516 |         $excludedNodes = [];
 517 |         foreach (\array_keys($this->excludedSelectors) as $selectorToExclude) {
 518 |             try {
 519 |                 $matchingNodes = $this->getXPath()
 520 |                     ->query($this->getCssSelectorConverter()->toXPath($selectorToExclude));
 521 | 
 522 |                 foreach ($matchingNodes as $node) {
 523 |                     if (!$node instanceof \DOMElement) {
 524 |                         /** @var string $path */
 525 |                         $path = $node->getNodePath() ?? '$node';
 526 |                         throw new \UnexpectedValueException($path . ' is not a DOMElement.', 1617975914);
 527 |                     }
 528 |                     $excludedNodes[] = $node;
 529 |                 }
 530 |             } catch (ParseException $e) {
 531 |                 if ($this->debug) {
 532 |                     throw $e;
 533 |                 }
 534 |             }
 535 |         }
 536 | 
 537 |         return $excludedNodes;
 538 |     }
 539 | 
 540 |     /**
 541 |      * @return CssSelectorConverter
 542 |      */
 543 |     private function getCssSelectorConverter(): CssSelectorConverter
 544 |     {
 545 |         if (!$this->cssSelectorConverter instanceof CssSelectorConverter) {
 546 |             $this->cssSelectorConverter = new CssSelectorConverter();
 547 |         }
 548 | 
 549 |         return $this->cssSelectorConverter;
 550 |     }
 551 | 
 552 |     /**
 553 |      * Collates the individual rules from a `CssDocument` object.
 554 |      *
 555 |      * @param CssDocument $parsedCss
 556 |      *
 557 |      * @return array<string, array<array-key, array{
 558 |      *           media: string,
 559 |      *           selector: string,
 560 |      *           hasUnmatchablePseudo: bool,
 561 |      *           declarationsBlock: string,
 562 |      *           line: int
 563 |      *         }>>
 564 |      *         This 2-entry array has the key "inlinable" containing rules which can be inlined as `style` attributes
 565 |      *         and the key "uninlinable" containing rules which cannot.  Each value is an array of sub-arrays with the
 566 |      *         following keys:
 567 |      *         - "media" (the media query string, e.g. "@media screen and (max-width: 480px)",
 568 |      *           or an empty string if not from a `@media` rule);
 569 |      *         - "selector" (the CSS selector, e.g., "*" or "header h1");
 570 |      *         - "hasUnmatchablePseudo" (`true` if that selector contains pseudo-elements or dynamic pseudo-classes such
 571 |      *           that the declarations cannot be applied inline);
 572 |      *         - "declarationsBlock" (the semicolon-separated CSS declarations for that selector,
 573 |      *           e.g., `color: red; height: 4px;`);
 574 |      *         - "line" (the line number, e.g. 42).
 575 |      */
 576 |     private function collateCssRules(CssDocument $parsedCss): array
 577 |     {
 578 |         $matches = $parsedCss->getStyleRulesData(\array_keys($this->allowedMediaTypes));
 579 | 
 580 |         $cssRules = [
 581 |             'inlinable' => [],
 582 |             'uninlinable' => [],
 583 |         ];
 584 |         foreach ($matches as $key => $cssRule) {
 585 |             if (!$cssRule->hasAtLeastOneDeclaration()) {
 586 |                 continue;
 587 |             }
 588 | 
 589 |             $mediaQuery = $cssRule->getContainingAtRule();
 590 |             $declarationsBlock = $cssRule->getDeclarationAsText();
 591 |             foreach ($cssRule->getSelectors() as $selector) {
 592 |                 // don't process pseudo-elements and behavioral (dynamic) pseudo-classes;
 593 |                 // only allow structural pseudo-classes
 594 |                 $hasPseudoElement = \strpos($selector, '::') !== false;
 595 |                 $hasUnmatchablePseudo = $hasPseudoElement || $this->hasUnsupportedPseudoClass($selector);
 596 | 
 597 |                 $parsedCssRule = [
 598 |                     'media' => $mediaQuery,
 599 |                     'selector' => $selector,
 600 |                     'hasUnmatchablePseudo' => $hasUnmatchablePseudo,
 601 |                     'declarationsBlock' => $declarationsBlock,
 602 |                     // keep track of where it appears in the file, since order is important
 603 |                     'line' => $key,
 604 |                 ];
 605 |                 $ruleType = (!$cssRule->hasContainingAtRule() && !$hasUnmatchablePseudo) ? 'inlinable' : 'uninlinable';
 606 |                 $cssRules[$ruleType][] = $parsedCssRule;
 607 |             }
 608 |         }
 609 | 
 610 |         \usort(
 611 |             $cssRules['inlinable'],
 612 |             /**
 613 |              * @param array{selector: string, line: int} $first
 614 |              * @param array{selector: string, line: int} $second
 615 |              */
 616 |             function (array $first, array $second): int {
 617 |                 return $this->sortBySelectorPrecedence($first, $second);
 618 |             }
 619 |         );
 620 | 
 621 |         return $cssRules;
 622 |     }
 623 | 
 624 |     /**
 625 |      * Tests if a selector contains a pseudo-class which would mean it cannot be converted to an XPath expression for
 626 |      * inlining CSS declarations.
 627 |      *
 628 |      * Any pseudo class that does not match {@see PSEUDO_CLASS_MATCHER} cannot be converted.  Additionally, `...of-type`
 629 |      * pseudo-classes cannot be converted if they are not associated with a type selector.
 630 |      *
 631 |      * @param string $selector
 632 |      *
 633 |      * @return bool
 634 |      */
 635 |     private function hasUnsupportedPseudoClass(string $selector): bool
 636 |     {
 637 |         if (\preg_match('/:(?!' . self::PSEUDO_CLASS_MATCHER . ')[\\w\\-]/i', $selector)) {
 638 |             return true;
 639 |         }
 640 | 
 641 |         if (!\preg_match('/:(?:' . self::OF_TYPE_PSEUDO_CLASS_MATCHER . ')/i', $selector)) {
 642 |             return false;
 643 |         }
 644 | 
 645 |         foreach (\preg_split('/' . self::COMBINATOR_MATCHER . '/', $selector) as $selectorPart) {
 646 |             if ($this->selectorPartHasUnsupportedOfTypePseudoClass($selectorPart)) {
 647 |                 return true;
 648 |             }
 649 |         }
 650 | 
 651 |         return false;
 652 |     }
 653 | 
 654 |     /**
 655 |      * Tests if part of a selector contains an `...of-type` pseudo-class such that it cannot be converted to an XPath
 656 |      * expression.
 657 |      *
 658 |      * @param string $selectorPart part of a selector which has been split up at combinators
 659 |      *
 660 |      * @return bool `true` if the selector part does not have a type but does have an `...of-type` pseudo-class
 661 |      */
 662 |     private function selectorPartHasUnsupportedOfTypePseudoClass(string $selectorPart): bool
 663 |     {
 664 |         if (\preg_match('/^[\\w\\-]/', $selectorPart)) {
 665 |             return false;
 666 |         }
 667 | 
 668 |         return (bool)\preg_match('/:(?:' . self::OF_TYPE_PSEUDO_CLASS_MATCHER . ')/i', $selectorPart);
 669 |     }
 670 | 
 671 |     /**
 672 |      * @param array{selector: string, line: int} $first
 673 |      * @param array{selector: string, line: int} $second
 674 |      *
 675 |      * @return int
 676 |      */
 677 |     private function sortBySelectorPrecedence(array $first, array $second): int
 678 |     {
 679 |         $precedenceOfFirst = $this->getCssSelectorPrecedence($first['selector']);
 680 |         $precedenceOfSecond = $this->getCssSelectorPrecedence($second['selector']);
 681 | 
 682 |         // We want these sorted in ascending order so selectors with lesser precedence get processed first and
 683 |         // selectors with greater precedence get sorted last.
 684 |         $precedenceForEquals = $first['line'] < $second['line'] ? -1 : 1;
 685 |         $precedenceForNotEquals = $precedenceOfFirst < $precedenceOfSecond ? -1 : 1;
 686 |         return ($precedenceOfFirst === $precedenceOfSecond) ? $precedenceForEquals : $precedenceForNotEquals;
 687 |     }
 688 | 
 689 |     /**
 690 |      * @param string $selector
 691 |      *
 692 |      * @return int
 693 |      */
 694 |     private function getCssSelectorPrecedence(string $selector): int
 695 |     {
 696 |         $selectorKey = \md5($selector);
 697 |         if (isset($this->caches[self::CACHE_KEY_SELECTOR][$selectorKey])) {
 698 |             return $this->caches[self::CACHE_KEY_SELECTOR][$selectorKey];
 699 |         }
 700 | 
 701 |         $precedence = 0;
 702 |         foreach ($this->selectorPrecedenceMatchers as $matcher => $value) {
 703 |             if (\trim($selector) === '') {
 704 |                 break;
 705 |             }
 706 |             $number = 0;
 707 |             $selector = \preg_replace('/' . $matcher . '\\w+/', '', $selector, -1, $number);
 708 |             $precedence += ($value * (int)$number);
 709 |         }
 710 |         $this->caches[self::CACHE_KEY_SELECTOR][$selectorKey] = $precedence;
 711 | 
 712 |         return $precedence;
 713 |     }
 714 | 
 715 |     /**
 716 |      * Copies $cssRule into the style attribute of $node.
 717 |      *
 718 |      * Note: This method does not check whether $cssRule matches $node.
 719 |      *
 720 |      * @param \DOMElement $node
 721 |      * @param array{
 722 |      *            media: string,
 723 |      *            selector: string,
 724 |      *            hasUnmatchablePseudo: bool,
 725 |      *            declarationsBlock: string,
 726 |      *            line: int
 727 |      *        } $cssRule
 728 |      */
 729 |     private function copyInlinableCssToStyleAttribute(\DOMElement $node, array $cssRule): void
 730 |     {
 731 |         $declarationsBlock = $cssRule['declarationsBlock'];
 732 |         $newStyleDeclarations = $this->parseCssDeclarationsBlock($declarationsBlock);
 733 |         if ($newStyleDeclarations === []) {
 734 |             return;
 735 |         }
 736 | 
 737 |         // if it has a style attribute, get it, process it, and append (overwrite) new stuff
 738 |         if ($node->hasAttribute('style')) {
 739 |             // break it up into an associative array
 740 |             $oldStyleDeclarations = $this->parseCssDeclarationsBlock($node->getAttribute('style'));
 741 |         } else {
 742 |             $oldStyleDeclarations = [];
 743 |         }
 744 |         $node->setAttribute(
 745 |             'style',
 746 |             $this->generateStyleStringFromDeclarationsArrays($oldStyleDeclarations, $newStyleDeclarations)
 747 |         );
 748 |     }
 749 | 
 750 |     /**
 751 |      * This method merges old or existing name/value array with new name/value array
 752 |      * and then generates a string of the combined style suitable for placing inline.
 753 |      * This becomes the single point for CSS string generation allowing for consistent
 754 |      * CSS output no matter where the CSS originally came from.
 755 |      *
 756 |      * @param array<string, string> $oldStyles
 757 |      * @param array<string, string> $newStyles
 758 |      *
 759 |      * @return string
 760 |      */
 761 |     private function generateStyleStringFromDeclarationsArrays(array $oldStyles, array $newStyles): string
 762 |     {
 763 |         $cacheKey = \serialize([$oldStyles, $newStyles]);
 764 |         if (isset($this->caches[self::CACHE_KEY_COMBINED_STYLES][$cacheKey])) {
 765 |             return $this->caches[self::CACHE_KEY_COMBINED_STYLES][$cacheKey];
 766 |         }
 767 | 
 768 |         // Unset the overridden styles to preserve order, important if shorthand and individual properties are mixed
 769 |         foreach ($oldStyles as $attributeName => $attributeValue) {
 770 |             if (!isset($newStyles[$attributeName])) {
 771 |                 continue;
 772 |             }
 773 | 
 774 |             $newAttributeValue = $newStyles[$attributeName];
 775 |             if (
 776 |                 $this->attributeValueIsImportant($attributeValue)
 777 |                 && !$this->attributeValueIsImportant($newAttributeValue)
 778 |             ) {
 779 |                 unset($newStyles[$attributeName]);
 780 |             } else {
 781 |                 unset($oldStyles[$attributeName]);
 782 |             }
 783 |         }
 784 | 
 785 |         $combinedStyles = \array_merge($oldStyles, $newStyles);
 786 | 
 787 |         $style = '';
 788 |         foreach ($combinedStyles as $attributeName => $attributeValue) {
 789 |             $style .= \strtolower(\trim($attributeName)) . ': ' . \trim($attributeValue) . '; ';
 790 |         }
 791 |         $trimmedStyle = \rtrim($style);
 792 | 
 793 |         $this->caches[self::CACHE_KEY_COMBINED_STYLES][$cacheKey] = $trimmedStyle;
 794 | 
 795 |         return $trimmedStyle;
 796 |     }
 797 | 
 798 |     /**
 799 |      * Checks whether $attributeValue is marked as !important.
 800 |      *
 801 |      * @param string $attributeValue
 802 |      *
 803 |      * @return bool
 804 |      */
 805 |     private function attributeValueIsImportant(string $attributeValue): bool
 806 |     {
 807 |         return (bool)\preg_match('/!\\s*+important$/i', $attributeValue);
 808 |     }
 809 | 
 810 |     /**
 811 |      * Merges styles from styles attributes and style nodes and applies them to the attribute nodes
 812 |      */
 813 |     private function fillStyleAttributesWithMergedStyles(): void
 814 |     {
 815 |         foreach ($this->styleAttributesForNodes as $nodePath => $styleAttributesForNode) {
 816 |             $node = $this->visitedNodes[$nodePath];
 817 |             $currentStyleAttributes = $this->parseCssDeclarationsBlock($node->getAttribute('style'));
 818 |             $node->setAttribute(
 819 |                 'style',
 820 |                 $this->generateStyleStringFromDeclarationsArrays(
 821 |                     $currentStyleAttributes,
 822 |                     $styleAttributesForNode
 823 |                 )
 824 |             );
 825 |         }
 826 |     }
 827 | 
 828 |     /**
 829 |      * Searches for all nodes with a style attribute and removes the "!important" annotations out of
 830 |      * the inline style declarations, eventually by rearranging declarations.
 831 |      *
 832 |      * @throws \RuntimeException
 833 |      */
 834 |     private function removeImportantAnnotationFromAllInlineStyles(): void
 835 |     {
 836 |         /** @var \DOMElement $node */
 837 |         foreach ($this->getAllNodesWithStyleAttribute() as $node) {
 838 |             $this->removeImportantAnnotationFromNodeInlineStyle($node);
 839 |         }
 840 |     }
 841 | 
 842 |     /**
 843 |      * Removes the "!important" annotations out of the inline style declarations,
 844 |      * eventually by rearranging declarations.
 845 |      * Rearranging needed when !important shorthand properties are followed by some of their
 846 |      * not !important expanded-version properties.
 847 |      * For example "font: 12px serif !important; font-size: 13px;" must be reordered
 848 |      * to "font-size: 13px; font: 12px serif;" in order to remain correct.
 849 |      *
 850 |      * @param \DOMElement $node
 851 |      *
 852 |      * @throws \RuntimeException
 853 |      */
 854 |     private function removeImportantAnnotationFromNodeInlineStyle(\DOMElement $node): void
 855 |     {
 856 |         $inlineStyleDeclarations = $this->parseCssDeclarationsBlock($node->getAttribute('style'));
 857 |         /** @var array<string, string> $regularStyleDeclarations */
 858 |         $regularStyleDeclarations = [];
 859 |         /** @var array<string, string> $importantStyleDeclarations */
 860 |         $importantStyleDeclarations = [];
 861 |         foreach ($inlineStyleDeclarations as $property => $value) {
 862 |             if ($this->attributeValueIsImportant($value)) {
 863 |                 $importantStyleDeclarations[$property] = $this->pregReplace('/\\s*+!\\s*+important$/i', '', $value);
 864 |             } else {
 865 |                 $regularStyleDeclarations[$property] = $value;
 866 |             }
 867 |         }
 868 |         $inlineStyleDeclarationsInNewOrder = \array_merge($regularStyleDeclarations, $importantStyleDeclarations);
 869 |         $node->setAttribute(
 870 |             'style',
 871 |             $this->generateStyleStringFromSingleDeclarationsArray($inlineStyleDeclarationsInNewOrder)
 872 |         );
 873 |     }
 874 | 
 875 |     /**
 876 |      * Generates a CSS style string suitable to be used inline from the $styleDeclarations property => value array.
 877 |      *
 878 |      * @param array<string, string> $styleDeclarations
 879 |      *
 880 |      * @return string
 881 |      */
 882 |     private function generateStyleStringFromSingleDeclarationsArray(array $styleDeclarations): string
 883 |     {
 884 |         return $this->generateStyleStringFromDeclarationsArrays([], $styleDeclarations);
 885 |     }
 886 | 
 887 |     /**
 888 |      * Determines which of `$cssRules` actually apply to `$this->domDocument`, and sets them in
 889 |      * `$this->matchingUninlinableCssRules`.
 890 |      *
 891 |      * @param array<array-key, array{
 892 |      *            media: string,
 893 |      *            selector: string,
 894 |      *            hasUnmatchablePseudo: bool,
 895 |      *            declarationsBlock: string,
 896 |      *            line: int
 897 |      *        }> $cssRules
 898 |      *        the "uninlinable" array of CSS rules returned by `collateCssRules`
 899 |      */
 900 |     private function determineMatchingUninlinableCssRules(array $cssRules): void
 901 |     {
 902 |         $this->matchingUninlinableCssRules = \array_filter(
 903 |             $cssRules,
 904 |             function (array $cssRule): bool {
 905 |                 return $this->existsMatchForSelectorInCssRule($cssRule);
 906 |             }
 907 |         );
 908 |     }
 909 | 
 910 |     /**
 911 |      * Checks whether there is at least one matching element for the CSS selector contained in the `selector` element
 912 |      * of the provided CSS rule.
 913 |      *
 914 |      * Any dynamic pseudo-classes will be assumed to apply. If the selector matches a pseudo-element,
 915 |      * it will test for a match with its originating element.
 916 |      *
 917 |      * @param array{
 918 |      *            media: string,
 919 |      *            selector: string,
 920 |      *            hasUnmatchablePseudo: bool,
 921 |      *            declarationsBlock: string,
 922 |      *            line: int
 923 |      *        } $cssRule
 924 |      *
 925 |      * @return bool
 926 |      *
 927 |      * @throws ParseException
 928 |      */
 929 |     private function existsMatchForSelectorInCssRule(array $cssRule): bool
 930 |     {
 931 |         $selector = $cssRule['selector'];
 932 |         if ($cssRule['hasUnmatchablePseudo']) {
 933 |             $selector = $this->removeUnmatchablePseudoComponents($selector);
 934 |         }
 935 |         return $this->existsMatchForCssSelector($selector);
 936 |     }
 937 | 
 938 |     /**
 939 |      * Checks whether there is at least one matching element for $cssSelector.
 940 |      * When not in debug mode, it returns true also for invalid selectors (because they may be valid,
 941 |      * just not implemented/recognized yet by Emogrifier).
 942 |      *
 943 |      * @param string $cssSelector
 944 |      *
 945 |      * @return bool
 946 |      *
 947 |      * @throws ParseException
 948 |      */
 949 |     private function existsMatchForCssSelector(string $cssSelector): bool
 950 |     {
 951 |         try {
 952 |             $nodesMatchingSelector = $this->getXPath()->query($this->getCssSelectorConverter()->toXPath($cssSelector));
 953 |         } catch (ParseException $e) {
 954 |             if ($this->debug) {
 955 |                 throw $e;
 956 |             }
 957 |             return true;
 958 |         }
 959 | 
 960 |         return $nodesMatchingSelector !== false && $nodesMatchingSelector->length !== 0;
 961 |     }
 962 | 
 963 |     /**
 964 |      * Removes pseudo-elements and dynamic pseudo-classes from a CSS selector, replacing them with "*" if necessary.
 965 |      * If such a pseudo-component is within the argument of `:not`, the entire `:not` component is removed or replaced.
 966 |      *
 967 |      * @param string $selector
 968 |      *
 969 |      * @return string
 970 |      *         selector which will match the relevant DOM elements if the pseudo-classes are assumed to apply, or in the
 971 |      *         case of pseudo-elements will match their originating element
 972 |      */
 973 |     private function removeUnmatchablePseudoComponents(string $selector): string
 974 |     {
 975 |         // The regex allows nested brackets via `(?2)`.
 976 |         // A space is temporarily prepended because the callback can't determine if the match was at the very start.
 977 |         $selectorWithoutNots = \ltrim(\preg_replace_callback(
 978 |             '/([\\s>+~]?+):not(\\([^()]*+(?:(?2)[^()]*+)*+\\))/i',
 979 |             /** @param array<int, string> $matches */
 980 |             function (array $matches): string {
 981 |                 return $this->replaceUnmatchableNotComponent($matches);
 982 |             },
 983 |             ' ' . $selector
 984 |         ));
 985 | 
 986 |         $selectorWithoutUnmatchablePseudoComponents = $this->removeSelectorComponents(
 987 |             ':(?!' . self::PSEUDO_CLASS_MATCHER . '):?+[\\w\\-]++(?:\\([^\\)]*+\\))?+',
 988 |             $selectorWithoutNots
 989 |         );
 990 | 
 991 |         if (
 992 |             !\preg_match(
 993 |                 '/:(?:' . self::OF_TYPE_PSEUDO_CLASS_MATCHER . ')/i',
 994 |                 $selectorWithoutUnmatchablePseudoComponents
 995 |             )
 996 |         ) {
 997 |             return $selectorWithoutUnmatchablePseudoComponents;
 998 |         }
 999 |         return \implode('', \array_map(
1000 |             function (string $selectorPart): string {
1001 |                 return $this->removeUnsupportedOfTypePseudoClasses($selectorPart);
1002 |             },
1003 |             \preg_split(
1004 |                 '/(' . self::COMBINATOR_MATCHER . ')/',
1005 |                 $selectorWithoutUnmatchablePseudoComponents,
1006 |                 -1,
1007 |                 PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY
1008 |             )
1009 |         ));
1010 |     }
1011 | 
1012 |     /**
1013 |      * Helps `removeUnmatchablePseudoComponents()` replace or remove a selector `:not(...)` component if its argument
1014 |      * contains pseudo-elements or dynamic pseudo-classes.
1015 |      *
1016 |      * @param array<int, string> $matches array of elements matched by the regular expression
1017 |      *
1018 |      * @return string
1019 |      *         the full match if there were no unmatchable pseudo components within; otherwise, any preceding combinator
1020 |      *         followed by "*", or an empty string if there was no preceding combinator
1021 |      */
1022 |     private function replaceUnmatchableNotComponent(array $matches): string
1023 |     {
1024 |         [$notComponentWithAnyPrecedingCombinator, $anyPrecedingCombinator, $notArgumentInBrackets] = $matches;
1025 | 
1026 |         if ($this->hasUnsupportedPseudoClass($notArgumentInBrackets)) {
1027 |             return $anyPrecedingCombinator !== '' ? $anyPrecedingCombinator . '*' : '';
1028 |         }
1029 |         return $notComponentWithAnyPrecedingCombinator;
1030 |     }
1031 | 
1032 |     /**
1033 |      * Removes components from a CSS selector, replacing them with "*" if necessary.
1034 |      *
1035 |      * @param string $matcher regular expression part to match the components to remove
1036 |      * @param string $selector
1037 |      *
1038 |      * @return string
1039 |      *         selector which will match the relevant DOM elements if the removed components are assumed to apply (or in
1040 |      *         the case of pseudo-elements will match their originating element)
1041 |      */
1042 |     private function removeSelectorComponents(string $matcher, string $selector): string
1043 |     {
1044 |         return \preg_replace(
1045 |             ['/([\\s>+~]|^)' . $matcher . '/i', '/' . $matcher . '/i'],
1046 |             ['$1*', ''],
1047 |             $selector
1048 |         );
1049 |     }
1050 | 
1051 |     /**
1052 |      * Removes any `...-of-type` pseudo-classes from part of a CSS selector, if it does not have a type, replacing them
1053 |      * with "*" if necessary.
1054 |      *
1055 |      * @param string $selectorPart part of a selector which has been split up at combinators
1056 |      *
1057 |      * @return string
1058 |      *         selector part which will match the relevant DOM elements if the pseudo-classes are assumed to apply
1059 |      */
1060 |     private function removeUnsupportedOfTypePseudoClasses(string $selectorPart): string
1061 |     {
1062 |         if (!$this->selectorPartHasUnsupportedOfTypePseudoClass($selectorPart)) {
1063 |             return $selectorPart;
1064 |         }
1065 | 
1066 |         return $this->removeSelectorComponents(
1067 |             ':(?:' . self::OF_TYPE_PSEUDO_CLASS_MATCHER . ')(?:\\([^\\)]*+\\))?+',
1068 |             $selectorPart
1069 |         );
1070 |     }
1071 | 
1072 |     /**
1073 |      * Applies `$this->matchingUninlinableCssRules` to `$this->domDocument` by placing them as CSS in a `<style>`
1074 |      * element.
1075 |      * If there are no uninlinable CSS rules to copy there, a `<style>` element will be created containing only the
1076 |      * applicable at-rules from `$parsedCss`.
1077 |      * If there are none of either, an empty `<style>` element will not be created.
1078 |      *
1079 |      * @param CssDocument $parsedCss
1080 |      *        This may contain various at-rules whose content `CssInliner` does not currently attempt to inline or
1081 |      *        process in any other way, such as `@import`, `@font-face`, `@keyframes`, etc., and which should precede
1082 |      *        the processed but found-to-be-uninlinable CSS placed in the `<style>` element.
1083 |      *        Note that `CssInliner` processes `@media` rules so that they can be ordered correctly with respect to
1084 |      *        other uninlinable rules; these will not be duplicated from `$parsedCss`.
1085 |      */
1086 |     private function copyUninlinableCssToStyleNode(CssDocument $parsedCss): void
1087 |     {
1088 |         $css = $parsedCss->renderNonConditionalAtRules();
1089 | 
1090 |         // avoid including unneeded class dependency if there are no rules
1091 |         if ($this->getMatchingUninlinableCssRules() !== []) {
1092 |             $cssConcatenator = new CssConcatenator();
1093 |             foreach ($this->getMatchingUninlinableCssRules() as $cssRule) {
1094 |                 $cssConcatenator->append([$cssRule['selector']], $cssRule['declarationsBlock'], $cssRule['media']);
1095 |             }
1096 |             $css .= $cssConcatenator->getCss();
1097 |         }
1098 | 
1099 |         // avoid adding empty style element
1100 |         if ($css !== '') {
1101 |             $this->addStyleElementToDocument($css);
1102 |         }
1103 |     }
1104 | 
1105 |     /**
1106 |      * Adds a style element with $css to $this->domDocument.
1107 |      *
1108 |      * This method is protected to allow overriding.
1109 |      *
1110 |      * @see https://github.com/MyIntervals/emogrifier/issues/103
1111 |      *
1112 |      * @param string $css
1113 |      */
1114 |     protected function addStyleElementToDocument(string $css): void
1115 |     {
1116 |         $domDocument = $this->getDomDocument();
1117 |         $styleElement = $domDocument->createElement('style', $css);
1118 |         $styleAttribute = $domDocument->createAttribute('type');
1119 |         $styleAttribute->value = 'text/css';
1120 |         $styleElement->appendChild($styleAttribute);
1121 | 
1122 |         $headElement = $this->getHeadElement();
1123 |         $headElement->appendChild($styleElement);
1124 |     }
1125 | 
1126 |     /**
1127 |      * Returns the HEAD element.
1128 |      *
1129 |      * This method assumes that there always is a HEAD element.
1130 |      *
1131 |      * @return \DOMElement
1132 |      *
1133 |      * @throws \UnexpectedValueException
1134 |      */
1135 |     private function getHeadElement(): \DOMElement
1136 |     {
1137 |         $node = $this->getDomDocument()->getElementsByTagName('head')->item(0);
1138 |         if (!$node instanceof \DOMElement) {
1139 |             throw new \UnexpectedValueException('There is no HEAD element. This should never happen.', 1617923227);
1140 |         }
1141 | 
1142 |         return $node;
1143 |     }
1144 | 
1145 |     /**
1146 |      * Wraps `preg_replace`.  If an error occurs (which is highly unlikely), either it is logged and the original
1147 |      * `$subject` is returned, or in debug mode an exception is thrown.
1148 |      *
1149 |      * This method only supports strings, not arrays of strings.
1150 |      *
1151 |      * @param string $pattern
1152 |      * @param string $replacement
1153 |      * @param string $subject
1154 |      *
1155 |      * @return string
1156 |      *
1157 |      * @throws \RuntimeException
1158 |      */
1159 |     private function pregReplace(string $pattern, string $replacement, string $subject): string
1160 |     {
1161 |         $result = \preg_replace($pattern, $replacement, $subject);
1162 | 
1163 |         if (!\is_string($result)) {
1164 |             $this->logOrThrowPregLastError();
1165 |             $result = $subject;
1166 |         }
1167 | 
1168 |         return $result;
1169 |     }
1170 | 
1171 |     /**
1172 |      * Obtains the name of the error constant for `preg_last_error` (based on code posted at
1173 |      * {@see https://www.php.net/manual/en/function.preg-last-error.php#124124}) and puts it into an error message
1174 |      * which is either passed to `trigger_error` (in non-debug mode) or an exception which is thrown (in debug mode).
1175 |      *
1176 |      * @throws \RuntimeException
1177 |      */
1178 |     private function logOrThrowPregLastError(): void
1179 |     {
1180 |         $pcreConstants = \get_defined_constants(true)['pcre'];
1181 |         $pcreErrorConstantNames = \is_array($pcreConstants) ? \array_flip(\array_filter(
1182 |             $pcreConstants,
1183 |             static function (string $key): bool {
1184 |                 return \substr($key, -6) === '_ERROR';
1185 |             },
1186 |             ARRAY_FILTER_USE_KEY
1187 |         )) : [];
1188 | 
1189 |         $pregLastError = \preg_last_error();
1190 |         $message = 'PCRE regex execution error `' . (string)($pcreErrorConstantNames[$pregLastError] ?? $pregLastError)
1191 |             . '`';
1192 | 
1193 |         if ($this->debug) {
1194 |             throw new \RuntimeException($message, 1592870147);
1195 |         }
1196 |         \trigger_error($message);
1197 |     }
1198 | }
1199 | 


--------------------------------------------------------------------------------