double-opt-in / src / Integration / FormIntegrationInterface.php

FormIntegrationInterface.php in Double Opt-In for Contact Form 7 – Secure, GDPR-Compliant Email Verification 5.5.0, at src/Integration/FormIntegrationInterface.php

170 lines 4.3 KB

Raw Download Zip

1	<?php
2	/**
3	* Form Integration Interface
4	*
5	* @package Forge12\DoubleOptIn\Integration
6	* @since 4.0.0
7	*/
8
9	namespace Forge12\DoubleOptIn\Integration;
10
11	use forge12\contactform7\CF7DoubleOptIn\OptIn;
12
13	if ( ! defined( 'ABSPATH' ) ) {
14	exit;
15	}
16
17	/**
18	* Interface FormIntegrationInterface
19	*
20	* @api
21	*
22	* Contract for all form integration implementations.
23	* Each form system (CF7, Avada, Elementor, etc.) must implement this interface.
24	*
25	* Covered by the Addon API semver policy as of Core API 4.3.0. See
26	* docs/addon-api.md §4.3 for usage and §7 for the deprecation process.
27	*/
28	interface FormIntegrationInterface {
29
30	/**
31	* Get the unique identifier for this integration.
32	*
33	* @return string The integration identifier (e.g., 'cf7', 'avada', 'elementor').
34	*/
35	public function getIdentifier(): string;
36
37	/**
38	* Get a human-readable name for this integration.
39	*
40	* @return string The integration display name.
41	*/
42	public function getName(): string;
43
44	/**
45	* Check if the integration's dependencies are available.
46	*
47	* @return bool True if the required plugin/theme is active.
48	*/
49	public function isAvailable(): bool;
50
51	/**
52	* Register WordPress hooks for this integration.
53	*
54	* Called during plugin initialization to set up all necessary hooks.
55	*
56	* @return void
57	*/
58	public function registerHooks(): void;
59
60	/**
61	* Process a form submission and create normalized FormData.
62	*
63	* @param mixed $context The form-system-specific submission context.
64	*
65	* @return FormDataInterface\|null The normalized form data or null if processing fails.
66	*/
67	public function processSubmission( $context ): ?FormDataInterface;
68
69	/**
70	* Resolve the recipient email address from form data.
71	*
72	* @param FormDataInterface $formData The normalized form data.
73	* @param array $formParameter The form configuration parameters.
74	*
75	* @return string The recipient email address.
76	*/
77	public function resolveRecipient( FormDataInterface $formData, array $formParameter ): string;
78
79	/**
80	* Send the opt-in confirmation mail.
81	*
82	* @param OptIn $optIn The opt-in record.
83	* @param FormDataInterface $formData The form data.
84	* @param array $formParameter The form configuration.
85	*
86	* @return bool True if the mail was sent successfully.
87	*/
88	public function sendOptInMail( OptIn $optIn, FormDataInterface $formData, array $formParameter ): bool;
89
90	/**
91	* Send the original (default) mail after opt-in confirmation.
92	*
93	* @param OptIn $optIn The confirmed opt-in record.
94	*
95	* @return void
96	*/
97	public function sendConfirmationMail( OptIn $optIn ): void;
98
99	/**
100	* Check if double opt-in is enabled for a specific form.
101	*
102	* @param int $formId The form ID.
103	*
104	* @return bool True if opt-in is enabled.
105	*/
106	public function isOptInEnabled( int $formId ): bool;
107
108	/**
109	* Get the form configuration parameters.
110	*
111	* @param int $formId The form ID.
112	*
113	* @return array The configuration parameters.
114	*/
115	public function getFormParameter( int $formId ): array;
116
117	/**
118	* Get all form field names/tags for a specific form.
119	*
120	* Used for building admin UI dropdowns.
121	*
122	* @param int\|string $formId The form ID (can be composite for some integrations like Elementor).
123	*
124	* @return array<string, string> Array of field name => field label.
125	*/
126	public function getFormFields( $formId ): array;
127
128	/**
129	* Get the priority for hook registration.
130	*
131	* Lower values execute earlier. Default is 10.
132	*
133	* @return int The hook priority.
134	*/
135	public function getHookPriority(): int;
136
137	/**
138	* Get all forms for this integration.
139	*
140	* Returns an array of forms with their basic information and DOI status.
141	*
142	* @since 4.1.0
143	*
144	* @return array<array{id: int, title: string, integration: string, enabled: bool, edit_url: string}>
145	*/
146	public function getForms(): array;
147
148	/**
149	* Get the title of a specific form.
150	*
151	* @since 4.1.0
152	*
153	* @param int\|string $formId The form ID (can be composite for some integrations like Elementor).
154	*
155	* @return string The form title.
156	*/
157	public function getFormTitle( $formId ): string;
158
159	/**
160	* Get the edit URL for a specific form.
161	*
162	* @since 4.1.0
163	*
164	* @param int\|string $formId The form ID (can be composite for some integrations like Elementor).
165	*
166	* @return string The edit URL.
167	*/
168	public function getFormEditUrl( $formId ): string;
169	}
170