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

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

133 lines 2.9 KB

Raw Download Zip

1	<?php
2	/**
3	* Form Data Interface
4	*
5	* @package Forge12\DoubleOptIn\Integration
6	* @since 4.0.0
7	*/
8
9	namespace Forge12\DoubleOptIn\Integration;
10
11	if ( ! defined( 'ABSPATH' ) ) {
12	exit;
13	}
14
15	/**
16	* Interface FormDataInterface
17	*
18	* @api
19	*
20	* Represents normalized form submission data across all integration types.
21	* This interface provides a standardized way to access form data regardless
22	* of the underlying form system (CF7, Avada, Elementor, etc.).
23	*
24	* Used as the payload for FormSubmittedEvent and as the return type of
25	* FormIntegrationInterface::processSubmission(). Covered by the Addon API
26	* semver policy as of Core API 4.3.0.
27	*/
28	interface FormDataInterface {
29
30	/**
31	* Get the form ID.
32	*
33	* @return int The form post ID.
34	*/
35	public function getFormId(): int;
36
37	/**
38	* Get the form type identifier.
39	*
40	* @return string The form type (e.g., 'cf7', 'avada', 'elementor').
41	*/
42	public function getFormType(): string;
43
44	/**
45	* Get all submitted form fields.
46	*
47	* @return array<string, mixed> Associative array of field name => value.
48	*/
49	public function getFields(): array;
50
51	/**
52	* Get a specific field value.
53	*
54	* @param string $key The field name.
55	* @param mixed $default Default value if field doesn't exist.
56	*
57	* @return mixed The field value or default.
58	*/
59	public function getField( string $key, $default = null );
60
61	/**
62	* Check if a field exists.
63	*
64	* @param string $key The field name.
65	*
66	* @return bool True if field exists.
67	*/
68	public function hasField( string $key ): bool;
69
70	/**
71	* Get uploaded files.
72	*
73	* @return array<string, array> Array of field name => file paths.
74	*/
75	public function getFiles(): array;
76
77	/**
78	* Get metadata about the submission.
79	*
80	* @return array<string, mixed> Metadata like source URL, timestamp, IP, etc.
81	*/
82	public function getMeta(): array;
83
84	/**
85	* Get a specific metadata value.
86	*
87	* @param string $key The metadata key.
88	* @param mixed $default Default value if key doesn't exist.
89	*
90	* @return mixed The metadata value or default.
91	*/
92	public function getMetaValue( string $key, $default = null );
93
94	/**
95	* Get the recipient email address.
96	*
97	* @return string The recipient email.
98	*/
99	public function getRecipientEmail(): string;
100
101	/**
102	* Get the form HTML content.
103	*
104	* @return string The form HTML.
105	*/
106	public function getFormHtml(): string;
107
108	/**
109	* Convert to array for serialization/storage.
110	*
111	* @return array The complete data as an array.
112	*/
113	public function toArray(): array;
114
115	/**
116	* Create a new instance with modified data.
117	*
118	* @param array $fields Fields to merge/override.
119	*
120	* @return static A new instance with modified data.
121	*/
122	public function withFields( array $fields ): self;
123
124	/**
125	* Create a new instance with modified metadata.
126	*
127	* @param array $meta Metadata to merge/override.
128	*
129	* @return static A new instance with modified metadata.
130	*/
131	public function withMeta( array $meta ): self;
132	}
133