bradietilley/laravel-css-inliner

将Laravel邮件中的CSS类转换为内联样式

维护者

详情

github.com/bradietilley/laravel-css-inliner

源代码

问题

安装: 752

依赖项: 0

建议者: 0

安全: 0

星标: 2

关注者: 0

分支: 0

开放问题: 0

2.0.0 2023-06-08 11:33 UTC

Requires

Requires (Dev)

MIT b4eb2b47437de17601abb2e0020febca2b2a0b2f

This package is not auto-updated.

Last update: 2024-09-13 15:53:55 UTC

README

Static Analysis Tests

概览

此软件包利用tijsverkoyen/css-to-inline-styles将可邮寄视图中的CSS类转换为内联样式，以改善电子邮件客户端兼容性。

您可以使用此软件包的自动化功能，或者选择将其挂钩到该软件包的事件（甚至Laravel的核心事件），并手动选择要转换的内容以及相应的样式表。有关更多详细信息，请参阅用法部分。

安装

通过Composer

composer require bradietilley/laravel-css-inliner

用法

为了演示目的，我们将使用外观BradieTilley\LaravelCssInliner\Facades\CssInline，但是如果您喜欢直接使用实例（像我一样），可以将BradieTilley\LaravelCssInliner\Facades\CssInline::替换为以下任何一项

  • BradieTilley\LaravelCssInliner\Facades\CssInline:
  • BradieTilley\LaravelCssInliner\CssInliner::singleton()->
  • app(BradieTilley\LaravelCssInliner\CssInliner::class)->
  • app()->make(BradieTilley\LaravelCssInliner\CssInliner::class)->

通过PHP添加CSS

在任何时候（在HTML转换之前），您可以定义要添加到每个HTML字符串或由CSS Inliner转换的电子邮件中的CSS文件或原始CSS。一个很好的例子是一个基础样式表，所有电子邮件都应该继承。

use BradieTilley\LaravelCssInliner\Facades\CssInline;

CssInline::addCssPath(resource_path('css/email.css'));
CssInline::addCssRaw('body { background: #eee; }');

# Or, you can achieve the same outcome by letting CssInline decide whether it's a path or raw CSS:
CssInline::addCss(resource_path('css/email.css'));
CssInline::addCss('body { background: #eee; }');

手动转换

您可能希望手动转换HTML字符串或电子邮件中的某些CSS。

use BradieTilley\LaravelCssInliner\Facades\CssInline;
use Symfony\Component\Mime\Email;

CssInline::addCss('.font-bold { font-weight: bold; }');

# Convert an HTML string
$html = CssInline::convert('<html><body><div class="font-bold">Bold</div></body></html>');
echo $html; // <html><body><div class="font-bold" style="font-weight: bold;">Bold</div></body></html>

# Convert an email
$email = new Email();
$email->html('<html><body><div class="font-bold">Bold</div></body></html>');
CssInline::convertEmail($email);
echo $email->getHtmlBody(); // <html><body><div class="font-bold" style="font-weight: bold;">Bold</div></body></html>

选项：自动解析Laravel电子邮件（或不要自动解析Laravel电子邮件）

您可能希望根据条件启用或禁用CSS Inliner以处理从Laravel发送的邮件（通过Mail::send()）。为此，我们可以利用emailListener选项。默认值为true（因此将自动转换从Laravel发送的电子邮件中找到的CSS类）。

use BradieTilley\LaravelCssInliner\Facades\CssInline;

CssInline::emailListenerEnabled(); // Current state: true or false
CssInline::enableEmailListener(); // Enables option; returns instance of CssInliner
CssInline::disableEmailListener(); // Disables option; returns instance of CssInliner

选项：从给定的HTML或电子邮件中读取CSS（样式和链接元素）

您可能希望解析HTML或电子邮件中找到的<style>或<link>样式表，例如，如果您想将特定于电子邮件的CSS存储在电子邮件视图中。为此，我们可以利用cssFromHtmlContent选项。默认值为false。

use BradieTilley\LaravelCssInliner\Facades\CssInline;

CssInline::cssFromHtmlContentEnabled(); // Current state: true or false
CssInline::enableCssExtractionFromHtmlContent(); // Enables option; returns instance of CssInliner
CssInline::disableCssExtractionFromHtmlContent(); // Disables option; returns instance of CssInliner

选项：在读取CSS（如上所述）后，从HTML或电子邮件中删除原始CSS（样式和链接元素）

您可能希望在将CSS转换为内联样式后从HTML或电子邮件中删除大型的<style>或<link>样式表，以减少从您的系统发送的电子邮件的有效负载大小。为此，我们可以利用cssRemovalFromHtmlContent选项。默认值为false。

use BradieTilley\LaravelCssInliner\Facades\CssInline;

CssInline::cssRemovalFromHtmlContentEnabled(); // Current state: true or false
CssInline::enableCssRemovalFromHtmlContent(); // Enables option; returns instance of CssInliner
CssInline::disableCssRemovalFromHtmlContent(); // Disables option; returns instance of CssInliner
use BradieTilley\LaravelCssInliner\Facades\CssInline;

CssInline::doSomething();
CssInliner::addCssPath(resource_path('css/email.css'));
CssInliner::addCssRaw('.text-success { color: #00ff00; }');

# Convert your own HTML/CSS
$html = '<span class="text-success">Success text</span>';
$html = CssInliner::convert($html);

echo $html; // <span class="text-success" style="color: #00ff00;">Success text</span>

事件

CssInliner会触发四个事件 - 两个用于HTML转换，四个用于电子邮件转换。事件的调用顺序是

  • 1st: BradieTilley\LaravelCssInliner\Events\PreEmailCssInlineEvent（仅电子邮件）
  • 2nd: BradieTilley\LaravelCssInliner\Events\PreCssInlineEvent（电子邮件 + HTML）
  • 3rd: BradieTilley\LaravelCssInliner\Events\PostCssInlineEvent（电子邮件 + HTML）
  • 4th: BradieTilley\LaravelCssInliner\Events\PostEmailCssInlineEvent（仅电子邮件）

可以通过Laravel的正常方式来监听事件。例如

Event::listen(\BradieTilley\LaravelCssInliner\Events\PreEmailCssInlineEvent::class, fn () => doSomething());

或者，您可能希望使用回调方法 hook 到 CSS Inliner：beforeConvertingEmail、afterConvertingEmail、beforeConvertingHtml、afterConvertingHtml。这些方法接受一个回调，并简单地将回调作为 Event::listen() 的第二个参数，因此请将以下示例中的回调视为相应 CssInliner 事件的 Event::listen() 的第二个参数。

事件：在转换电子邮件之前（beforeConvertingEmail）

CssInliner::beforeConvertingEmail(function (PreEmailCssInlineEvent $event) {
    # You have access to the unconverted-Email and CSS Inliner instance via the event
    $event->email; // instanceof: \Symfony\Component\Mime\Email
    $event->cssInliner; // instanceof BradieTilley\LaravelCssInliner\CssInliner
    echo $event->email->getHtmlBody(); // <html>...</html>

    # Because this is a 'before' event, you may choose to halt the conversion of this *one* Email
    return $event->cssInliner->halt();
    # Laravel will halt any other event listeners; CSS Inliner will return the Email immediately (and not convert it)
});

事件：在转换HTML之前（beforeConvertingHtml）

CssInliner::beforeConvertingHtml(function (PreCssInlineEvent $event) {
    # You have access to the unconverted-HTML and CSS Inliner instance via the event
    $event->html; // string
    $event->cssInliner; // instanceof BradieTilley\LaravelCssInliner\CssInliner
    echo $event->html; // <html>...</html>

    # Because this is a 'before' event, you may choose to halt the conversion of this *one* HTML string
    return $event->cssInliner->halt();
    # Laravel will halt any other event listeners; CSS Inliner will return the HTML immediately (and not convert it) 
});

事件：在转换HTML之后（afterConvertingHtml）

CssInliner::afterConvertingHtml(function (PostCssInlineEvent $event) {
    # You have access to the converted-HTML and CSS Inliner instance via the event
    $event->html; // string
    $event->cssInliner; // instanceof BradieTilley\LaravelCssInliner\CssInliner
    echo $event->html; // <html>...</html>

    # Because this is an 'after' event, you cannot halt the conversion of the HTML string (unlike the 'before' event)
});

事件：在转换电子邮件之后（afterConvertingEmail）

CssInliner::afterConvertingEmail(function (PostEmailCssInlineEvent $event) {
    # You have access to the converted-Email and CSS Inliner instance via the event
    $event->email; // instanceof: \Symfony\Component\Mime\Email
    $event->cssInliner; // instanceof BradieTilley\LaravelCssInliner\CssInliner
    echo $event->email->getHtmlBody(); // <html>...</html>

    # Because this is an 'after' event, you cannot halt the conversion of the Email (unlike the 'before' event)
});

变更日志

请参阅变更日志获取关于最近更改的更多信息。

测试

composer test

贡献

请参阅贡献指南以获取详细信息。