double-opt-in / src / FollowUp / FollowUpAction.php

FollowUpAction.php in Double Opt-In for Contact Form 7 – Secure, GDPR-Compliant Email Verification 5.6.0, at src/FollowUp/FollowUpAction.php

127 lines 3.7 KB

Raw Download Zip

1	<?php
2	/**
3	* Descriptor of one planned follow-up action.
4	*
5	* @package Forge12\DoubleOptIn\FollowUp
6	* @since 5.6.0
7	*/
8
9	declare( strict_types=1 );
10
11	namespace Forge12\DoubleOptIn\FollowUp;
12
13	if ( ! defined( 'ABSPATH' ) ) {
14	exit;
15	}
16
17	/**
18	* What an adapter will do for a confirmed opt-in.
19	*
20	* The id is the idempotency key: together with the opt-in id it is
21	* unique in the follow-up table, so the same action is never planned —
22	* and never executed — twice. It must therefore be stable across
23	* requests (`elementor:email`, `wpforms:notification:2`), never derived
24	* from time or randomness.
25	*/
26	final class FollowUpAction {
27
28	public const KIND_ENTRY = 'entry';
29	public const KIND_MAIL = 'mail';
30	public const KIND_WEBHOOK = 'webhook';
31	public const KIND_DISPATCH = 'dispatch';
32	public const KIND_OPAQUE = 'opaque';
33	public const KIND_MARKER = 'marker';
34
35	/**
36	* Reserved id for "the integration planned nothing". Lets the admin
37	* tell "no follow-ups configured" apart from "no status recorded".
38	*/
39	public const ID_NONE = '_none';
40
41	/** @var string */
42	private $id;
43
44	/** @var string */
45	private $kind;
46
47	/** @var string */
48	private $label;
49
50	/** @var bool */
51	private $gatedByDefaultMail;
52
53	/** @var string */
54	private $skipReason;
55
56	/** @var string */
57	private $previousEntryRef;
58
59	/**
60	* @param string $id Stable action id, [a-z0-9_:.-], max 100 chars.
61	* @param string $kind One of the KIND_* constants.
62	* @param string $label Non-personal label for the admin (e.g. "Email 2").
63	* @param bool $gatedByDefaultMail Whether `f12_cf7_doubleoptin_send_default_mail = false`
64	* disables this action. Mirrors the existing
65	* per-integration semantics of that filter.
66	* @param string $skipReason Non-empty: plan the action as `skipped`
67	* with this reason (e.g. `not_supported`).
68	* @param string $previousEntryRef On a retry: the record a previous attempt
69	* already created (e.g. a half-written
70	* submission), so the adapter can avoid a
71	* duplicate instead of starting over.
72	*/
73	public function __construct( string $id, string $kind, string $label, bool $gatedByDefaultMail = true, string $skipReason = '', string $previousEntryRef = '' ) {
74	$id = strtolower( $id );
75	if ( $id === '' \|\| strlen( $id ) > 100 \|\| preg_match( '/[^a-z0-9_:.\-]/', $id ) ) {
76	throw new \InvalidArgumentException( 'Invalid follow-up action id.' );
77	}
78
79	$this->id = $id;
80	$this->kind = $kind;
81	$this->label = substr( $label, 0, 190 );
82	$this->gatedByDefaultMail = $gatedByDefaultMail;
83	$this->skipReason = $skipReason;
84	$this->previousEntryRef = $previousEntryRef;
85	}
86
87	public function getPreviousEntryRef(): string {
88	return $this->previousEntryRef;
89	}
90
91	public function getId(): string {
92	return $this->id;
93	}
94
95	public function getKind(): string {
96	return $this->kind;
97	}
98
99	public function getLabel(): string {
100	return $this->label;
101	}
102
103	public function isGatedByDefaultMail(): bool {
104	return $this->gatedByDefaultMail;
105	}
106
107	public function getSkipReason(): string {
108	return $this->skipReason;
109	}
110
111	/**
112	* Stable fingerprint of a plan: the sorted action ids. Stored with
113	* every row so a later retry can tell whether the form's action set
114	* changed since the plan was bound.
115	*
116	* @param FollowUpAction[] $actions
117	*/
118	public static function fingerprint( array $actions ): string {
119	$ids = array();
120	foreach ( $actions as $action ) {
121	$ids[] = $action->getId();
122	}
123	sort( $ids );
124	return hash( 'sha256', implode( '\|', $ids ) );
125	}
126	}
127