README

A Charcoal 服务，用于简单的电子邮件模板预设。

目录

• 安装
  • 依赖项
• 服务提供商
  • 参数
  • 服务
• 配置
• 使用方法
• 开发
  • API 文档
  • 开发依赖项
  • 编码风格
• 致谢
• 许可证

安装

首选（且唯一支持）的方法是使用 Composer

$ composer require locomotivemtl/charcoal-contrib-communicator

依赖项

必需

• PHP 5.6+: 推荐使用 PHP 7。
• locomotivemtl/charcoal-email: ^0.3

服务提供商

服务

• communicator: Charcoal\Communicator\Communicator 的实例。

配置

Communicator 使用 场景（如查询确认）分组到 频道（如用户或管理员）。这些可以从应用程序配置集中定义

{
    "communicator": {
        "user": {
            "contact": {
                "log": true,
                "campaign": "",
                "subject": "Contact Us Confirmation",
                "template_ident": "communicator/email/default",
                "template_data": {
                    "message": "Thank you {{ form_data.full_name }} for your interest in our company! We received your request for information and will contact you as soon as we can."
                }
            }
        },
        "admin": {
            "contact": {
                "log": true,
                "campaign": "",
                "subject": "Contact Us Notification",
                "template_ident": "communicator/email/default",
                "template_data": {
                    "title": "New Contact form submission from {{ form_data.full_name }}",
                    "message": "{{ form_data.full_name }} would like information concerning {{ form_data.category }}.",
                    "charcoal": "<a href=\"{{ template_data.charcoal_url }}\"><b>See the entry on Charcoal<b></a>"
                }
            }
        }
    }
}

查看 communicator.sample.json 以获取详细示例。

使用方法

Communicator 可以根据所选场景、频道和任何自定义数据准备和发送电子邮件

/**
 * @var \Charcoal\Communicator\Communicator $communicator
 * @var \App\Model\Contact\Entry            $entry
 */

$formData = [
    'full_name'     => $entry['full_name'],
    'business_name' => $entry['business_name'],
    'email_address' => $entry['email_address'],
    'category'      => transform($entry['category_id'], function ($categoryId) {
        // Fetch name of Category object from Category ID.
    }),
    'message'       => $entry['message'],
];

$communicator->setFormData($formData);

$communicator->setTo([
    'email' => $entry['email_address'],
    'name'  => $entry['full_name'],
]);

$emailData = [
    'template_data' => [
        'entry'        => $formData,
        'charcoal_url' => build_admin_url('object/edit', [
            'obj_type' => Entry::objType(),
            'obj_id'   => $entry['id'],
        ]),
    ],
];

/** @var bool */
$sent = $communicator->send('contact', 'user', $emailData);

默认情况下，Communicator 将使用应用程序配置集中 email.default_from 的电子邮件地址。

开发

要安装开发环境

$ composer install

要运行脚本（phplint、phpcs 和 phpunit）

$ composer test

API 文档

• 自动生成的 phpDocumentor API 文档可在以下位置找到
  https://locomotivemtl.github.io/charcoal-contrib-communicator/docs/master/
• 自动生成的 apigen API 文档可在以下位置找到
  https://codedoc.pub/locomotivemtl/charcoal-contrib-communicator/master/

开发依赖项

• php-coveralls/php-coveralls
• phpunit/phpunit
• squizlabs/php_codesniffer

编码风格

charcoal-contrib-communicator 模块遵循 Charcoal 编码风格

• PSR-1
• PSR-2
• PSR-4，因此自动加载由 Composer 提供。
• phpDocumentor 注释。
• phpcs.xml.dist 和 .editorconfig 用于编码标准。

可以使用 composer phpcs 执行编码风格验证/强制执行。还可以使用 composer phpcbf 使用自动修复器。

致谢

• Locomotive

许可证

Charcoal 依照 MIT 许可证授权。有关详细信息，请参阅 LICENSE。