double-opt-in / src / Repository / OptInRepositoryInterface.php

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

177 lines 4.4 KB

Raw Download Zip

1	<?php
2	/**
3	* OptIn Repository Interface
4	*
5	* @package Forge12\DoubleOptIn\Repository
6	* @since 4.0.0
7	*/
8
9	namespace Forge12\DoubleOptIn\Repository;
10
11	use Forge12\DoubleOptIn\Entity\OptIn;
12
13	if ( ! defined( 'ABSPATH' ) ) {
14	exit;
15	}
16
17	/**
18	* Interface OptInRepositoryInterface
19	*
20	* @api
21	*
22	* Contract for OptIn data access operations. Addons that need to read
23	* opt-in data (analytics, exports, custom reports) resolve this from the
24	* container rather than issuing direct `$wpdb` queries against the shared
25	* opt-in table. Covered by the Addon API semver policy as of Core API 4.3.0.
26	*/
27	interface OptInRepositoryInterface {
28
29	/**
30	* Find an OptIn by its ID.
31	*
32	* @param int $id The OptIn ID.
33	*
34	* @return OptIn\|null
35	*/
36	public function findById( int $id ): ?OptIn;
37
38	/**
39	* Find an OptIn by its hash.
40	*
41	* @param string $hash The unique hash.
42	*
43	* @return OptIn\|null
44	*/
45	public function findByHash( string $hash ): ?OptIn;
46
47	/**
48	* Find all OptIns by email address.
49	*
50	* @param string $email The email address.
51	*
52	* @return OptIn[]
53	*/
54	public function findByEmail( string $email ): array;
55
56	/**
57	* Find confirmed OptIns by email address.
58	*
59	* @param string $email The email address.
60	*
61	* @return OptIn[]
62	*/
63	public function findConfirmedByEmail( string $email ): array;
64
65	/**
66	* Find unconfirmed OptIns by email address.
67	*
68	* @param string $email The email address.
69	*
70	* @return OptIn[]
71	*/
72	public function findUnconfirmedByEmail( string $email ): array;
73
74	/**
75	* Find OptIns by category with pagination.
76	*
77	* @param int $categoryId The category ID (0 for all).
78	* @param array $options Options: perPage, page, orderBy, order, keyword.
79	*
80	* @return OptIn[]
81	*/
82	public function findByCategory( int $categoryId, array $options = array() ): array;
83
84	/**
85	* Count OptIns by category.
86	*
87	* @param int $categoryId The category ID (0 for all).
88	* @param string $keyword Optional search keyword.
89	*
90	* @return int
91	*/
92	public function countByCategory( int $categoryId, string $keyword = '' ): int;
93
94	/**
95	* Count OptIns by form ID.
96	*
97	* @param int $formId The form ID.
98	*
99	* @return int
100	*/
101	public function countByFormId( int $formId ): int;
102
103	/**
104	* Save an OptIn (insert or update).
105	*
106	* @param OptIn $optIn The OptIn entity.
107	*
108	* @return OptIn The saved entity with ID.
109	* @throws \RuntimeException If save fails.
110	*/
111	public function save( OptIn $optIn ): OptIn;
112
113	/**
114	* Delete an OptIn.
115	*
116	* @param OptIn $optIn The OptIn to delete.
117	*
118	* @return bool True on success.
119	*/
120	public function delete( OptIn $optIn ): bool;
121
122	/**
123	* Delete an OptIn by hash.
124	*
125	* @param string $hash The hash.
126	*
127	* @return int Number of deleted rows.
128	*/
129	public function deleteByHash( string $hash ): int;
130
131	/**
132	* Bulk update category for multiple OptIns.
133	*
134	* @param int $fromCategoryId The source category ID.
135	* @param int $toCategoryId The target category ID.
136	*
137	* @return int Number of updated rows.
138	*/
139	public function bulkUpdateCategory( int $fromCategoryId, int $toCategoryId ): int;
140
141	/**
142	* Delete OptIns older than a timestamp by confirmation status.
143	*
144	* @param int $timestamp Cutoff timestamp.
145	* @param bool $confirmed True for confirmed, false for unconfirmed.
146	*
147	* @return int Number of deleted rows.
148	*/
149	public function deleteOlderThan( int $timestamp, bool $confirmed ): int;
150
151	/**
152	* Find unconfirmed OptIns eligible for a reminder email.
153	*
154	* Returns entries that are unconfirmed, have no reminder sent yet,
155	* have a valid email, are not opted out, and were created at least
156	* $delaySeconds ago but not older than $safetyFloorSeconds.
157	*
158	* @param int $delaySeconds Minimum age in seconds before reminder is sent.
159	* @param int $safetyFloorSeconds Maximum age in seconds (entries older than this are excluded).
160	* @param int $limit Maximum number of results.
161	*
162	* @return OptIn[]
163	*/
164	public function findEligibleForReminder( int $delaySeconds, int $safetyFloorSeconds = 0, int $limit = 50 ): array;
165
166	/**
167	* Check if an active (non-opted-out) OptIn exists for the given email and form ID.
168	*
169	* @param string $email The email address.
170	* @param int $formId The form ID.
171	* @param bool $confirmedOnly Whether to check only confirmed opt-ins.
172	*
173	* @return bool
174	*/
175	public function existsByEmailAndFormId( string $email, int $formId, bool $confirmedOnly = true ): bool;
176	}
177