sgalinski/sg-mail

邮件模板服务

维护者

详细信息

gitlab.sgalinski.de/typo3/sg_mail.git

主页

安装: 171

依赖: 1

建议者: 0

安全: 0

类型:typo3-cms-extension

9.1.10 2024-08-23 12:14 UTC

Requires

Replaces

  • sgalinski/sg_mail: 9.1.10

GPL-2.0-or-later f2adb5edd02d621dee79f76a37b10633993c150b

This package is not auto-updated.

Last update: 2024-09-16 18:50:31 UTC

README

许可证: GNU GPL, Version 2

仓库: https://gitlab.sgalinski.de/typo3/sg_mail

请在此处报告错误: https://gitlab.sgalinski.de/typo3/sg_mail

关于

本扩展为所有TYPO3扩展提供邮件模板服务和邮件队列功能。它还支持多种语言的模板，这些模板可以在后台进行管理。

此外，sg_mail还提供多项功能，有助于与ext:form集成。

sg_mail支持多站点和多语言。

使用方法

注册您的扩展

要将扩展与sg_mail注册，您需要为每个要集成的模板创建一个配置文件。它需要是一个.php文件，并必须位于扩展的配置文件夹typo3conf/ext/{your_extension}/Configuration/Sgmail中。

此外，您需要在您的ext_localconf.php文件中使您的注册文件知名

// register mail templates
$GLOBALS['sg_mail']['my_extension_key']['unique_template_name'] = 'EXT:my_extension_key/Configuration/SgMail/MyTemplate.php';

sg_mail将自动解析TYPO3实例中所有扩展的有效配置文件。

在文件中，您可以定义必选和可选设置

必选

  • extension_key：需要将此模板与适当的扩展关联
  • template_key：您模板的唯一标识符
  • description：对您模板使用情况的简短描述，显示在后台模板编辑器中。这应该是一个语言标签
  • subject：此模板使用的默认邮件主题。您也可以在此提供语言标签

  • markers：一组占位符变量。将动态替换为适当的值。如果您不想有任何标记，请提供一个空数组。

    标记需要按以下结构组织

    • marker：您模板中使用的变量名称。
    • type：您可以使用\SGalinski\SgMail\Service\MailTemplateService类中的一个常量来指定变量类型。
    • value：此标记的示例值。也用于在后台模块中预览您的邮件。
    • description：描述此标记用途的简短文本。

可选

  • template_path：您可以使用此设置提供与默认路径不同的邮件模板路径。

模板文件夹

如果您的配置文件中没有覆盖，则您扩展的模板的默认位置为ext/sg_example/Resources/Private/Templates/SgMail/{TemplateNameInUpperCamelCase}。在此文件夹中，您需要一个文件夹来注册每个模板。模板文件的名称本身应该是template.html

示例

您的模板“confirm_mail”的配置文件应位于../Configuration/ConfirmMail.php。

一个可能的ConfirmMail.php文件可能如下所示

return [
    'extension_key' => 'sg_example',
    'template_key' => 'confirm_mail',
    'description' => 'LLL:EXT:sg_example/Resources/Private/Language/locallang.xlf:mail.confirm.description',
    'subject' => 'LLL:EXT:sg_example/Resources/Private/Language/locallang.xlf:mail.confirm.subject',
    'markers' => [
        [
            'marker' => 'username',
            'type' => \SGalinski\SgMail\Service\MailTemplateService::MARKER_TYPE_STRING,
            'value' => 'max.mustermann@example.org',
            'description' => 'LLL:EXT:sg_energieportal/Resources/Private/Language/locallang.xlf:mail.marker.username'
        ],
        //... more markers
    ]
];

template.html文件的默认路径：ext/sg_example/Resources/Private/Templates/SgMail/ConfirmMail

使用MailTemplateService发送邮件

基本用法

  1. 获取MailTemplateService实例
  2. 在构造函数中提供template_name、extension_key和标记数组
  3. 设置或覆盖所有所需的字段（例如：setLanguage、setToAddresses、setTemplateName、setExtensionKey等）
  4. 调用sendEmail函数

示例

// get an instance of the service
/** @var MailTemplateService $mailService */
$mailService = GeneralUtility::makeInstance(MailTemplateService::class, 'confirm_mail', 'sg_example', ['username' => $username]);

$mailService->setFromName($this->settings['fromName']);
$mailService->setFromAddress($this->settings['fromEmail']);
$mailService->setToAddresses([$emailAddress]);
$mailService->setIgnoreMailQueue(TRUE);

// set the pageId of the rootpage, otherwise the templates could be duplicated (mandatory since version 4.0!!!)
$site = GeneralUtility::makeInstance(SiteFinder::class)->getSiteByPageId($GLOBALS['TSFE']->id);
$mailService->setPid($site->getRootPageId());

// set the proper language for the mail (not necessary if you want the default language)
$mailService->setSiteLanguage(GeneralUtility::makeInstance(SiteFinder::class)->getSiteByPageId(123)->getLanguageById(0));

// finally send the mail
$success = $mailService->sendEmail();
if (!$success) {
    // the mail sending failed
}

邮件队列

邮件队列包含所有已发送或将来应发送的邮件。您可以在后台模块中查看邮件队列并与条目交互。

您可以使用SGalinski\SgMail\Domain\Model\Mail类的常量来设置邮件的优先级（通过服务的setPriority函数）。使用ignoreMailQueue标志，您可以在将邮件排队（false）或立即发送（true）之间切换。

  • PRIORITY_LOWEST
  • PRIORITY_LOW
  • PRIORITY_MEDIUM
  • PRIORITY_HIGH
  • PRIORITY_HIGHEST

优先级越高，邮件越有可能立即发送（取决于邮件队列的“繁忙”程度）。

命令控制器

要启用邮件队列功能，您需要配置SendMailCommandController。

转到TYPO3后端的调度模块，设置计划的任务。选择SgMail SendMail:runSendMail命令控制器命令，并提供每秒或cron格式的频率。

有关TYPO3调度扩展的更多信息，请参阅其手册。

语言处理

当使用MailTemplateService API时，您需要通过设置setSiteLanguage或从具有已设置SiteLanguage的Template实例加载值来向API提供SiteLanguage的实例。

在您的模板编辑器中，您将自动显示页面的所有语言。

示例

finishers {
    1 {
        class = SGalinski\SgMail\Service\FormhandlerFinisherService
        config {
            checkBinaryCrLf = message
            template_key = your_template
            extension_key = extension_key
            to_address = admin@sgalinski.de
            from_address = info@sgalinski.de
            from_name = sgalinski.de
            ignore_mail_queue = TRUE
        }
    }
}

后端模块

此扩展会在您的TYPO3后端的“WEB”部分添加一个新的模块。

点击它将加载所有邮件模板和邮件队列的管理面板。

该模块提供两种模式

在模板编辑器模式下，您可以看到所选模板的所有模板占位符的概述。在这里，您可以编辑和重置您在TYPO3实例的所有语言中的模板。此外，您可以通过输入电子邮件地址并点击发送测试邮件来测试您的邮件。

在邮件队列模式下，您可以看到当前邮件队列的内容。对于每个队列条目，您有以下选项

编辑
启用/禁用
删除
显示更多信息
显示历史记录
.... 展开/折叠选项菜单
再次发送邮件（如果已经发送）
发送此邮件（如果尚未发送）
查看此邮件的内容

此外，您现在可以过滤邮件队列或将它导出为csv文件。

黑名单模板

您可以选择排除所有或特定域的某些模板。被排除的模板不会在后台模块中显示，并且它们的邮件永远不会发送。这些模板的邮件仍然会被记录，并且您可以在后台模块中搜索它们。

排除所有域的模板黑名单

在扩展配置设置 general.excludeTemplatesAllDomains 中，您可以指定哪些模板应该对所有域名进行排除，使用逗号分隔的列表。

示例

sg_comments.approved, sg_comments.declined

扩展 sg_comments 的“批准”和“拒绝”模板在所有域名中被列入黑名单。

为特定域名列入黑名单的模板

在扩展配置设置 general.excludeTemplates 中，您可以指定哪些模板应该排除哪些域名，使用分号分隔的逗号分隔列表。

逗号分隔的列表包含页面 ID 和要排除的模板。

示例

1, sg_comments.approved, sg_example.welcome;10, sg_comments.declined

扩展 sg_comments 的“批准”模板和扩展 sg_example 的“欢迎”模板被列入 ID 为 1 的页面的黑名单。

扩展 sg_comments 的“拒绝”模板被列入 ID 为 10 的页面的黑名单。

如果页面 ID 缺失或与网站根不匹配，则配置没有任何效果。

搜索来自列入黑名单模板的电子邮件

在“队列”模块模式下，您可以根据“黑名单”邮件进行筛选。注意：您不应选择模板筛选器以查看列入黑名单的邮件。

开发者指南

数据库和模型

此扩展使用两个数据库表

  • tx_sgmail_domain_model_template：存储通过后端模块提供的所有模板设置。默认设置仅存在于注册数组中，而不在数据库中。

  • tx_sgmail_domain_model_mail：此表包含所有在邮件队列中的邮件。当它们被发送时，将 sent 标志设置为 true，并插入 sending_time。您可以使用后端模块检查邮件队列。如果电子邮件应该忽略邮件队列，它仍然以 sent 标志设置为 true 的形式插入此表。邮件有一个与之关联的状态。如果邮件提交失败，状态将被设置为错误，并将错误消息保存到 error_message 字段中，以便您可以逐个检查邮件。

这些表的 extbase 模型类位于 Domain\Model 文件夹中。

服务类

MailTemplateService

此类为您提供了对邮件功能以及有关您模板的各种辅助函数的 API。

以下是一些重要函数的概述

function getDefaultTemplateMarker

从您的 locallang.xlf 中读取自定义示例模板标记。如果您需要在后端标记中需要多语言示例，这很有用。

function sendEmail

根据设置发送您的邮件或将它添加到邮件队列中。您可以使用布尔参数指定是否使用预览值。

function sendMailFromQueue

从队列中强制发送一封电子邮件。如果它已经发送，它将再次发送。

function sendMailsFromQueue

与 sendMailFromQueue 相同，但此方法接受一个 Mail 实例数组，而不是一个 Mail 的 uid。

function addFileResourceAttachment

您可以将文件资源附加到将通过标记数组发送的邮件。

function addMailToMailQueue

将构建的当前邮件添加到邮件队列中。

functions setX

将各种变量设置为提供的值。使用这些函数，您可以覆盖例如 from/cc/bcc 地址、from 名称等。

您还可以告诉 MailTemplateService 在将其添加到邮件队列时不忽略此邮件：function setIgnoreMailQueue。

Ext:form 集成

模板标记

此扩展为您提供自定义表单输入字段标识符的可能性。这些标识符在邮件模板中用作标记名称。要更改字段的标识符，请在表单编辑器中选择它，并在标有“邮件模板标记名称”的字段中输入您希望使用的标识符。保存表单后，更改的标识符名称将被覆盖。

新的邮件结束器

sg_mail为您的表单带来了两个新的结束器，以下是对sg_mail集成的设置：

  • 模板键：如果此字段为空，将在保存表单定义后自动生成一个唯一的模板名称并自动插入到字段中。生成的模板名称基于表单标识符，与结束器标识符（通过-分隔）连接。
  • 自动注册：将自动创建sg_mail注册。有关更多信息，请参阅自动注册部分。
  • 忽略邮件队列：邮件将立即发送，而不是添加到邮件队列。

自动注册

如果您选择自动使用sg_mail注册表单，将使用默认的HTML模板。

您可以通过在setup.ts中自定义TypoScript设置来控制自动生成的注册文件。

# extension where automatic generated registrations are put. Will be appended with /Configuration/MailTemplates/. Make sure these folders exist!
configurationLocation = your_extension_key

# default html template file, which serves as a fallback for all mail templates
defaultHtmlTemplate = EXT:project_theme/Configuration/MailTemplates/Default.html

事件

  • BeforeSendingFormsMailEvent：包含可变的邮件模板和提交表单的上下文。

如何监听事件（例如，BeforeSendingFormsMailEvent）

在您的扩展的Services.yaml中注册监听器

services:
  SGalinski\SomeExtension\EventListener\MyListener:
    tags:
      - name: event.listener
        identifier: 'myListener'
        event: SGalinski\SgMail\Events\BeforeSendingFormsMailEvent

创建您的监听器类

namespace SGalinski\SomeExtension\EventListener;
use SGalinski\SgMail\Events\BeforeSendingFormsMailEvent;

class MyListener
{
    public function __invoke(BeforeSendingFormsMailEvent $event): void
    {
        /** Logic goes here **/
    }
}

TypoScriptSettingsService

此服务使您能够在控制器类外部访问您的TypoScript设置。您只需提供您的页面ID和扩展密钥。如果您没有特定的页面ID设置，请将页面ID设置为0。