[FEATURE] Add HtmlPruner::removeRedundantClassesAfterCssInlined

CHANGELOG.md

@@ -6,6 +6,9 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 ## x.y.z
 
 ### Added
+- Add `HtmlPruner::removeRedundantClassesAfterCssInlined`
+  ([#380](https://github.com/MyIntervals/emogrifier/issues/380),
+  [#724](https://github.com/MyIntervals/emogrifier/pull/724))
 - Check on Travis that PHP-CS-Fixer will not change anything
   [#727](https://github.com/MyIntervals/emogrifier/pull/727))
 - Support `:not(…)` as an entire selector

README.md

@@ -106,8 +106,10 @@ use Pelago\Emogrifier\HtmlProcessor\HtmlPruner;
 
 …
 
-$domDocument = CssInliner::fromHtml($html)->inlineCss($css)->getDomDocument();
-HtmlPruner::fromDomDocument($domDocument)->removeElementsWithDisplayNone();
+$cssInliner = CssInliner::fromHtml($html)->inlineCss($css);
+$domDocument = $cssInliner->getDomDocument();
+HtmlPruner::fromDomDocument($domDocument)->removeElementsWithDisplayNone()
+  ->removeRedundantClassesAfterCssInlined($cssInliner);
 $finalHtml = CssToAttributeConverter::fromDomDocument($domDocument)
   ->convertCssToVisualAttributes()->render();
 ```
@@ -156,6 +158,37 @@ $visualHtml = CssToAttributeConverter::fromDomDocument($domDocument)
   ->convertCssToVisualAttributes()->render();
 ```
 
+### Removing redundant content and attributes from the HTML
+
+The `HtmlPruner` class can reduce the size of the HTML by removing elements with
+a `display: none` style declaration, and/or removing classes from `class`
+attributes that are not required.
+
+It can be used like this:
+
+```php
+use Pelago\Emogrifier\HtmlProcessor\HtmlPruner;
+
+…
+
+$prunedHtml = HtmlPruner::fromHtml($html)->removeElementsWithDisplayNone()
+  ->removeRedundantClasses($classesToKeep)->render();
+```
+
+The `removeRedundantClasses` method accepts a whitelist of names of classes that
+should be retained.  If this is a post-processing step after inlining CSS, you
+can alternatively use `removeRedundantClassesAfterCssInlined`, passing it the
+`CssInliner` instance that has inlined the CSS (and having the `HtmlPruner` work
+on the `DOMDocument`).  This will use information from the `CssInliner` to
+determine which classes are still required (namely, those used in uninlinable
+rules that have been copied to a `<style>` element):
+
+```php
+$prunedHtml = HtmlPruner::fromDomDocument($cssInliner->getDomDocument())
+  ->removeElementsWithDisplayNone()
+  ->removeRedundantClassesAfterCssInlined($cssInliner)->render();
+```
+
 ### Options
 
 There are several options that you can set on the `CssInliner` instance before

src/Emogrifier/HtmlProcessor/HtmlPruner.php

@@ -2,6 +2,7 @@
 
 namespace Pelago\Emogrifier\HtmlProcessor;
 
+use Pelago\Emogrifier\CssInliner;
 use Pelago\Emogrifier\Utilities\ArrayIntersector;
 
 /**
@@ -109,4 +110,30 @@ private function removeClassAttributeFromElements(\DOMNodeList $elements)
             $element->removeAttribute('class');
         }
     }
+
+    /**
+     * After CSS has been inlined, there will likely be some classes in `class` attributes that are no longer referenced
+     * by any remaining (uninlinable) CSS.  This method removes such classes.
+     *
+     * Note that it does not inspect the remaining CSS, but uses information readily available from the `CssInliner`
+     * instance about the CSS rules that could not be inlined.
+     *
+     * @param CssInliner $cssInliner object instance that performed the CSS inlining
+     *
+     * @return self fluent interface
+     *
+     * @throws \BadMethodCallException if `inlineCss` has not first been called on `$cssInliner`
+     */
+    public function removeRedundantClassesAfterCssInlined(CssInliner $cssInliner)
+    {
+        $classesToKeepAsKeys = [];
+        foreach ($cssInliner->getMatchingUninlinableSelectors() as $selector) {
+            \preg_match_all('/\\.(-?+[_a-zA-Z][\\w\\-]*+)/', $selector, $matches);
+            $classesToKeepAsKeys += \array_fill_keys($matches[1], true);
+        }
+
+        $this->removeRedundantClasses(\array_keys($classesToKeepAsKeys));
+
+        return $this;
+    }
 }

tests/Unit/Emogrifier/HtmlProcessor/HtmlPrunerTest.php

@@ -2,6 +2,7 @@
 
 namespace Pelago\Tests\Unit\Emogrifier\HtmlProcessor;
 
+use Pelago\Emogrifier\CssInliner;
 use Pelago\Emogrifier\HtmlProcessor\AbstractHtmlProcessor;
 use Pelago\Emogrifier\HtmlProcessor\HtmlPruner;
 use PHPUnit\Framework\TestCase;
@@ -263,9 +264,7 @@ public function removeRedundantClassesRemovesClassesNotToKeep(
         $subject->removeRedundantClasses($classesToKeep);
 
         $result = $subject->render();
-        foreach ($classesExpectedToBeRemoved as $class) {
-            self::assertNotContains($class, $result);
-        }
+        self::assertContainsNone($classesExpectedToBeRemoved, $result);
     }
 
     /**
@@ -359,6 +358,210 @@ public function removeRedundantClassesMinifiesClassAttributes($html, array $clas
         }
     }
 
+    /**
+     * Builds a `CssInliner` fixture with the given HTML in a state where the given CSS has been inlined, and an
+     * `HtmlPruner` subject sharing the same `DOMDocument`.
+     *
+     * @param string $html
+     * @param string $css
+     *
+     * @return (CssInliner|HtmlPruner)[] The `HtmlPruner` subject is the first element, and the `CssInliner` fixture is
+     *         the second element.
+     */
+    private function buildSubjectAndCssInlinerWithCssInlined($html, $css)
+    {
+        $cssInliner = CssInliner::fromHtml($html);
+        $cssInliner->inlineCss($css);
+
+        $subject = HtmlPruner::fromDomDocument($cssInliner->getDomDocument());
+
+        return [$subject, $cssInliner];
+    }
+
+    /**
+     * @test
+     */
+    public function removeRedundantClassesAfterCssInlinedProvidesFluentInterface()
+    {
+        list($subject, $cssInliner) = $this->buildSubjectAndCssInlinerWithCssInlined('<html></html>', '');
+
+        $result = $subject->removeRedundantClassesAfterCssInlined($cssInliner);
+
+        self::assertSame($subject, $result);
+    }
+
+    /**
+     * @test
+     */
+    public function removeRedundantClassesAfterCssInlinedThrowsExceptionIfInlineCssNotCalled()
+    {
+        $this->expectException(\BadMethodCallException::class);
+
+        $cssInliner = CssInliner::fromHtml('<html></html>');
+        $subject = HtmlPruner::fromDomDocument($cssInliner->getDomDocument());
+
+        $subject->removeRedundantClassesAfterCssInlined($cssInliner);
+    }
+
+    /**
+     * @return (string|string[])[][]
+     */
+    public function provideClassesNotInUninlinableRules()
+    {
+        return [
+            'inlinable rule with different class' => [
+                'HTML' => '<p class="foo">hello</p>',
+                'CSS' => '.bar { color: red; }',
+                'classes expected to be removed' => ['foo'],
+            ],
+            'uninlinable rule with different class' => [
+                'HTML' => '<p class="foo">hello</p>',
+                'CSS' => '.bar:hover { color: red; }',
+                'classes expected to be removed' => ['foo'],
+            ],
+            'inlinable rule with matching class' => [
+                'HTML' => '<p class="foo">hello</p>',
+                'CSS' => '.foo { color: red; }',
+                'classes expected to be removed' => ['foo'],
+            ],
+            '2 instances of class to be removed' => [
+                'HTML' => '<p class="foo">hello</p><p class="foo">world</p>',
+                'CSS' => '.foo { color: red; }',
+                'classes expected to be removed' => ['foo'],
+            ],
+            '2 different classes to be removed' => [
+                'HTML' => '<p class="foo">hello</p><p class="bar">world</p>',
+                'CSS' => '.foo { color: red; }',
+                'classes expected to be removed' => ['foo', 'bar'],
+            ],
+            '2 different classes, 1 in inlinable rule, 1 in uninlinable rule' => [
+                'HTML' => '<p class="foo bar">hello</p>',
+                'CSS' => '.foo { color: red; } .bar:hover { color: green; }',
+                'classes expected to be removed' => ['foo'],
+            ],
+            'class with hyphen, underscore, uppercase letter and number in name' => [
+                'HTML' => '<p class="foo-2_A">hello</p>',
+                'CSS' => '.foo-2_A { color: red; }',
+                'classes expected to be removed' => ['foo-2_A'],
+            ],
+        ];
+    }
+
+    /**
+     * @test
+     *
+     * @param string $html
+     * @param string $css
+     * @param string[] $classesExpectedToBeRemoved
+     *
+     * @dataProvider provideClassesNotInUninlinableRules
+     */
+    public function removeRedundantClassesAfterCssInlinedRemovesClassesNotInUninlinableRules(
+        $html,
+        $css,
+        array $classesExpectedToBeRemoved = []
+    ) {
+        list($subject, $cssInliner)
+            = $this->buildSubjectAndCssInlinerWithCssInlined('<html>' . $html . '</html>', $css);
+
+        $subject->removeRedundantClassesAfterCssInlined($cssInliner);
+
+        $result = $subject->render();
+        self::assertContainsNone($classesExpectedToBeRemoved, $result);
+    }
+
+    /**
+     * @return (string|string[])[][]
+     */
+    public function provideClassesInUninlinableRules()
+    {
+        return [
+            'media rule' => [
+                'HTML' => '<p class="foo">hello</p>',
+                'CSS' => '@media (max-width: 640px) { .foo { color: green; } }',
+                'classes to be kept' => ['foo'],
+            ],
+            'dynamic pseudo-class' => [
+                'HTML' => '<p class="foo">hello</p>',
+                'CSS' => '.foo:hover { color: green; }',
+                'classes to be kept' => ['foo'],
+            ],
+            '2 classes, in different uninlinable rules' => [
+                'HTML' => '<p class="foo bar">hello</p>',
+                'CSS' => '.foo:hover { color: green; } @media (max-width: 640px) { .bar { color: green; } }',
+                'classes to be kept' => ['foo', 'bar'],
+            ],
+            '1 class in uninlinable rule, 1 in inlinable rule' => [
+                'HTML' => '<p class="foo bar">hello</p>',
+                'CSS' => '.foo { color: red; } .bar:hover { color: green; }',
+                'classes to be kept' => ['bar'],
+            ],
+            '2 classes in same selector' => [
+                'HTML' => '<p class="foo bar">hello</p>',
+                'CSS' => '.foo.bar:hover { color: green; }',
+                'classes to be kept' => ['foo', 'bar'],
+            ],
+            'class with hyphen, underscore, uppercase letter and number in name' => [
+                'HTML' => '<p class="foo-2_A">hello</p>',
+                'CSS' => '.foo-2_A:hover { color: green; }',
+                'classes to be kept' => ['foo-2_A'],
+            ],
+        ];
+    }
+
+    /**
+     * @test
+     *
+     * @param string $html
+     * @param string $css
+     * @param string[] $classesToBeKept
+     *
+     * @dataProvider provideClassesInUninlinableRules
+     */
+    public function removeRedundantClassesAfterCssInlinedNotRemovesClassesInUninlinableRules(
+        $html,
+        $css,
+        array $classesToBeKept = []
+    ) {
+        list($subject, $cssInliner)
+            = $this->buildSubjectAndCssInlinerWithCssInlined('<html>' . $html . '</html>', $css);
+
+        $subject->removeRedundantClassesAfterCssInlined($cssInliner);
+
+        $result = $subject->render();
+        self::assertContainsAll($classesToBeKept, $result);
+    }
+
+    /**
+     * Asserts that none of the `$needles` can be found within the string `$haystack`.
+     *
+     * @param string[] $needles
+     * @param string $haystack
+     *
+     * @throws \PHPUnit_Framework_AssertionFailedError
+     */
+    private static function assertContainsNone(array $needles, $haystack)
+    {
+        foreach ($needles as $needle) {
+            self::assertNotContains($needle, $haystack);
+        }
+    }
+
+    /**
+     * Asserts that all of the `$needles` can be found within the string `$haystack`.
+     *
+     * @param string[] $needles
+     * @param string $haystack
+     *
+     * @throws \PHPUnit_Framework_AssertionFailedError
+     */
+    private static function assertContainsAll(array $needles, $haystack)
+    {
+        foreach ($needles as $needle) {
+            self::assertContains($needle, $haystack);
+        }
+    }
+
     /**
      * Asserts that the number of occurrences of `$needle` within the string `$haystack` is as expected.
      *