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	* Retrieve value of a constant based on the constant name.
318	*
319	* @access public
320	*
321	* @param string $constant Name of constant to retrieve.
322	*/
323	public function get_constant( $constant );
324
325	/**
326	* Set the value of a constant.
327	*
328	* @access public
329	*
330	* @param string $constant Name of constant to retrieve.
331	* @param mixed  $value    Value set for the constant.
332	*/
333	public function set_constant( $constant, $value );
334
335	/**
336	* Retrieve the number of the available updates of a certain type.
337	* Type is one of: `plugins`, `themes`, `wordpress`, `translations`, `total`, `wp_update_version`.
338	*
339	* @access public
340	*
341	* @param string $type Type of updates to retrieve.
342	*/
343	public function get_updates( $type );
344
345	/**
346	* Set the available updates of a certain type.
347	* Type is one of: `plugins`, `themes`, `wordpress`, `translations`, `total`, `wp_update_version`.
348	*
349	* @access public
350	*
351	* @param string $type    Type of updates to set.
352	* @param int    $updates Total number of updates.
353	*/
354	public function set_updates( $type, $updates );
355
356	/**
357	* Retrieve a callable value based on its name.
358	*
359	* @access public
360	*
361	* @param string $callable Name of the callable to retrieve.
362	*/
363	public function get_callable( $callable );
364
365	/**
366	* Update the value of a callable.
367	*
368	* @access public
369	*
370	* @param string $callable Callable name.
371	* @param mixed  $value    Callable value.
372	*/
373	public function set_callable( $callable, $value );
374
375	/**
376	* Retrieve a network option value based on a network option name.
377	*
378	* @access public
379	*
380	* @param string $option Name of network option to retrieve.
381	*/
382	public function get_site_option( $option );
383
384	/**
385	* Update the value of a network option.
386	*
387	* @access public
388	*
389	* @param string $option Network option name.
390	* @param mixed  $value  Network option value.
391	*/
392	public function update_site_option( $option, $value );
393
394	/**
395	* Remove a network option by name.
396	*
397	* @access public
398	*
399	* @param string $option Name of option to remove.
400	*/
401	public function delete_site_option( $option );
402
403	/**
404	* Retrieve the terms from a particular taxonomy.
405	*
406	* @access public
407	*
408	* @param string $taxonomy Taxonomy slug.
409	*/
410	public function get_terms( $taxonomy );
411
412	/**
413	* Retrieve a particular term.
414	*
415	* @access public
416	*
417	* @param string|false $taxonomy   Taxonomy slug.
418	* @param int          $term_id    ID of the term.
419	* @param string       $term_key   ID Field `term_id` or `term_taxonomy_id`.
420	*/
421	public function get_term( $taxonomy, $term_id, $term_key = 'term_id' );
422
423	/**
424	* Insert or update a term.
425	*
426	* @access public
427	*
428	* @param \WP_Term $term_object Term object.
429	*/
430	public function update_term( $term_object );
431
432	/**
433	* Delete a term by the term ID and its corresponding taxonomy.
434	*
435	* @access public
436	*
437	* @param int    $term_id  Term ID.
438	* @param string $taxonomy Taxonomy slug.
439	*/
440	public function delete_term( $term_id, $taxonomy );
441
442	/**
443	* Retrieve all terms from a taxonomy that are related to an object with a particular ID.
444	*
445	* @access public
446	*
447	* @param int    $object_id Object ID.
448	* @param string $taxonomy  Taxonomy slug.
449	*/
450	public function get_the_terms( $object_id, $taxonomy );
451
452	/**
453	* Add/update terms of a particular taxonomy of an object with the specified ID.
454	*
455	* @access public
456	*
457	* @param int              $object_id The object to relate to.
458	* @param string           $taxonomy  The context in which to relate the term to the object.
459	* @param string|int|array $terms     A single term slug, single term id, or array of either term slugs or ids.
460	* @param bool             $append    Optional. If false will delete difference of terms. Default false.
461	*/
462	public function update_object_terms( $object_id, $taxonomy, $terms, $append );
463
464	/**
465	* Remove certain term relationships from the specified object.
466	*
467	* @access public
468	*
469	* @todo Refactor to not use interpolated values when preparing the SQL query.
470	*
471	* @param int   $object_id ID of the object.
472	* @param array $tt_ids    Term taxonomy IDs.
473	*/
474	public function delete_object_terms( $object_id, $tt_ids );
475
476	/**
477	* Retrieve the number of users.
478	*
479	* @access public
480	*/
481	public function user_count();
482
483	/**
484	* Retrieve a user object by the user ID.
485	*
486	* @access public
487	*
488	* @param int $user_id User ID.
489	* @return \WP_User|null User object, or `null` if user invalid/not found.
490	*/
491	public function get_user( $user_id );
492
493	/**
494	* Insert or update a user.
495	*
496	* @access public
497	*
498	* @param \WP_User $user User object.
499	*/
500	public function upsert_user( $user );
501
502	/**
503	* Delete a user.
504	*
505	* @access public
506	*
507	* @param int $user_id User ID.
508	*/
509	public function delete_user( $user_id );
510
511	/**
512	* Update/insert user locale.
513	*
514	* @access public
515	*
516	* @param int    $user_id User ID.
517	* @param string $locale  The user locale.
518	*/
519	public function upsert_user_locale( $user_id, $locale );
520
521	/**
522	* Delete user locale.
523	*
524	* @access public
525	*
526	* @param int $user_id User ID.
527	*/
528	public function delete_user_locale( $user_id );
529
530	/**
531	* Retrieve the user locale.
532	*
533	* @access public
534	*
535	* @param int $user_id User ID.
536	*/
537	public function get_user_locale( $user_id );
538
539	/**
540	* Retrieve the allowed mime types for the user.
541	*
542	* @access public
543	*
544	* @param int $user_id User ID.
545	*/
546	public function get_allowed_mime_types( $user_id );
547
548	/**
549	* Retrieve all the checksums we are interested in.
550	* Currently that is posts, comments, post meta and comment meta.
551	*
552	* @access public
553	*/
554	public function checksum_all();
555
556	/**
557	* Retrieve the checksum histogram for a specific object type.
558	*
559	* @access public
560	*
561	* @param string $object_type Object type.
562	* @param int    $buckets     Number of buckets to split the objects to.
563	* @param int    $start_id    Minimum object ID.
564	* @param int    $end_id      Maximum object ID.
565	*/
566	public function checksum_histogram( $object_type, $buckets, $start_id = null, $end_id = null );
567	}