README

关于 Zahper

Zahper 是一个 Laravel 增强版 的 Mailable，允许您使用 MJML 创建跨浏览器的精美电子邮件新闻通讯。

为什么选择 Zahper

Zahper 将解决您以下问题

• 创建电子邮件模板的挫败感，最后还要验证它们是否与浏览器兼容。
• 在没有共同的基础模板结构的情况下重新创建电子邮件模板的烦恼。
• 创建“在浏览器中查看”链接的复杂性，例如需要创建用于存储的 db/file 模型。
• 重建 Laravel 包以发送电子邮件。

Zahper 特性

您将获得所有这些功能

• 以优雅的方式在您的 Mailable 类上直接构建 MJML 模板，使用所有 MJML 特性和组件。
• 通过 MJML Api 自动将 MJML 编译为 Blade 视图。
• 缓存机制，因此您在发送 500 封电子邮件时不需要进行 500 次API调用。
• 自动生成“在浏览器中查看”链接，以防您想将用户重定向到浏览器中查看电子邮件。
• 高度可定制（存储和视图缓存、图像渲染类型等）通过配置文件。
• 自动将图像 CID / URL 渲染。
• 已经在 masteringnova.com、Laraning 和 Laraflash 中使用。
• 您还可以使用完整的原始 Mailable 类功能，因为 Zahper 继承自 Laravel 的 Mailable 类。

安装

您可以通过以下命令使用 composer 安装 Zahper

composer require brunocfalcao/zahper

该包将自动注册服务提供者（使用 auto-discover）。

下一步是发布您的 zahper.php 配置。

php artisan vendor:publish --tag=zahper-config

最后一步是在您的 .ENV 配置中安装您的 mjml.io API 密钥。

ZAHPER_API_URL=https://api.mjml.io/v1/render
ZAHPER_API_APPLICATION_ID=<your application id>
ZAHPER_API_SECRET_KEY=<your secret key>

👉 您需要在这里注册您的 MJML api 应用程序 的 API 密钥。这是免费的。

没有时间等待？

在您的 .ENV 文件中拥有 API 密钥后，只需这样做即可进行快速电子邮件演示

运行以下 artisan 命令

php artisan zahper:demo

在您的本地 Laravel 应用程序中导航到网址 /zahper/demo。 Et voilá，您应该看到一个可邮寄的演示。

工作原理

Zahper 使用 MJML 语法的力量来渲染一个跨浏览器兼容的 HTML 电子邮件。为此，您首先需要学习 MJML，相信我，它非常简单。您可以在 这里 查看文档。

此外，它还利用了 Laravel Mailable 的全部功能，您可以使用它。因此，它与任何基于 Mailable 的代码库完全兼容。

如何使用 Zahper

1. 首先，使用以下示例创建您的 zahper mailable

php artisan zahper:mailable WelcomeMailable

此命令将在 app\Mail 文件夹中创建您的新 mailable。

1. 在您的 zahper mailable 中，您有以下方法

    public function __construct()
    {
        // --- Zahper code ---
        ZahperTemplate::$cache = false;
        // [...]
        // --- /Zahper code ---
    }

$cache 静态属性将允许您缓存 MJML 编译视图，这样在您有 500 封邮件要发送的情况下，您不需要调用 MJML api 500 次。您应该在测试完您的新闻通讯后将其设置为 false，并在决定在网站上使用它时将其设置为 true。关于缓存的更多内容将在本说明文档的后面介绍。

    protected function template()
    {
        $mjml = ZahperComponent::make();

        $head = $mjml->with('mj-head');
        // $head->with(...)

        $body = $mjml->with('mj-body');
        // $body->with(...)

        return $mjml;
    }

魔法就在这里发生。您将编写您的 MJML，Zahper 将调用 MJML api 将其编译为视图。作为一个快速示例（更多示例将在本说明文档的后面介绍），以下 MJML

    <mj-section>
        <mj-column>
            <mj-text>Hi there!</mj-text>
        </mj-column>
    </mj-section>

在 Zahper 中编写如下

    $section = ZahperComponent::make('mj-section')
               ->with('mj-column')
                   ->with('mj-text', 'Hi there!');

最后的方法

    public function build()
    {
        $this
            ->from(
                'you@example.com',
                'You from Example.com'
            )
            ->subject('Nice subject out here!');

        parent::build();
    }

用于配置您的 Mailable "from" 收件人和主题。

☝️ 所有 Laravel Mailable 功能都可用于您，除了 "build" 方法。例如，您可以传递公共属性，它们也将可在 MJML 渲染视图中使用！

如何编写 MJML

编写 MJML 是以一种非常自然的方式完成的。

1. 您创建组件

    $body = ZahperComponent::make('mj-section');

1. 然后以两种方式添加所有属性，例如

    $body->align('center')
    
    or 
    
    $body = ZahperComponent::make('mj-section', ['align' => 'center');

让我们看看另一个示例，以便您更好地学习

    <mj-section padding="40px" background-color="#FFFFFF">
        <mj-column>
            <mj-text align="center" color="#1a202c" font-size="20px">Hey there!</mj-text>
        </mj-column>
    </mj-section>

编写如下

    $section = ZahperComponent::make('mj-section')
               ->padding('40px')
               ->backgroundColor('#FFFFFF')
                   ->with('mj-column')
                       ->with('mj-text', 'Hey there!')
                           ->align('center')
                           ->color('#1A202C')
                           ->fontSize('20px')

编码方式是 "自然的"。这意味着您创建组件，然后如果您想要添加子组件，您使用 ->with()，如果您想要传递属性，您只需继续将它们作为方法添加。您只需遵守属性名称约定，例如 "background-color" 应该是 ->backgroundColor()。然后就是这些了！Zahper 然后将它转换为纯 MJML，调用 MJML Api 将其转换为 blade 视图，并调用 ->build() Mailable 方法！

❓ 如果您想编写两列怎么办？

很简单。您有一个 ->parent() 方法，它将在 MJML 层次结构中向上指一级 😊

    <mj-section padding="40px" background-color="#FFFFFF">
        <mj-column>
            <mj-text>First Column</mj-text>
        </mj-column>
        <mj-column>
            <mj-text>Second Column</mj-text>
        </mj-column>
    </mj-section>

编写如下

    $section = ZahperComponent::make('mj-section')
                   ->with('mj-column')
                       ->with('mj-text', 'First Column')
                           ->parent()
                       ->parent()
                   ->with('mj-column')
                       ->with('mj-text', 'Second Column');

缓存策略

由于在发送大量邮件时，我们无法对相同的 MJML 重复调用 MJML Api，因此 Zahper 需要有一个缓存策略。否则，当出现峰值时，您可能会突然发现您的 MJML Api 账户被封锁。因此，Zahper 允许您缓存您的 blade 视图，这样当相同的 Mailable 类被调用时，它不会重新编译 mjml，而是使用缓存的视图内容。

需要注意的事项

激活 Zahper Mailable 缓存

您在生成的 Zahper Mailable 中，在 construct() 方法中打开或关闭 Mailable 缓存。

    public function __construct()
    {
        // --- Zahper code ---
        ZahperTemplate::$cache = false;
        // [...]
        // --- /Zahper code ---
    }

❗ 在您完全调整好新闻通讯结构之前请保持关闭。然后您将其打开，对于此 Mailable，MJML Api 将不会再次被调用，直到您再次打开。

在您的 Zahper Mailable 上使用动态值

假设您想在按钮的 href 属性中有一个动态 URL，每个电子邮件都有一个不同的用户 id。

    <mj-button href="{{ route('welcome', ['user_id' => $id]) }}">Click here to Browse</mj-button>

您应该这样写

    $button = ZahperComponent::make('mj-button')
                ->href("{{ route('welcome', ['user_id' => \$id]) }}")

❗ 如果您这样写，用户 id 将被缓存。因此，您将发送 500 封邮件，给 500 个收件人，他们都将有相同的用户 id！

    $button = ZahperComponent::make('mj-button')
                ->href(route('welcome', ['user_id' => \$id]))

在浏览器中查看

对于每封发送的邮件，Zahper 将在其存储文件夹中存储一个带有唯一 UUID 的副本。您只能在 Mailable 的生命周期内访问此 UUID。之后它将被丢弃并重新生成。

您可以通过以下方式在您的 mailable 中访问 UUID

    [...]
    $uuid = $this->zhp_uuid;
    [...]

您还可以在 zahper 配置文件中配置直接调用的路由和动作。

此外，您还有一个辅助工具可以为您生成完整的 URL，因此您可以在 MJML 代码中使用它。

    [...]
        ->with('mj-button', 'View in Browser')
            ->href("{{ zhp_url_view_in_browser(\$zhp_uuid) }}")
            ->target('_blank');
    [...]

退订

像在浏览器中查看一样，UUID 也用于退订。Zahper 将有一个默认路由供您使用，但动作所做的不仅仅是调用一个事件。因此，您需要注入一个监听器。

ZahpController@unsubscribe 动作

    public function unsubscribe(string $uuid)
    {
        event(new ZahperUnsubscribeEvent($uuid));

        return response('Thank you, you have been unsubscribed!', 200);
    }

当前开发状态

• 完成核心开发。
• 完成生产环境测试。
• 关闭Beta版本发布。
• 使用作业队列进行多并行测试。
• 添加测试场景。
• 面向公众发布。

贡献

目前您不需要贡献，因为Zahper还处于早期生产版本。您已经可以在您的生产网站上使用它，但仍请注意我的仓库中可能影响您的问题。

许可证

Zahper是开源软件，采用MIT许可证。

如何关注我

您可以通过twitter关注我的工作，@brunocfalcao。 :)