code-snippets / php / Controller / Cloud_Search_Controller.php

Cloud_Search_Controller.php in Code Snippets 3.10.1, at php/Controller/Cloud_Search_Controller.php

176 lines 5.4 KB

Raw Download Zip

1	<?php
2
3	namespace Code_Snippets\Controller;
4
5	use Code_Snippets\Client\Cloud_Public_Client;
6	use Code_Snippets\Model\Basic_Cloud_Connection;
7	use Code_Snippets\Model\Cloud_Snippet;
8	use Code_Snippets\Model\Cloud_Snippets;
9	use Code_Snippets\Model\Snippet;
10	use WP_REST_Request;
11	use function Code_Snippets\save_snippet;
12
13	/**
14	* Controller for interfacing with public data on Code Snippets Cloud.
15	*/
16	class Cloud_Search_Controller {
17
18	/**
19	* Maximum number of cloud search results allowed per page.
20	*/
21	public const MAX_RESULTS_PER_PAGE = 100;
22
23	/**
24	* Minimum TTL in seconds for the featured snippets transient.
25	*/
26	private const FEATURED_MIN_TTL = 3600;
27
28	/**
29	* Option key holding the current featured-snippets cache version.
30	*
31	* Bumped on flush so old transient keys become unreachable and expire naturally.
32	*/
33	private const FEATURED_VERSION_OPTION = 'cs_featured_cache_version';
34
35	/**
36	* Transient key for cached featured snippets.
37	*/
38	private const FEATURED_TRANSIENT_KEY = 'cs_featured_snippets';
39
40	/**
41	* Cloud snippets client instance.
42	*
43	* @var Cloud_Public_Client
44	*/
45	private Cloud_Public_Client $client;
46
47	/**
48	* Class constructor.
49	*
50	* @param Basic_Cloud_Connection $connection Connection to Code Snippets Cloud.
51	*/
52	public function __construct( Basic_Cloud_Connection $connection ) {
53	$this->client = new Cloud_Public_Client( $connection );
54	}
55
56	/**
57	* Verify a REST API request is authorised to access controller functions.
58	*
59	* @param WP_REST_Request $request The REST API request.
60	*
61	* @return bool
62	*/
63	public function verify_rest_request( WP_REST_Request $request ): bool {
64	return $this->client->verify_rest_request( $request );
65	}
66
67	/**
68	* Refresh the cached synced data.
69	*
70	* Bumps the featured-cache version counter so previously cached keys
71	* become unreachable and expire via WordPress's normal transient path.
72	*
73	* @return void
74	*/
75	public static function clear_caches() {
76	delete_transient( self::FEATURED_VERSION_OPTION );
77	}
78
79	/**
80	* Retrieve a single cloud snippet from the API.
81	*
82	* @param int $cloud_id Remote cloud snippet ID.
83	*
84	* @return Cloud_Snippet Retrieved snippet.
85	*/
86	public function get_cloud_snippet( int $cloud_id ): ?Cloud_Snippet {
87	return $this->client->get_cloud_snippet( $cloud_id );
88	}
89
90	/**
91	* Search Code Snippets Cloud.
92	*
93	* @param string $search_method Search by name of codevault or keyword(s).
94	* @param string $search Search query.
95	* @param int $page Search result page to retrieve. Defaults to '1'.
96	* @param int $per_page Number of search results to retrieve per page.
97	* @param array<string,string> $filters Optional filters: category, type, status.
98	*
99	* @return Cloud_Snippets Result of search query.
100	*/
101	public function fetch_search_results( string $search_method, string $search, int $page = 1, int $per_page = 10, array $filters = [] ): ?Cloud_Snippets {
102	$per_page = min( self::MAX_RESULTS_PER_PAGE, $per_page );
103	return $this->client->fetch_search_results( $search_method, $search, $page, $per_page, $filters );
104	}
105
106	/**
107	* Download a snippet from the cloud.
108	*
109	* @param Cloud_Snippet $cloud_snippet The snippet to be downloaded.
110	*
111	* @return Snippet\|null The newly-created local snippet.
112	*/
113	public function download_snippet_from_cloud( Cloud_Snippet $cloud_snippet ): ?Snippet {
114	$snippet = new Snippet( $cloud_snippet );
115
116	// Set the snippet id to 0 to ensure that the snippet is saved as a new snippet.
117	$snippet->id = 0;
118	$snippet->active = 0;
119	$snippet->cloud_id = $cloud_snippet->id;
120	$snippet->is_cloud_owner = $cloud_snippet->is_owner;
121	$snippet->desc = $cloud_snippet->description ?? '';
122
123	return save_snippet( $snippet );
124	}
125
126	/**
127	* Build the transient key for a specific (version, page, per_page, filters) slot.
128	*
129	* @param int $page Page number (1-indexed).
130	* @param int $per_page Results per page.
131	* @param array<string,string> $filters Filter values.
132	*
133	* @return string
134	*/
135	private function build_featured_cache_key( int $page, int $per_page, array $filters ): string {
136	$encoded = wp_json_encode( array_filter( $filters ) );
137	$filter_hash = md5( false === $encoded ? '' : $encoded );
138
139	$version = get_transient( self::FEATURED_VERSION_OPTION );
140
141	if ( ! $version ) {
142	$version = (string) ( microtime( true ) * 1000 );
143	set_transient( self::FEATURED_VERSION_OPTION, $version, MONTH_IN_SECONDS );
144	}
145
146	return self::FEATURED_TRANSIENT_KEY . "_v{$version}_p{$page}_pp{$per_page}_$filter_hash";
147	}
148
149	/**
150	* Retrieve featured snippets from the cloud API, with transient caching.
151	*
152	* @param int $page Page number (1-indexed).
153	* @param int $per_page Results per page.
154	* @param array<string,string> $filters Optional filters: category, type, status.
155	*
156	* @return Cloud_Snippets Featured snippets, or an empty result on failure.
157	*/
158	public function get_featured_snippets( int $page = 1, int $per_page = 10, array $filters = [] ): ?Cloud_Snippets {
159	$cache_key = self::build_featured_cache_key( $page, $per_page, $filters );
160	$cached = get_transient( $cache_key );
161
162	if ( $cached instanceof Cloud_Snippets ) {
163	return $cached;
164	}
165
166	$per_page = min( self::MAX_RESULTS_PER_PAGE, max( 1, $per_page ) );
167	$result = $this->client->get_featured_snippets( $page, $per_page, $filters );
168
169	if ( $result ) {
170	set_transient( $cache_key, $result, self::FEATURED_MIN_TTL );
171	}
172
173	return $result;
174	}
175	}
176