1	<?php
2	/**
3	* Sync architecture prototype.
4	*
5	* To run tests: phpunit --testsuite sync --filter New_Sync
6	*
7	* @author Dan Walmsley
8	* @package automattic/jetpack-sync
9	*/
10
11	namespace Automattic\Jetpack\Sync;
12
13	/**
14	* A high-level interface for objects that store synced WordPress data.
15	* Useful for ensuring that different storage mechanisms implement the
16	* required semantics for storing all the data that we sync.
17	*/
18	interface Replicastore_Interface {
19	/**
20	* Empty and reset the replicastore.
21	*
22	* @access public
23	*/
24	public function reset();
25
26	/**
27	* Ran when full sync has just started.
28	*
29	* @access public
30	*
31	* @param array $config Full sync configuration for this sync module.
32	*/
33	public function full_sync_start( $config );
34
35	/**
36	* Ran when full sync has just finished.
37	*
38	* @access public
39	*
40	* @param string $checksum Deprecated since 7.3.0.
41	*/
42	public function full_sync_end( $checksum );
43
44	/**
45	* Retrieve the number of posts with a particular post status within a certain range.
46	*
47	* @access public
48	*
49	* @todo Prepare the SQL query before executing it.
50	*
51	* @param string $status Post status.
52	* @param int    $min_id Minimum post ID.
53	* @param int    $max_id Maximum post ID.
54	*/
55	public function post_count( $status = null, $min_id = null, $max_id = null );
56
57	/**
58	* Retrieve the posts with a particular post status.
59	*
60	* @access public
61	*
62	* @param string $status Post status.
63	* @param int    $min_id Minimum post ID.
64	* @param int    $max_id Maximum post ID.
65	*/
66	public function get_posts( $status = null, $min_id = null, $max_id = null );
67
68	/**
69	* Retrieve a post object by the post ID.
70	*
71	* @access public
72	*
73	* @param int $id Post ID.
74	*/
75	public function get_post( $id );
76
77	/**
78	* Update or insert a post.
79	*
80	* @access public
81	*
82	* @param \WP_Post $post   Post object.
83	* @param bool     $silent Whether to perform a silent action.
84	*/
85	public function upsert_post( $post, $silent = false );
86
87	/**
88	* Delete a post by the post ID.
89	*
90	* @access public
91	*
92	* @param int $post_id Post ID.
93	*/
94	public function delete_post( $post_id );
95
96	/**
97	* Retrieve the checksum for posts within a range.
98	*
99	* @access public
100	*
101	* @param int $min_id Minimum post ID.
102	* @param int $max_id Maximum post ID.
103	*/
104	public function posts_checksum( $min_id = null, $max_id = null );
105
106	/**
107	* Retrieve the checksum for post meta within a range.
108	*
109	* @access public
110	*
111	* @param int $min_id Minimum post meta ID.
112	* @param int $max_id Maximum post meta ID.
113	*/
114	public function post_meta_checksum( $min_id = null, $max_id = null );
115
116	/**
117	* Retrieve the number of comments with a particular comment status within a certain range.
118	*
119	* @access public
120	*
121	* @param string $status Comment status.
122	* @param int    $min_id Minimum comment ID.
123	* @param int    $max_id Maximum comment ID.
124	*/
125	public function comment_count( $status = null, $min_id = null, $max_id = null );
126
127	/**
128	* Retrieve the comments with a particular comment status.
129	*
130	* @access public
131	*
132	* @param string $status Comment status.
133	* @param int    $min_id Minimum comment ID.
134	* @param int    $max_id Maximum comment ID.
135	*/
136	public function get_comments( $status = null, $min_id = null, $max_id = null );
137
138	/**
139	* Retrieve a comment object by the comment ID.
140	*
141	* @access public
142	*
143	* @param int $id Comment ID.
144	*/
145	public function get_comment( $id );
146
147	/**
148	* Update or insert a comment.
149	*
150	* @access public
151	*
152	* @param \WP_Comment $comment Comment object.
153	*/
154	public function upsert_comment( $comment );
155
156	/**
157	* Trash a comment by the comment ID.
158	*
159	* @access public
160	*
161	* @param int $comment_id Comment ID.
162	*/
163	public function trash_comment( $comment_id );
164
165	/**
166	* Mark a comment by the comment ID as spam.
167	*
168	* @access public
169	*
170	* @param int $comment_id Comment ID.
171	*/
172	public function spam_comment( $comment_id );
173
174	/**
175	* Delete a comment by the comment ID.
176	*
177	* @access public
178	*
179	* @param int $comment_id Comment ID.
180	*/
181	public function delete_comment( $comment_id );
182
183	/**
184	* Trash the comments of a post.
185	*
186	* @access public
187	*
188	* @param int   $post_id  Post ID.
189	* @param array $statuses Post statuses.
190	*/
191	public function trashed_post_comments( $post_id, $statuses );
192
193	/**
194	* Untrash the comments of a post.
195	*
196	* @access public
197	*
198	* @param int $post_id Post ID.
199	*/
200	public function untrashed_post_comments( $post_id );
201
202	/**
203	* Retrieve the checksum for comments within a range.
204	*
205	* @access public
206	*
207	* @param int $min_id Minimum comment ID.
208	* @param int $max_id Maximum comment ID.
209	*/
210	public function comments_checksum( $min_id = null, $max_id = null );
211
212	/**
213	* Retrieve the checksum for comment meta within a range.
214	*
215	* @access public
216	*
217	* @param int $min_id Minimum comment meta ID.
218	* @param int $max_id Maximum comment meta ID.
219	*/
220	public function comment_meta_checksum( $min_id = null, $max_id = null );
221
222	/**
223	* Update the value of an option.
224	*
225	* @access public
226	*
227	* @param string $option Option name.
228	* @param mixed  $value  Option value.
229	*/
230	public function update_option( $option, $value );
231
232	/**
233	* Retrieve an option value based on an option name.
234	*
235	* @access public
236	*
237	* @param string $option  Name of option to retrieve.
238	* @param mixed  $default Optional. Default value to return if the option does not exist.
239	*/
240	public function get_option( $option, $default = false );
241
242	/**
243	* Remove an option by name.
244	*
245	* @access public
246	*
247	* @param string $option Name of option to remove.
248	*/
249	public function delete_option( $option );
250
251	/**
252	* Change the info of the current theme.
253	*
254	* @access public
255	*
256	* @param array $theme_info Theme info array.
257	*/
258	public function set_theme_info( $theme_info );
259
260	/**
261	* Whether the current theme supports a certain feature.
262	*
263	* @access public
264	*
265	* @param string $feature Name of the feature.
266	*/
267	public function current_theme_supports( $feature );
268
269	/**
270	* Retrieve metadata for the specified object.
271	*
272	* @access public
273	*
274	* @param string $type      Meta type.
275	* @param int    $object_id ID of the object.
276	* @param string $meta_key  Meta key.
277	* @param bool   $single    If true, return only the first value of the specified meta_key.
278	*/
279	public function get_metadata( $type, $object_id, $meta_key = '', $single = false );
280
281	/**
282	* Stores remote meta key/values alongside an ID mapping key.
283	*
284	* @access public
285	*
286	* @param string $type       Meta type.
287	* @param int    $object_id  ID of the object.
288	* @param string $meta_key   Meta key.
289	* @param mixed  $meta_value Meta value.
290	* @param int    $meta_id    ID of the meta.
291	*/
292	public function upsert_metadata( $type, $object_id, $meta_key, $meta_value, $meta_id );
293
294	/**
295	* Delete metadata for the specified object.
296	*
297	* @access public
298	*
299	* @param string $type      Meta type.
300	* @param int    $object_id ID of the object.
301	* @param array  $meta_ids  IDs of the meta objects to delete.
302	*/
303	public function delete_metadata( $type, $object_id, $meta_ids );
304
305	/**
306	* Delete metadata with a certain key for the specified objects.
307	*
308	* @access public
309	*
310	* @param string $type       Meta type.
311	* @param array  $object_ids IDs of the objects.
312	* @param string $meta_key   Meta key.
313	*/
314	public function delete_batch_metadata( $type, $object_ids, $meta_key );
315
316	/**
317	* Delete metadata with a certain key and value for all objects.
318	*
319	* @access public
320	*
321	* @param string $type       Meta type.
322	* @param string $meta_key   Meta key.
323	* @param mixed  $meta_value Meta value to match.
324	*/
325	public function delete_metadata_by_key_value( $type, $meta_key, $meta_value );
326
327	/**
328	* Retrieve value of a constant based on the constant name.
329	*
330	* @access public
331	*
332	* @param string $constant Name of constant to retrieve.
333	*/
334	public function get_constant( $constant );
335
336	/**
337	* Set the value of a constant.
338	*
339	* @access public
340	*
341	* @param string $constant Name of constant to retrieve.
342	* @param mixed  $value    Value set for the constant.
343	*/
344	public function set_constant( $constant, $value );
345
346	/**
347	* Retrieve the number of the available updates of a certain type.
348	* Type is one of: `plugins`, `themes`, `wordpress`, `translations`, `total`, `wp_update_version`.
349	*
350	* @access public
351	*
352	* @param string $type Type of updates to retrieve.
353	*/
354	public function get_updates( $type );
355
356	/**
357	* Set the available updates of a certain type.
358	* Type is one of: `plugins`, `themes`, `wordpress`, `translations`, `total`, `wp_update_version`.
359	*
360	* @access public
361	*
362	* @param string $type    Type of updates to set.
363	* @param int    $updates Total number of updates.
364	*/
365	public function set_updates( $type, $updates );
366
367	/**
368	* Retrieve a callable value based on its name.
369	*
370	* @access public
371	*
372	* @param string $callable Name of the callable to retrieve.
373	*/
374	public function get_callable( $callable );
375
376	/**
377	* Update the value of a callable.
378	*
379	* @access public
380	*
381	* @param string $callable Callable name.
382	* @param mixed  $value    Callable value.
383	*/
384	public function set_callable( $callable, $value );
385
386	/**
387	* Retrieve a network option value based on a network option name.
388	*
389	* @access public
390	*
391	* @param string $option Name of network option to retrieve.
392	*/
393	public function get_site_option( $option );
394
395	/**
396	* Update the value of a network option.
397	*
398	* @access public
399	*
400	* @param string $option Network option name.
401	* @param mixed  $value  Network option value.
402	*/
403	public function update_site_option( $option, $value );
404
405	/**
406	* Remove a network option by name.
407	*
408	* @access public
409	*
410	* @param string $option Name of option to remove.
411	*/
412	public function delete_site_option( $option );
413
414	/**
415	* Retrieve the terms from a particular taxonomy.
416	*
417	* @access public
418	*
419	* @param string $taxonomy Taxonomy slug.
420	*/
421	public function get_terms( $taxonomy );
422
423	/**
424	* Retrieve a particular term.
425	*
426	* @access public
427	*
428	* @param string|false $taxonomy   Taxonomy slug.
429	* @param int          $term_id    ID of the term.
430	* @param string       $term_key   ID Field `term_id` or `term_taxonomy_id`.
431	*/
432	public function get_term( $taxonomy, $term_id, $term_key = 'term_id' );
433
434	/**
435	* Insert or update a term.
436	*
437	* @access public
438	*
439	* @param \WP_Term $term_object Term object.
440	*/
441	public function update_term( $term_object );
442
443	/**
444	* Delete a term by the term ID and its corresponding taxonomy.
445	*
446	* @access public
447	*
448	* @param int    $term_id  Term ID.
449	* @param string $taxonomy Taxonomy slug.
450	*/
451	public function delete_term( $term_id, $taxonomy );
452
453	/**
454	* Retrieve all terms from a taxonomy that are related to an object with a particular ID.
455	*
456	* @access public
457	*
458	* @param int    $object_id Object ID.
459	* @param string $taxonomy  Taxonomy slug.
460	*/
461	public function get_the_terms( $object_id, $taxonomy );
462
463	/**
464	* Add/update terms of a particular taxonomy of an object with the specified ID.
465	*
466	* @access public
467	*
468	* @param int              $object_id The object to relate to.
469	* @param string           $taxonomy  The context in which to relate the term to the object.
470	* @param string|int|array $terms     A single term slug, single term id, or array of either term slugs or ids.
471	* @param bool             $append    Optional. If false will delete difference of terms. Default false.
472	*/
473	public function update_object_terms( $object_id, $taxonomy, $terms, $append );
474
475	/**
476	* Remove certain term relationships from the specified object.
477	*
478	* @access public
479	*
480	* @todo Refactor to not use interpolated values when preparing the SQL query.
481	*
482	* @param int   $object_id ID of the object.
483	* @param array $tt_ids    Term taxonomy IDs.
484	*/
485	public function delete_object_terms( $object_id, $tt_ids );
486
487	/**
488	* Retrieve the number of users.
489	*
490	* @access public
491	*/
492	public function user_count();
493
494	/**
495	* Retrieve a user object by the user ID.
496	*
497	* @access public
498	*
499	* @param int $user_id User ID.
500	* @return \WP_User|null User object, or `null` if user invalid/not found.
501	*/
502	public function get_user( $user_id );
503
504	/**
505	* Insert or update a user.
506	*
507	* @access public
508	*
509	* @param \WP_User $user User object.
510	*/
511	public function upsert_user( $user );
512
513	/**
514	* Delete a user.
515	*
516	* @access public
517	*
518	* @param int $user_id User ID.
519	*/
520	public function delete_user( $user_id );
521
522	/**
523	* Update/insert user locale.
524	*
525	* @access public
526	*
527	* @param int    $user_id User ID.
528	* @param string $locale  The user locale.
529	*/
530	public function upsert_user_locale( $user_id, $locale );
531
532	/**
533	* Delete user locale.
534	*
535	* @access public
536	*
537	* @param int $user_id User ID.
538	*/
539	public function delete_user_locale( $user_id );
540
541	/**
542	* Retrieve the user locale.
543	*
544	* @access public
545	*
546	* @param int $user_id User ID.
547	*/
548	public function get_user_locale( $user_id );
549
550	/**
551	* Retrieve the allowed mime types for the user.
552	*
553	* @access public
554	*
555	* @param int $user_id User ID.
556	*/
557	public function get_allowed_mime_types( $user_id );
558
559	/**
560	* Retrieve all the checksums we are interested in.
561	* Currently that is posts, comments, post meta and comment meta.
562	*
563	* @access public
564	*/
565	public function checksum_all();
566
567	/**
568	* Retrieve the checksum histogram for a specific object type.
569	*
570	* @access public
571	*
572	* @param string $object_type Object type.
573	* @param int    $buckets     Number of buckets to split the objects to.
574	* @param int    $start_id    Minimum object ID.
575	* @param int    $end_id      Maximum object ID.
576	*/
577	public function checksum_histogram( $object_type, $buckets, $start_id = null, $end_id = null );
578	}