typo3-powermail

TYPO3 Powermail 開発

出典：https://github.com/dirnbauer/webconsulting-skills

互換性： Packagist によると、Powermail 13.x は現在 TYPO3 13.4 を対象としています。パッケージで宣言されるまでは、v14 を想定しないでください。可能な限り、例では最新の TYPO3 API を使用しています。Core のバージョンに合わせて調整してください。 すべての例は PHP 8.2 以降を使用しています。

TYPO3 API を優先： カスタム実装を作成する前に、必ず TYPO3 の組み込み API、コア機能、確立された規約を使用してください。TYPO3 がすでに提供しているものを再実装しないでください。使用する API やメソッドが存在し、TYPO3 v14 で非推奨になっていないことを、公式 TYPO3 ドキュメントで必ず確認してください。

補足：

• 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 のフォームフレームワークにおける削除内容（フック → 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	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
}

詳細リファレンス

詳細な例、長いテンプレート、トラブルシューティングのマトリックス、付録、または上記に含まれていないセクションが必要なタスクでは、完全なガイドをお読みください。タスクの範囲が狭い場合は、このファイルを読み込まず、スキルが段階的に情報を開示するようにしてください。