README

用于 v3.2 版本 Campaign Monitor API 的集成

此包允许您使用自己的资源生成模板，并将它们提交给 Campaign Monitor 作为您的通讯录内容的素材。它包含了在数据库中保存内容模板的 CRUD 实现。

从版本 2.0.0 开始，仅接受 MJML

Laravel 8 的支持已迁移到版本 3.x

文档

• 升级
• 安装
• 配置
• 资产
• 生成器
• 使用方法
• 异常
• Laravel 兼容性
• Envoyer 部署

升级

从版本 1.x 升级到版本 2.x

如果您之前使用过 LaravelCM，您需要遵循几个步骤来使您的设置与新版本的 LaravelCM 兼容。

基本布局/模板

由于 LaravelCM 现在提供了多布局解决方案，我们更新了文件命名以及目录结构。您需要将现有的模板图像和 SCSS 复制到新创建的文件中。

../storage/app/laravel-cm/layouts/base

将所有模板代码移动到 base.blade.php，所有 SCSS 移动到 base.scss。这些文件不再位于 'assets' 文件夹中。图像被复制到基本布局根目录下的 'images' 文件夹。

迁移配置

LaravelCM 2.x 提供了许多新的配置变量，您需要设置这些变量才能使一切正常工作。如果您导航到 LaravelCM 的仪表板，您会在列表中注意到新的配置选项。最好删除您当前的配置文件，从头开始重新发布它。

多布局选项的迁移

如果您计划为您的通讯录使用多个布局，您需要将一个字段 'layouts' 添加到您的通讯录模板表，以便 LaravelCM 可以跟踪此信息。

您的迁移应类似于以下内容

Schema::table('newsletter_templates', function(Blueprint $table){
    $table->string('layout')->nullable();
});

一旦该字段添加到模板模型中，您就可以运行以下安装命令来将内容移动到适当的位置，就可以正常使用了。

安装命令

LaravelCM 2.x 具有一个新的安装命令，该命令负责发布配置文件等。但是，您也可以运行此命令将现有的模板文件和布局移动到存储文件夹，以便在部署后不会丢失。

php artisan laravel-cm:install --deployment

此命令将仅从资源文件夹复制现有模板文件到存储，删除现在为空的 laravel-cm 文件夹，并设置对新创建的存储文件夹的符号链接。

从版本 2.x 升级到版本 3.x

如果您之前使用过 LaravelCM，您需要遵循几个步骤来使您的设置与新版本的 LaravelCM 兼容。

迁移配置

LaravelCM 3.x 将配置中的选项 'bootstrap' 更改为 'css_framework'，因为您现在可以在 Bootstrap4 和 TailwindCSS 之间切换。

路由外观

由于 Laravel 8 与之前版本处理路由的方式略有不同，您需要提供通过命令生成的 NewsletterTemplateController 的命名空间，如以下所述，给 CMRoutes 外观。

安装

安装包

通过执行命令将包添加到您的 composer.json。

composer require flobbos/laravel-cm

LaravelCM 具有针对 Laravel 的自动发现功能。如果这失败，只需将服务提供者添加到 app.php 文件中。

Flobbos\LaravelCM\LaravelCMServiceProvider::class,

运行安装程序

使用新的安装命令，您将指导发布所有必要的文件以及设置所有必需的目录和符号链接。

php artisan laravel-cm:install

按照逐步过程操作，或者您也可以一次性运行所有操作。有一个提示选项供您选择。

发布配置文件

这一步非常重要，因为它将NewsletterTemplate模型发布到App文件夹，这样您就可以设置自己的可填写字段以及可能需要的关联。模板生成器需要这个模型存在，否则您将收到错误。

这还将发布将用于生成新闻通讯模板的初始基本布局。

php artisan vendor:publish --tag=laravel-cm-config

生成控制器

您需要生成处理从基本布局或您生成的任何其他布局生成模板的控制器。

php artisan laravel-cm:controller NewsletterTemplateController --route=

您可以为此命令提供一个路由，但生成过程中也会询问。这个路由是所有魔法发生的地方。默认为admin.newsletter-template。

生成视图

接下来是您运行模板生成所需的视图

php artisan laravel-cm:views path.to.routes --route=

这里您需要使用之前为控制器定义的路由。默认值相同，但生成过程中也会询问。

迁移

在发布过程中，也发布了newsletter_templates表的迁移。添加所有需要的字段并运行迁移。

php artisan migrate

添加包

路由

用于LaravelCM的路由需要添加到您的路由文件中。从3.x版本开始，您需要指定由LaravelCM生成的NewsletterTemplateController的命名空间。

use App\Http\Controllers\NewsletterTemplateController;

CMRoutes::load(NewsletterTemplateController::class);

这就是加载路由所需的所有操作。

如果您想手动将路由添加到NewsletterTemplateController中，您可以简单地添加以下路由

Route::put('newsletter-template/generate-template/{id}', [NewsletterTemplateController::class, 'generateTemplate'])->name('newsletter-templates.generate-template');
Route::put('newsletter-template/update-template/{id}', [NewsletterTemplateController::class, 'updateTemplate'])->name('newsletter-templates.update-template');
Route::get('templates/{id}/send-preview', [NewsletterTemplateController::class, 'sendPreview'])->name('newsletter-templates.send-preview');
Route::resource('newsletter-templates', NewsletterTemplateController::class)

菜单项

如果您使用标准的Bootstrap4或Tailwind顶栏菜单，您可以通过下拉菜单包含所有必要的链接，如下所示

@include('laravel-cm::menu')

在您的主布局blade文件或顶栏所在位置。

Tailwind响应式菜单

自从转向Tailwind以来，默认的Laravel菜单具有响应式菜单。只需将提供的菜单包含在其余的响应式Laravel菜单所在位置即可。

@include('laravel-cm::menu-responsive')

就是这样。您可以开始了。让我们继续进行配置

配置

客户端API密钥

在此处设置您的Campaign Monitor客户端API密钥以访问API。

'client_api_key' => 'your secret key'

客户端ID

设置您的Campaign Monitor客户端ID。

'client_id' => 'your client ID'

默认列表ID

如果您在Campaign Monitor中创建了一个列表，您可以设置一个默认列表。如果没有，您可以使用API创建一个列表，稍后将其插入此处。

'default_list_id' => 'your default list ID'

基本URI

这是调用Campaign Monitor API的基本URI。这可能在未来随着他们API的新版本而改变。目前，请不要修改。

'base_uri' => 'https://api.createsend.com/api/v3.2/'

存储路径

如果您计划导入带有电子邮件地址的XLS文件，这将确定用于它的存储路径。

'storage_path' => 'xls'

URL路径

确定包的基本路由。

'url_path'=>'laravel-cm'

格式

在这里，您可以设置与API通信时使用的默认格式。目前仅支持JSON。

'format' => 'json'

确认电子邮件

默认情况下，您可以在逗号分隔列表中拥有最多5个电子邮件地址，当发送活动时，确认将发送到这些地址。

'confirmation_emails' => 'you@example.com,xyz@example.com',

订阅成功

如果您每次都使用相同的成功页面进行订阅，则可以在此处设置它，以便自动将其加载到表单中。

'subscribe_success' => 'http://example.com/success'

取消订阅成功

取消订阅成功页面也是如此。

'unsubscribe_success' => 'http://example.com/unsubscribe_success'

发件人邮箱

活动默认的发件人电子邮件。此电子邮件仍可以在表单中更改。

'from_email' => 'newsletter@example.com'

回复邮箱

活动默认的回复电子邮件。此电子邮件仍可以在表单中更改。

'reply_to' => 'replies@example.com'

布局文件

这确定了包视图将扩展的布局文件名称。

'layout_file' => 'admin'

最大测试邮件

最大预览测试电子邮件地址数。

'max_test_emails' => 5

测试邮件

默认的邮箱地址，预览邮件将发送到这里。

'test_email' => 'tester@example.com'

测试主题

预览邮件的默认主题

'test_subject' => 'Campaign Preview'

远程编译器

所有编译操作都通过远程编译器完成，该编译器对所有此包的用户免费提供。只需联系我获取有效的API密钥，即可基于MJML处理您的远程编译需求。在此设置令牌。

'api_token' => '',

CSS框架

您现在可以选择要使用的CSS框架。您可以选择使用Bootstrap4或TailwindCSS。根据您的选择，LaravelCM将自动加载相应的视图。

//bootstrap or tailwind
'css_framework' => 'tailwind',

资产

命名规范

提供了一个默认布局文件供您使用。根据您的需求，可以生成额外的布局文件。文件夹结构简单，如下所示

/resources
    /defaults
        /base
            base.blade.php
            base.scss

此文件夹将被复制到您的资源文件夹中，您应将默认布局设计放入这些文件中。您还可以添加一个图像文件夹，该文件夹在生成新模板时也将被复制。

默认布局应仅包含您的基布局。后续更改应针对特定新闻邮件模板生成的文件进行。

生成器

控制器生成器

使用此命令，您可以为获取内容并生成用于活动的模板生成一个模板控制器。

第一个参数是控制器名称。路由参数告诉生成器默认视图/控制器的路由位置，而视图参数告诉控制器视图路径。

php artisan laravel-cm:controller NewsletterController --route=admin.newsletter-template --views=laravel-cm.templates

视图生成器

此命令生成用于制作活动模板所需的视图。

第一个参数是视图应存在的路径。应与控制器命令中给出的路径相匹配。

php artisan laravel-cm:views /view/path --route=laravel-cm.templates

布局生成器

您可以通过简单地使用以下命令生成一个新的布局。这将为您生成一个新的空白布局文件以进行编辑。

php artisan laravel-cm:layout name-of-layout

使用方法

仪表板

仪表板包含您的配置设置概述以及如何使用此包的简要文档。

活动

活动概述显示您通过API从Campaign Monitor检索的草稿/计划/发送的活动。在这里，您可以创建/计划/预览您的活动，以及查看基本统计信息。

列表

列表部分允许您创建/编辑不同的电子邮件列表，这些列表与Campaign Monitor同步。您还可以查看有关您的列表的基本统计信息，例如订阅/取消订阅/退订。

订阅者

在这里，您可以查看您在不同列表中的所有订阅者信息。您还可以选择从XLS文件中导入大量订阅者。格式应该是

EmailAddress    Name

如果订阅者已经确认并导入到双重确认列表中，他们都将收到一封确认邮件，他们基本上需要重新订阅。

您还可以手动取消用户订阅以及重新订阅他们，并查看有关您的订阅者的一些基本信息。

异常

ConfigKeyNotSetException

如果配置文件中缺少配置密钥，但需要执行特定的API调用，则会抛出此异常。

TemplateNotFoundException

当您尝试使用不存在的模板时，会发生此异常。

Laravel 兼容性

不支持Laravel的早期版本。

Envoyer 部署

如果您正在使用Envoyer或其他类似工具部署代码，有解决方案可以保留现有的模板和编译好的新闻邮件。在部署期间，您只需运行以下命令

php artisan laravel-cm:install --deployment

这将运行一个函数，将所有现有内容移动到新安装中，并处理为一切正常工作所需的必要符号链接的重建。