typo3-powermail

TYPO3 Powermail 开发

来源：https://github.com/dirnbauer/webconsulting-skills

兼容性： 根据 Packagist，Powermail 13.x 目前面向 TYPO3 13.4——在软件包声明支持 v14 之前，不要假设它支持 v14。示例尽可能使用现代 TYPO3 API；请根据你的 Core 版本进行调整。 所有示例均使用 PHP 8.2+。

优先使用 TYPO3 API： 在创建自定义实现之前，始终优先使用 TYPO3 内置的 API、核心功能和既定约定。不要重复实现 TYPO3 已提供的功能。请务必查阅 TYPO3 官方文档，确认所用 API 和方法存在，且在 TYPO3 v14 中未被弃用。

补充资料：

• SKILL-CONDITIONS.md - 条件字段／页面可见性（powermail_cond）
• 此技能中直接介绍了用于 finisher、validator 和 condition 的 PHP 8.4 模式
• SKILL-EXAMPLES.md - 包含奥地利法律类型的多步骤商店表单、DDEV SQL + DataHandler CLI

Powermail 与 Core EXT:form

这是两个不同的系统。不要混用它们的迁移建议。

	Powermail（in2code/powermail）	TYPO3 Core EXT:form
用途	在 Powermail 后端模块中构建的邮件表单；存储在 tx_powermail_* 表中	声明式表单（通常为 YAML）、form 框架、以 YAML/PHP 定义的 finisher
渲染	Powermail 插件／ViewHelper／TypoScript	Fluid 模板 + Core 表单运行时
本技能	介绍 in2code 发布的 Powermail API、finisher、validator 和事件	仅适用于你的代码也涉及 EXT:form 的情况（桥接、共享站点、双表单栈）

v14-Only Changes 下标注为 EXT:form 的章节介绍的是 Core 表单框架的移除项（hooks → PSR-14、存储适配器）。它们适用于挂接到 EXT:form 的自定义代码，不适用于普通的纯 Powermail 项目——除非你明确集成了两者。

1. 架构概览

领域模型层级

Form (tx_powermail_domain_model_form)
 └── Page (tx_powermail_domain_model_page)
      └── Field (tx_powermail_domain_model_field)

Mail (tx_powermail_domain_model_mail)
 └── Answer (tx_powermail_domain_model_answer)
      └── references Field

插件注册

• Pi1（可缓存／不可缓存）：form、create、confirmation、optinConfirm、disclaimer
• Pi5（不可缓存）：marketing（AJAX 跟踪）

Composer

composer require in2code/powermail

典型依赖要求（请始终在 Packagist 上确认当前版本）：PHP ^8.2、typo3/cms-core: ^13.4（撰写本文时的最新稳定版本系列），以及 ext-json、ext-gd、ext-fileinfo、ext-curl。上游更新软件包约束之前，不要假设支持 TYPO3 v14。

2. 字段类型

类型	键	值类型	说明
文本	input	TEXT (0)	标准输入
多行文本	textarea	TEXT (0)	多行
选择框	select	TEXT/ARRAY (0/1)	支持多选
复选框	check	ARRAY (1)	多个值
单选框	radio	TEXT (0)	单项选择
提交按钮	submit	—	表单提交按钮
验证码	captcha	TEXT (0)	内置 CAPTCHA
重置按钮	reset	—	表单重置按钮
静态文本	text	—	仅显示
内容元素	content	—	CE 引用
HTML	html	TEXT (0)	原始 HTML
密码	password	PASSWORD (4)	哈希存储
文件上传	file	UPLOAD (3)	文件附件
隐藏字段	hidden	TEXT (0)	隐藏输入
日期	date	DATE (2)	日期选择器
国家／地区	country	TEXT (0)	国家／地区选择器
位置	location	TEXT (0)	地理位置
TypoScript	typoscript	TEXT (0)	TS 生成的内容

答案值类型

Answer::VALUE_TYPE_TEXT     = 0;  // String values
Answer::VALUE_TYPE_ARRAY    = 1;  // JSON-encoded arrays (checkboxes, multiselect)
Answer::VALUE_TYPE_DATE     = 2;  // Timestamps
Answer::VALUE_TYPE_UPLOAD   = 3;  // File references
Answer::VALUE_TYPE_PASSWORD = 4;  // Hashed passwords

3. TypoScript 配置

基本设置

plugin.tx_powermail {
    settings {
        setup {
            # Form settings
            main {
                pid = {$plugin.tx_powermail.settings.main.pid}
                form = {$plugin.tx_powermail.settings.main.form}
                confirmation = 0
                optin = 0
                morestep = 0
            }

            # Receiver mail
            receiver {
                enable = 1
                subject = Mail from {firstname} {lastname}
                body = A new mail from your website
                senderNameField = firstname
                senderEmailField = email
                # Override receiver: receiver.overwrite.email = [email protected]
                # Attach uploads: receiver.attachment = 1
                # Add CC: receiver.overwrite.cc = [email protected]
            }

            # Sender confirmation mail
            sender {
                enable = 1
                subject = Thank you for your message
                body = We received your submission
                senderName = Website
                senderEmail = [email protected]
            }

            # Double Opt-In
            optin {
                subject = Please confirm your submission
                senderName = Website
                senderEmail = [email protected]
            }

            # Thank you page
            thx {
                redirect = # Page UID for redirect after submit
            }

            # Spam protection — numeric `methods` keys (matches EXT:powermail `12_Spamshield.typoscript`)
            spamshield {
                _enable = 1
                factor = 75
                methods {
                    1 {
                        _enable = 1
                        class = In2code\Powermail\Domain\Validator\SpamShield\HoneyPodMethod
                        indication = 5
                        configuration { }
                    }
                    2 {
                        _enable = 1
                        class = In2code\Powermail\Domain\Validator\SpamShield\LinkMethod
                        indication = 3
                        configuration {
                            linkLimit = 2
                        }
                    }
                    3 {
                        _enable = 1
                        class = In2code\Powermail\Domain\Validator\SpamShield\NameMethod
                        indication = 3
                        configuration { }
                    }
                    # SessionMethod sets a cookie when enabled — shipping TypoScript uses _enable = 0
                    4 {
                        _enable = 0
                        class = In2code\Powermail\Domain\Validator\SpamShield\SessionMethod
                        indication = 5
                        configuration { }
                    }
                    5 {
                        _enable = 1
                        class = In2code\Powermail\Domain\Validator\SpamShield\UniqueMethod
                        indication = 2
                        configuration { }
                    }
                    6 {
                        _enable = 1
                        class = In2code\Powermail\Domain\Validator\SpamShield\ValueBlacklistMethod
                        indication = 7
                        configuration {
                            values = TEXT
                            values.value = viagra,sex,porn
                        }
                    }
                    7 {
                        _enable = 1
                        class = In2code\Powermail\Domain\Validator\SpamShield\IpBlacklistMethod
                        indication = 7
                        configuration {
                            values = TEXT
                            values.value = 203.0.113.1
                        }
                    }
                    8 {
                        _enable = 1
                        class = In2code\Powermail\Domain\Validator\SpamShield\RateLimitMethod
                        indication = 100
                        configuration {
                            interval = 5 minutes
                            limit = 10
                            restrictions {
                                10 = __ipAddress
                                20 = __formIdentifier
                            }
                        }
                    }
                }
            }

            # Validation
            misc {
                htmlForLabels = 1
                showOnlyFilledValues = 1
                ajaxSubmit = 0
                file {
                    folder = uploads/tx_powermail/
                    size = 25000000
                    extension = jpg,jpeg,gif,png,tif,txt,doc,docx,xls,xlsx,ppt,pptx,pdf,zip,csv,svg
                }
            }
        }
    }
}

通过 TypoScript 预填字段

plugin.tx_powermail.settings.setup.prefill {
    # By field marker
    email = TEXT
    email.data = TSFE:fe_user|user|email

    firstname = TEXT
    firstname.data = TSFE:fe_user|user|first_name

    # Prefill from GET/POST
    subject = TEXT
    subject.data = GP:subject
}

营销信息

plugin.tx_powermail.settings.setup.marketing {
    enable = 1
    # Tracked: refererDomain, referer, country, mobileDevice, frontendLanguage, browserLanguage, pageFunnel
}

详细参考

如果任务需要详细示例、较长的模板、故障排查矩阵、附录或上文未包含的章节，请阅读完整指南。处理范围较窄的任务时，请勿加载此文件，以便技能遵循渐进式披露。