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

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

111 lines 3.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Follow-up repository contract.
4	*
5	* @package Forge12\DoubleOptIn\Repository
6	* @since 5.6.0
7	*/
8
9	declare( strict_types=1 );
10
11	namespace Forge12\DoubleOptIn\Repository;
12
13	use Forge12\DoubleOptIn\FollowUp\FollowUpAction;
14	use Forge12\DoubleOptIn\FollowUp\FollowUpRecord;
15	use Forge12\DoubleOptIn\FollowUp\FollowUpResult;
16
17	if ( ! defined( 'ABSPATH' ) ) {
18	exit;
19	}
20
21	/**
22	* Persistence for follow-up action state.
23	*
24	* Every state change that decides "who executes" (`claim`,
25	* `consumeTicket`) is a single conditional UPDATE — the database, not a
26	* PHP flag or a transient, arbitrates between concurrent requests.
27	*/
28	interface FollowUpRepositoryInterface {
29
30	/**
31	* Insert one row per action unless it already exists (the unique key
32	* (optin_id, action_id) makes this idempotent).
33	*
34	* @param FollowUpAction[] $actions
35	* @param array<string, string> $skipReasons Action id => reason; those rows
36	* are inserted as `skipped`.
37	*
38	* @return int Number of rows actually inserted.
39	*/
40	public function plan( int $optInId, string $integration, array $actions, array $skipReasons, string $fingerprint, string $now ): int;
41
42	/**
43	* @return FollowUpRecord[]
44	*/
45	public function findByOptIn( int $optInId ): array;
46
47	/**
48	* Atomically move one row from any of $fromStatuses to `running`.
49	*
50	* @param string[] $fromStatuses
51	*
52	* @return bool True only for the request that won the claim.
53	*/
54	public function claim( int $rowId, array $fromStatuses, string $attemptId, string $trigger, string $now, string $leaseUntil ): bool;
55
56	/**
57	* Store the result of a claimed row. Only succeeds while the row is
58	* still `running` under the same attempt id.
59	*/
60	public function complete( int $rowId, string $attemptId, FollowUpResult $result, string $now, string $nextAttemptAt ): bool;
61
62	/**
63	* Attach a hashed single-use ticket to every row of an attempt.
64	*/
65	public function setTicket( int $optInId, string $attemptId, string $ticketHash, string $expiresAt ): void;
66
67	/**
68	* Atomically consume a ticket. Returns the action ids bound to it, or
69	* null when the ticket is unknown, expired or already used.
70	*
71	* @return string[]\|null
72	*/
73	public function consumeTicket( int $optInId, string $ticketHash, string $now ): ?array;
74
75	/**
76	* Rows stuck in `running` past their lease become `unknown`: the
77	* process may have died after the side effect. Returns affected rows.
78	*/
79	public function expireLeases( string $now ): int;
80
81	/**
82	* Opt-in ids with work the sweep may pick up: `failed_retryable`
83	* whose next attempt is due, or `pending` on a confirmed opt-in older
84	* than $pendingBefore (the confirming request died before running it).
85	*
86	* @return int[]
87	*/
88	public function findDueOptInIds( string $now, string $pendingBefore, int $limit ): array;
89
90	/**
91	* Mark every open row (pending / failed_retryable) of an opt-in as
92	* skipped. Returns affected rows.
93	*/
94	public function skipOpen( int $optInId, string $reason, string $now ): int;
95
96	public function deleteByOptIn( int $optInId ): int;
97
98	/**
99	* Delete rows whose opt-in no longer exists. Backstop for deletion
100	* paths that do not fire `f12_doi_optin_pre_delete` (repository
101	* deletes, direct SQL by third parties). Returns affected rows.
102	*/
103	public function deleteOrphans( int $limit ): int;
104
105	/**
106	* Fully qualified table name — for list filters that need an EXISTS
107	* sub-query against the opt-in table.
108	*/
109	public function getTableName(): string;
110	}
111