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

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

73 lines 2.2 KB

Raw Download Zip

1	<?php
2	/**
3	* Contract between the follow-up coordinator and a form integration.
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	use forge12\contactform7\CF7DoubleOptIn\OptIn;
14
15	if ( ! defined( 'ABSPATH' ) ) {
16	exit;
17	}
18
19	/**
20	* Additive contract (Core API 4.4). Integrations that implement it hand
21	* the post-confirmation work to the coordinator, which persists a
22	* status per action, claims each action atomically and records an
23	* honest result. Integrations that do not implement it keep the
24	* previous behaviour unchanged.
25	*
26	* Adapters are registered on `f12_doi_register_follow_up_adapters`.
27	*/
28	interface FollowUpAdapterInterface {
29
30	/**
31	* Integration identifier, identical to the one passed to
32	* `OptIn::isType()` (`cf7`, `elementor`, `avada`, `wpforms`,
33	* `gravityforms`).
34	*/
35	public function getIntegration(): string;
36
37	/**
38	* The actions this opt-in needs after confirmation, read from the
39	* form's current configuration. Called once per opt-in; the result
40	* is bound (persisted) and later configuration changes do not add
41	* or re-map actions.
42	*
43	* An empty array means "nothing configured".
44	*
45	* @return FollowUpAction[]
46	*/
47	public function planActions( OptIn $optIn ): array;
48
49	/**
50	* Execute the given actions. Every action passed in has been claimed
51	* for this attempt and MUST get a result; a missing result is
52	* recorded as `unknown`.
53	*
54	* Implementations must not throw for expected failures — return a
55	* failed result instead. Any global state (superglobals, temporary
56	* filters) must be restored in `finally`.
57	*
58	* @param FollowUpAction[] $actions
59	*
60	* @return array<string, FollowUpResult> Keyed by action id.
61	*/
62	public function execute( OptIn $optIn, array $actions, FollowUpAttempt $attempt ): array;
63
64	/**
65	* Called after every attempt with the complete status of the
66	* opt-in, so the adapter can release resources — e.g. delete
67	* staged uploads once every action that needs them is done.
68	*
69	* @param array<string, string> $statusByAction Action id => status.
70	*/
71	public function onSettled( OptIn $optIn, array $statusByAction ): void;
72	}
73