longyi c9405dd336 vendor		hace 5 años
..
src	c9405dd336 vendor	hace 5 años
CHANGELOG.md	c9405dd336 vendor	hace 5 años
LICENSE	c9405dd336 vendor	hace 5 años
README.md	c9405dd336 vendor	hace 5 años
composer.json	c9405dd336 vendor	hace 5 años

Emogrifier

n. e•mog•ri•fi•er [\ē-'mä-grƏ-,fī-Ər] - a utility for changing completely the nature or appearance of HTML email, esp. in a particularly fantastic or bizarre manner

Emogrifier converts CSS styles into inline style attributes in your HTML code. This ensures proper display on email and mobile device readers that lack stylesheet support.

This utility was developed as part of Intervals to deal with the problems posed by certain email clients (namely Outlook 2007 and GoogleMail) when it comes to the way they handle styling contained in HTML emails. As many web developers and designers already know, certain email clients are notorious for their lack of CSS support. While attempts are being made to develop common email standards, implementation is still a ways off.

The primary problem with uncooperative email clients is that most tend to only regard inline CSS, discarding all <style> elements and links to stylesheets in <link> elements. Emogrifier solves this problem by converting CSS styles into inline style attributes in your HTML code.

How it works
Installation
Usage
Options
Installing with Composer
Supported CSS selectors
Caveats
Technology preview of new classes
Steps to release a new version
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 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. This can happen directly during instantiation:

$html = '<html><h1>Hello world!</h1></html>';
$css = 'h1 {font-size: 32px;}';
$emogrifier = new \Pelago\Emogrifier($html, $css);

You could also use the setters for providing this data after instantiation:

$emogrifier = new \Pelago\Emogrifier();

$html = '<html><h1>Hello world!</h1></html>';
$css = 'h1 {font-size: 32px;}';

$emogrifier->setHtml($html);
$emogrifier->setCss($css);

After you have set the HTML and CSS, you can call the emogrify method to merge both:

$mergedHtml = $emogrifier->emogrify();

Emogrifier automatically adds a Content-Type meta tag to set the charset for the document (if it is not provided).

If you would like to get back only the content of the BODY element instead of 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 calling the emogrify method:

$emogrifier->disableStyleBlocksParsing() - By default, Emogrifier will grab all <style> blocks in the HTML and will apply the CSS styles as inline "style" attributes to the HTML. The <style> blocks will then be removed from the HTML. If you want to disable this functionality so that Emogrifier leaves these <style> blocks in the HTML and does not parse them, you should use this option. If you use this option, the contents of the <style> blocks will not be applied as inline styles and any CSS you want Emogrifier to use must be passed in as described in the Usage section above.
$emogrifier->disableInlineStylesParsing() - By default, Emogrifier preserves all of the "style" attributes on tags in the HTML you pass to it. However if you want to discard all existing inline styles in the HTML before the CSS is applied, you should use this option.
$emogrifier->disableInvisibleNodeRemoval() - By default, Emogrifier removes elements from the DOM that have the style attribute display: none;. If you would like to keep invisible elements in the DOM, use this option. Note: This option will be removed in Emogrifier 3.0. HTML tags with display: none; then will always be retained.
$emogrifier->addAllowedMediaType(string $mediaName) - By default, Emogrifier will keep only media types all, screen and print. If you want to keep some others, you can use this method to define them.
$emogrifier->removeAllowedMediaType(string $mediaName) - You can use this method to remove media types that Emogrifier keeps.
$emogrifier->addExcludedSelector(string $selector) - Keeps elements from being affected by emogrification.
$emogrifier->enableCssToHtmlMapping() - Some email clients don't support CSS well, even if inline and prefer HTML attributes. This function allows you to put properties such as height, width, background color and font color in your CSS while the transformed content will have all the available HTML attributes set. This option will be removed in Emogrifier 3.0. Please use the CssToAttributeConverter class instead.

Installing with Composer

Download the composer.phar locally or install Composer globally:

curl -s https://getcomposer.org/installer | php

Run the following command for a local installation:

php composer.phar require pelago/emogrifier:^2.2

Or for a global installation, run the following command:

composer require pelago/emogrifier:^2.2

You can also add follow lines to your composer.json and run the composer update command:

"require": {
  "pelago/emogrifier": "^2.2"
}

See https://getcomposer.org/ for more information and documentation.

Supported CSS selectors

Emogrifier currently supports the following CSS selectors:

type
class
ID
universal:
attribute:
- presence
- exact value match
- value with ~ (one word within a whitespace-separated list of words)
- value with | (either exact value match or prefix followed by a hyphen)
- value with ^ (prefix match)
- value with $ (suffix match)
- value with * (substring match)
adjacent
child
descendant
pseudo-classes:

The following selectors are not implemented yet:

universal
case-insensitive attribute value
general sibling
pseudo-classes (some of them will never be supported)
pseudo-elements

Caveats

Emogrifier requires the HTML and the CSS to be UTF-8. Encodings like ISO8859-1 or ISO8859-15 are not supported.
Emogrifier now preserves all valuable @media queries. Media queries can be very useful in responsive email design. See media query support.
Emogrifier will grab existing inline style attributes and will grab <style> blocks from your HTML, but it will not grab CSS files referenced in elements. (The problem email clients are going to ignore these tags anyway, so why leave them in your HTML?)
Even with styles inline, certain CSS properties are ignored by certain email clients. For more information, refer to these resources:
All CSS attributes that apply to a node will be applied, even if they are redundant. For example, if you define a font attribute and a font-size attribute, both attributes will be applied to that node (in other words, the more specific attribute will not be combined into the more general attribute).
There's a good chance you might encounter problems if your HTML is not well-formed and valid (DOMDocument might complain). If you get problems like this, consider running your HTML through Tidy before you pass it to Emogrifier.
Emogrifier automatically converts the provided (X)HTML into HTML5, i.e., self-closing tags will lose their slash. To keep your HTML valid, it is recommended to use HTML5 instead of one of the XHTML variants.
Emogrifier only supports CSS1 level selectors and a few CSS2 level selectors (but not all of them). It does not support pseudo selectors. (Emogrifier works by converting CSS selectors to XPath selectors, and pseudo selectors cannot be converted accurately).

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 classes which inherit from AbstractHtmlProcessor. You can try the new classes, but be aware that the APIs of the new classes still are subject to change before version 3.0.0.

This is how to use the new CssInliner:

$visualHtml = \Pelago\Emogrifier\CssInliner::fromHtml($html)->inlineCss($css)->render();

You can also use the DOMDocument created by CssInliner to process it further:

$domDocument = \Pelago\Emogrifier\CssInliner::fromHtml($html)->inlineCss($css)->getDomDocument();
$prunedHtml = \Pelago\Emogrifier\HtmlProcessor\HtmlPruner::fromDomDocument($domDocument)
  ->removeInvisibleNodes->render();

Normalizing and cleaning up HTML

The HtmlNormalizer class normalizes the given HTML in the following ways:

add a document type (HTML5) if missing
disentangle incorrectly nested tags
add HEAD and BODY elements (if they are missing)
reformat the HTML

The class can be used like this:

$cleanHtml = \Pelago\Emogrifier\HtmlProcessor\HtmlNormalizer::fromHtml($rawHtml)->render();

Converting CSS styles to visual HTML attributes

The CssToAttributeConverter converts a few style attributes values to visual HTML attributes. This allows to get at least a bit of visual styling for email clients that do not support CSS well. For example, style="width: 100px" will be converted to width="100".