sureforms / inc / compatibility / multilingual / string-backfill.php

string-backfill.php in SureForms – Contact Form Builder, AI Forms, Payment Form, Survey & Quiz 2.12.8, at inc/compatibility/multilingual/string-backfill.php

393 lines 13.0 KB

Raw Download Zip

1	<?php
2	/**
3	* Multilingual String Backfill.
4	*
5	* Registers String Packages for forms that already existed before the
6	* multilingual integration became active. Without this, a form's strings only
7	* reach the multilingual provider when the form is next re-saved, so existing
8	* forms stay invisible to WPML until manually opened and saved again.
9	*
10	* @package sureforms.
11	* @since 2.12.3
12	*/
13
14	namespace SRFM\Inc\Compatibility\Multilingual;
15
16	use SRFM\Inc\Helper;
17	use SRFM\Inc\Traits\Get_Instance;
18
19	if ( ! defined( 'ABSPATH' ) ) {
20	exit; // Exit if accessed directly.
21	}
22
23	/**
24	* String_Backfill.
25	*
26	* One-time (per {@see self::SCHEMA_VERSION}) pass that runs
27	* {@see String_Collector::collect()} for every existing form once a multilingual
28	* provider is active, so their String Packages are registered without needing a
29	* manual re-save.
30	*
31	* @since 2.12.3
32	*/
33	class String_Backfill {
34	use Get_Instance;
35
36	/**
37	* Option that records the schema version the backfill last completed for.
38	*
39	* @since 2.12.3
40	*/
41	public const DONE_OPTION = 'srfm_wpml_backfill_done';
42
43	/**
44	* Backfill schema version. Bump this ONLY when the set of strings registered
45	* by String_Collector changes, to force a one-time re-backfill. Deliberately
46	* NOT tied to SRFM_VER, so ordinary plugin releases don't re-enqueue a job
47	* per form on every update.
48	*
49	* @since 2.12.3
50	*/
51	public const SCHEMA_VERSION = '2';
52
53	/**
54	* Option holding the in-progress run lock: [ 'schema' => string, 'started' => int ].
55	*
56	* Separate from DONE_OPTION on purpose. DONE_OPTION means "the whole pass finished";
57	* this means "a pass is currently running". Conflating them meant a run that died
58	* mid-way looked complete forever.
59	*
60	* @since 2.12.3
61	*/
62	public const LOCK_OPTION = 'srfm_wpml_backfill_lock';
63
64	/**
65	* How long a run lock is honoured before it is treated as stale and reclaimed.
66	*
67	* Bounds the failure mode where a worker dies without chaining: the next admin load
68	* after this window restarts the pass, and the per-form markers make the replay cheap.
69	*
70	* @since 2.12.3
71	*/
72	public const LOCK_TTL = 3600;
73
74	/**
75	* Action Scheduler hook that backfills a single form.
76	*
77	* @since 2.12.3
78	*/
79	public const HOOK = 'srfm_wpml_backfill_form';
80
81	/**
82	* Action Scheduler hook that backfills one page of forms and chains the next.
83	*
84	* @since 2.12.3
85	*/
86	public const HOOK_BATCH = 'srfm_wpml_backfill_batch';
87
88	/**
89	* Per-form meta key recording the schema version a form was last backfilled for.
90	*
91	* Makes the pass idempotent per form, so a replayed or partially-failed batch
92	* never re-registers packages it already handled.
93	*
94	* @since 2.12.3
95	*/
96	public const FORM_MARKER = '_srfm_wpml_backfilled';
97
98	/**
99	* Forms processed per batch action.
100	*
101	* @since 2.12.3
102	*/
103	private const BATCH_SIZE = 50;
104
105	/**
106	* Constructor. Schedules the backfill on admin load and handles each queued form.
107	*
108	* @since 2.12.3
109	*/
110	public function __construct() {
111	add_action( 'admin_init', [ $this, 'maybe_schedule' ] );
112	add_action( self::HOOK_BATCH, [ $this, 'backfill_batch' ], 10, 1 );
113	// Void wrapper: backfill_one() returns a bool for the batch's progress accounting,
114	// and an action callback must not return a value. HOOK stays registered so any
115	// per-form actions still pending from the previous implementation drain cleanly.
116	add_action( self::HOOK, [ $this, 'handle_backfill_action' ], 10, 1 );
117	}
118
119	/**
120	* Queue a one-time backfill of all existing forms when a provider is active.
121	*
122	* Bails when the request is not a privileged admin page load, when no
123	* multilingual provider is active, when the backfill has already completed for
124	* the current schema version, or when Action Scheduler is unavailable.
125	*
126	* Enqueues ONE paginating batch action rather than one action per form. Action
127	* Scheduler's `$unique` flag matches on (status, hook, group_id) only — it does
128	* NOT consider `args` — so a per-form fan-out with `$unique = true` inserted the
129	* first form and then silently wrote 0 rows for every subsequent one, leaving
130	* exactly one form backfilled per site. A single self-chaining batch action never
131	* has more than one pending row for this hook, so uniqueness is irrelevant and
132	* the query stays bounded.
133	*
134	* @since 2.12.3
135	* @return void
136	*/
137	public function maybe_schedule(): void {
138	// Only a genuine, privileged admin page load may start this. `admin_init`
139	// also fires inside admin-ajax.php, which is reachable unauthenticated, and
140	// this pass is state-changing and touches every form.
141	if ( wp_doing_ajax() \|\| wp_doing_cron() \|\| ! Helper::current_user_can() ) {
142	return;
143	}
144
145	if ( ! Multilingual_Manager::get_instance()->provider()->is_active() ) {
146	return;
147	}
148
149	if ( self::SCHEMA_VERSION === get_option( self::DONE_OPTION ) ) {
150	return;
151	}
152
153	if ( ! function_exists( 'as_enqueue_async_action' ) ) {
154	return;
155	}
156
157	// A run already in flight (a fresh, non-stale lock) — don't start a second chain.
158	if ( $this->is_run_in_flight() ) {
159	return;
160	}
161
162	// A stale lock left by a worker that died without chaining. Clear it so the
163	// atomic add_option() below can re-take it.
164	delete_option( self::LOCK_OPTION );
165
166	// Take the lock atomically BEFORE enqueuing. add_option() is an INSERT that returns
167	// false when the row already exists, so two concurrent admin requests can't both
168	// pass is_run_in_flight() and both start a chain — exactly one wins. Completion is
169	// NOT recorded here; that only happens when the final page comes back empty.
170	// autoload=false: this admin-only marker never needs to load on the front end.
171	$acquired = add_option(
172	self::LOCK_OPTION,
173	[
174	'schema' => self::SCHEMA_VERSION,
175	'started' => time(),
176	],
177	'',
178	false
179	);
180
181	if ( ! $acquired ) {
182	// Another request won the race.
183	return;
184	}
185
186	// Verify the action actually got queued. as_enqueue_async_action() returns 0 when
187	// the insert wrote no rows, silently and without raising — so an unchecked call
188	// could leave the pass never started with the lock held.
189	$action_id = as_enqueue_async_action( self::HOOK_BATCH, [ 'paged' => 1 ], 'srfm' );
190
191	if ( empty( $action_id ) ) {
192	// Release immediately so the next admin load retries rather than waiting out
193	// the whole lock TTL.
194	delete_option( self::LOCK_OPTION );
195
196	/**
197	* Fires when the backfill's first batch action could not be queued.
198	*
199	* @since 2.12.3
200	* @param string $schema_version The schema version being backfilled.
201	*/
202	do_action( 'srfm_wpml_backfill_enqueue_failed', self::SCHEMA_VERSION );
203	}
204	}
205
206	/**
207	* Backfill one page of forms, then chain the next page.
208	*
209	* Runs String_Collector directly per form (rather than enqueuing a child action
210	* each) and re-enqueues itself for the following page until a page comes back
211	* empty. Each form is marked with self::FORM_MARKER on success, so a batch that
212	* dies part-way can be replayed without re-registering packages it already did.
213	*
214	* @param mixed $paged 1-based page number.
215	* @since 2.12.3
216	* @return void
217	*/
218	public function backfill_batch( $paged = 1 ): void {
219	// Args arrive from Action Scheduler, so the type is not guaranteed.
220	$paged = is_numeric( $paged ) ? max( 1, (int) $paged ) : 1;
221
222	// The provider can be deactivated between scheduling and execution. Abandon the
223	// run and release the lock WITHOUT recording completion, so a later admin load
224	// restarts the pass once a provider is active again.
225	if ( ! Multilingual_Manager::get_instance()->provider()->is_active() ) {
226	delete_option( self::LOCK_OPTION );
227
228	/**
229	* Fires when a backfill batch aborts because no multilingual provider is active.
230	*
231	* @since 2.12.3
232	* @param int $paged The page the run stopped on.
233	*/
234	do_action( 'srfm_wpml_backfill_aborted', $paged );
235	return;
236	}
237
238	// Refresh the lock so a long multi-page run isn't reclaimed as stale mid-flight.
239	update_option(
240	self::LOCK_OPTION,
241	[
242	'schema' => self::SCHEMA_VERSION,
243	'started' => time(),
244	],
245	false
246	);
247
248	$form_ids = get_posts(
249	[
250	'post_type' => SRFM_FORMS_POST_TYPE,
251	'post_status' => [ 'publish', 'draft', 'pending', 'private', 'future' ],
252	'fields' => 'ids',
253	'posts_per_page' => self::BATCH_SIZE, // phpcs:ignore WordPress.WP.PostsPerPage.posts_per_page_posts_per_page -- Bounded constant (50); batching is the point of this query.
254	'paged' => $paged,
255	'orderby' => 'ID',
256	'order' => 'ASC',
257	]
258	);
259
260	// An empty page means every form has been walked — THIS is the only place the pass
261	// is recorded as complete, and only after all pages actually finished.
262	if ( empty( $form_ids ) \|\| ! is_array( $form_ids ) ) {
263	update_option( self::DONE_OPTION, self::SCHEMA_VERSION, false );
264	delete_option( self::LOCK_OPTION );
265
266	/**
267	* Fires when the multilingual string backfill has completed every page.
268	*
269	* @since 2.12.3
270	* @param string $schema_version The schema version that completed.
271	*/
272	do_action( 'srfm_wpml_backfill_completed', self::SCHEMA_VERSION );
273	return;
274	}
275
276	$collected = 0;
277	foreach ( $form_ids as $form_id ) {
278	if ( $this->backfill_one( (int) $form_id ) ) {
279	$collected++;
280	}
281	}
282
283	// Nothing on a non-empty page could be collected — the provider went away
284	// mid-page. Stop and release rather than chaining and marking progress.
285	if ( 0 === $collected ) {
286	delete_option( self::LOCK_OPTION );
287	do_action( 'srfm_wpml_backfill_aborted', $paged );
288	return;
289	}
290
291	if ( ! function_exists( 'as_enqueue_async_action' ) ) {
292	// Cannot chain — release the lock so the next admin load resumes. Already-marked
293	// forms are skipped, so the replay only redoes the unfinished tail.
294	delete_option( self::LOCK_OPTION );
295	return;
296	}
297
298	// One pending action at a time, so $unique is unnecessary here.
299	$next_id = as_enqueue_async_action( self::HOOK_BATCH, [ 'paged' => $paged + 1 ], 'srfm' );
300
301	if ( empty( $next_id ) ) {
302	// The chain broke. Release so a later admin load restarts; FORM_MARKER means it
303	// resumes rather than starting over.
304	delete_option( self::LOCK_OPTION );
305	do_action( 'srfm_wpml_backfill_enqueue_failed', self::SCHEMA_VERSION );
306	}
307	}
308
309	/**
310	* Action-hook entry point for a single-form backfill.
311	*
312	* Exists so backfill_one() can report success to the batch loop while the hook
313	* callback itself returns nothing.
314	*
315	* @param mixed $form_id The form post ID to backfill.
316	* @since 2.12.3
317	* @return void
318	*/
319	public function handle_backfill_action( $form_id ): void {
320	$this->backfill_one( is_numeric( $form_id ) ? (int) $form_id : 0 );
321	}
322
323	/**
324	* Backfill a single form's String Package.
325	*
326	* @param int $form_id The form post ID to backfill.
327	* @since 2.12.3
328	* @since 2.12.3 Returns whether the form was (or already had been) collected, and only
329	* writes the marker on a confirmed collection.
330	* @return bool True when this form is backfilled for the current schema version.
331	*/
332	public function backfill_one( int $form_id ): bool {
333	if ( $form_id <= 0 ) {
334	return false;
335	}
336
337	// Only ever touch SureForms forms. backfill_batch()'s get_posts() is already
338	// post-type-scoped, but self::HOOK stays registered for actions queued by the
339	// previous implementation and routes any numeric arg through
340	// handle_backfill_action() — so guard here too, mirroring
341	// String_Collector::on_form_delete(), so a stray do_action( self::HOOK, $id )
342	// can't write our meta onto (or run collect() against) an arbitrary post.
343	if ( SRFM_FORMS_POST_TYPE !== get_post_type( $form_id ) ) {
344	return false;
345	}
346
347	// Idempotency guard: a replayed batch must not re-register packages for forms
348	// it already processed under this schema version.
349	if ( self::SCHEMA_VERSION === get_post_meta( $form_id, self::FORM_MARKER, true ) ) {
350	return true;
351	}
352
353	// collect() returns false when the provider is inactive, in which case it did
354	// nothing. Marking the form regardless would permanently skip it — the exact
355	// failure this backfill exists to prevent — so the marker is only written on a
356	// confirmed collection.
357	if ( ! String_Collector::get_instance()->collect( $form_id ) ) {
358	return false;
359	}
360
361	update_post_meta( $form_id, self::FORM_MARKER, self::SCHEMA_VERSION );
362
363	return true;
364	}
365	/**
366	* Whether a backfill run is currently in flight for this schema version.
367	*
368	* A lock older than self::LOCK_TTL is treated as stale and ignored, which is how an
369	* interrupted run (worker died before chaining the next page, host restarted, action
370	* purged) recovers instead of stalling forever. Replaying is cheap because
371	* self::FORM_MARKER skips forms already done.
372	*
373	* @since 2.12.3
374	* @return bool
375	*/
376	private function is_run_in_flight(): bool {
377	$lock = get_option( self::LOCK_OPTION );
378
379	if ( ! is_array( $lock ) ) {
380	return false;
381	}
382
383	// A lock from an older schema version is irrelevant to this pass.
384	if ( self::SCHEMA_VERSION !== ( $lock['schema'] ?? '' ) ) {
385	return false;
386	}
387
388	$started = isset( $lock['started'] ) && is_numeric( $lock['started'] ) ? (int) $lock['started'] : 0;
389
390	return time() - $started < self::LOCK_TTL;
391	}
392	}
393