diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b6800a3..938e2b51 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,9 +3,20 @@ All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](https://semver.org/). - ## x.y.z +### Added + +### Changed + +### Deprecated + +### Removed + +### Fixed + +## 2.1.0 + ### Added - PHP 7.3 support ([#638](https://github.com/MyIntervals/emogrifier/pull/638)) @@ -37,6 +48,8 @@ This project adheres to [Semantic Versioning](https://semver.org/). ([#476](https://github.com/jjriv/emogrifier/pull/476)) ### Changed +- Mark the work-in-progress classes as `@internal` + ([#640](https://github.com/MyIntervals/emogrifier/pull/640)) - Remove the unprocessable tags from the DOM, not from the raw HTML ([#627](https://github.com/MyIntervals/emogrifier/pull/627)) - Reject empty HTML in `setHtml()` @@ -107,7 +120,6 @@ This project adheres to [Semantic Versioning](https://semver.org/). - Allow CSS property values containing newlines ([#504](https://github.com/MyIntervals/emogrifier/pull/504)) - ## 2.0.0 ### Added @@ -159,7 +171,6 @@ This project adheres to [Semantic Versioning](https://semver.org/). - Silence purposefully ignored PHP Warnings ([#400](https://github.com/MyIntervals/emogrifier/pull/400)) - ## 1.2.0 (2017-03-02) ### Added @@ -176,7 +187,6 @@ This project adheres to [Semantic Versioning](https://semver.org/). - Ignore "auto" width and height ([#365](https://github.com/MyIntervals/emogrifier/pull/365)) - ## 1.1.0 (2016-09-18) ### Added @@ -221,7 +231,6 @@ This project adheres to [Semantic Versioning](https://semver.org/). - Second !important rule needs to overwrite the first one ([#292](https://github.com/MyIntervals/emogrifier/pull/292)) - ## 1.0.0 (2015-10-15) ### Added diff --git a/README.md b/README.md index 53989e39..eee5b79c 100644 --- a/README.md +++ b/README.md @@ -37,14 +37,12 @@ into inline style attributes in your HTML code. - [Processing HTML](#processing-html) - [Maintainers](#maintainers) - ## How it Works Emogrifier automagically transmogrifies your HTML by parsing your CSS and inserting your CSS definitions into tags within your HTML based on your CSS selectors. - ## Installation For installing emogrifier, either add pelago/emogrifier to your @@ -54,7 +52,6 @@ project's composer.json, or you can use composer as below: composer require pelago/emogrifier ``` - ## Usage First, you provide Emogrifier with the HTML and CSS you would like to merge. @@ -78,7 +75,6 @@ $emogrifier->setHtml($html); $emogrifier->setCss($css); ``` - After you have set the HTML and CSS, you can call the `emogrify` method to merge both: @@ -96,7 +92,6 @@ the complete HTML document, you can use the `emogrifyBodyContent` instead: $bodyContent = $emogrifier->emogrifyBodyContent(); ``` - ## Options There are several options that you can set on the Emogrifier object before @@ -133,7 +128,6 @@ calling the `emogrify` method: attributes set. This option will be removed in Emogrifier 3.0. Please use the `CssToAttributeConverter` class instead. - ## Installing with Composer Download the [`composer.phar`](https://getcomposer.org/composer.phar) locally @@ -146,13 +140,13 @@ curl -s https://getcomposer.org/installer | php Run the following command for a local installation: ```bash -php composer.phar require pelago/emogrifier:^2.0.0 +php composer.phar require pelago/emogrifier:^2.1.0 ``` Or for a global installation, run the following command: ```bash -composer require pelago/emogrifier:^2.0.0 +composer require pelago/emogrifier:^2.1.0 ``` You can also add follow lines to your `composer.json` and run the @@ -160,13 +154,12 @@ You can also add follow lines to your `composer.json` and run the ```json "require": { - "pelago/emogrifier": "^2.0.0" + "pelago/emogrifier": "^2.1.0" } ``` See https://getcomposer.org/ for more information and documentation. - ## Supported CSS selectors Emogrifier currently supports the following @@ -201,7 +194,6 @@ The following selectors are not implemented yet: (some of them will never be supported) * [pseudo-elements](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-elements) - ## Caveats * Emogrifier requires the HTML and the CSS to be UTF-8. Encodings like @@ -236,7 +228,6 @@ The following selectors are not implemented yet: works by converting CSS selectors to XPath selectors, and pseudo selectors cannot be converted accurately). - ## Processing HTML The Emogrifier package also provides classes for (post-)processing the HTML @@ -272,24 +263,28 @@ $converter = new \Pelago\Emogrifier\HtmlProcessor\CssToAttributeConverter($rawHt $visualHtml = $converter->convertCssToVisualAttributes()->render(); ``` +### Technology preview of new classes + +Currently, a refactoring effort is underway, aiming towards replacing the +grown-over-time `Emogrifier` class with the new `CssInliner` class and moving +additional HTML processing into separate `CssProcessor` classes (which will +inherit from `AbstractHtmlProcessor`). You can try the new classes, but be +aware that the APIs of the new classes still are subject to change. ## Steps to release a new version 1. Create a pull request "Prepare release of version x.y.z" with the following changes. -2. Set the new version number in the `@version` annotation in the class PHPDoc - of [Emogrifier.php](src/Emogrifier.php). -3. In the [composer.json](composer.json), update the `branch-alias` entry to +1. In the [composer.json](composer.json), update the `branch-alias` entry to point to the release _after_ the upcoming release. -4. In the [README.md](README.md), update the version numbers in the section +1. In the [README.md](README.md), update the version numbers in the section [Installing with Composer](#installing-with-composer). -5. In the [CHANGELOG.md](CHANGELOG.md), set the version number and remove any +1. In the [CHANGELOG.md](CHANGELOG.md), set the version number and remove any empty sections. -6. Have the pull request reviewed and merged. -7. In the [Releases tab](https://github.com/MyIntervals/emogrifier/releases), +1. Have the pull request reviewed and merged. +1. In the [Releases tab](https://github.com/MyIntervals/emogrifier/releases), create a new release and copy the change log entries to the new release. -8. Post about the new release on social media. - +1. Post about the new release on social media. ## Maintainers diff --git a/src/Emogrifier/CssInliner.php b/src/Emogrifier/CssInliner.php index 36174cea..3ad06c4d 100644 --- a/src/Emogrifier/CssInliner.php +++ b/src/Emogrifier/CssInliner.php @@ -12,6 +12,8 @@ * * For more information, please see the README.md file. * + * @internal This class currently is a new technology preview, and its API is still in flux. Don't use it in production. + * * @author Cameron Brooks * @author Jaime Prado * @author Oliver Klee diff --git a/src/Emogrifier/HtmlProcessor/AbstractHtmlProcessor.php b/src/Emogrifier/HtmlProcessor/AbstractHtmlProcessor.php index ca49d0de..cf767425 100644 --- a/src/Emogrifier/HtmlProcessor/AbstractHtmlProcessor.php +++ b/src/Emogrifier/HtmlProcessor/AbstractHtmlProcessor.php @@ -7,6 +7,8 @@ * * The "vanilla" subclass is the HtmlNormalizer. * + * @internal This class currently is a new technology preview, and its API is still in flux. Don't use it in production. + * * @author Oliver Klee */ abstract class AbstractHtmlProcessor diff --git a/src/Emogrifier/HtmlProcessor/CssToAttributeConverter.php b/src/Emogrifier/HtmlProcessor/CssToAttributeConverter.php index ff2e45c2..97a94b1c 100644 --- a/src/Emogrifier/HtmlProcessor/CssToAttributeConverter.php +++ b/src/Emogrifier/HtmlProcessor/CssToAttributeConverter.php @@ -10,6 +10,8 @@ * * To trigger the conversion, call the convertCssToVisualAttributes method. * + * @internal This class currently is a new technology preview, and its API is still in flux. Don't use it in production. + * * @author Oliver Klee */ class CssToAttributeConverter extends AbstractHtmlProcessor diff --git a/src/Emogrifier/HtmlProcessor/HtmlNormalizer.php b/src/Emogrifier/HtmlProcessor/HtmlNormalizer.php index 1406a9ff..ad3abff3 100644 --- a/src/Emogrifier/HtmlProcessor/HtmlNormalizer.php +++ b/src/Emogrifier/HtmlProcessor/HtmlNormalizer.php @@ -9,6 +9,8 @@ * - add HEAD and BODY elements (if they are missing) * - reformat the HTML * + * @internal This class currently is a new technology preview, and its API is still in flux. Don't use it in production. + * * @author Oliver Klee */ class HtmlNormalizer extends AbstractHtmlProcessor