wp-parsely / src / services / content-api / class-content-api-service.php

class-content-api-service.php in Parse.ly 3.17.0, at src/services/content-api/class-content-api-service.php

235 lines 6.5 KB

Raw Download Zip

1	<?php
2	/**
3	* Parse.ly Content API Service class.
4	*
5	* @package Parsely
6	* @since 3.17.0
7	*/
8
9	declare(strict_types=1);
10
11	namespace Parsely\Services\Content_API;
12
13	use Parsely\Services\Base_API_Service;
14	use Parsely\Services\Base_Service_Endpoint;
15	use WP_Error;
16
17	/**
18	* The Parse.ly Content API Service class.
19	*
20	* This class is responsible for handling the API requests to the Parse.ly Content API.
21	*
22	* @since 3.17.0
23	*/
24	class Content_API_Service extends Base_API_Service {
25	/**
26	* Returns the base URL for the Parse.ly Content API, aka Public API.
27	*
28	* @since 3.17.0
29	*
30	* @return string
31	*/
32	public static function get_base_url(): string {
33	return 'https://api.parsely.com/v2';
34	}
35
36	/**
37	* Registers the endpoints for the Parse.ly Content API.
38	*
39	* @since 3.17.0
40	*/
41	protected function register_endpoints(): void {
42	/**
43	* The endpoints for the Parse.ly Content API.
44	*
45	* @var array<Base_Service_Endpoint> $endpoints
46	*/
47	$endpoints = array(
48	new Endpoints\Endpoint_Validate( $this ),
49	);
50
51	foreach ( $endpoints as $endpoint ) {
52	$this->register_endpoint( $endpoint );
53	}
54
55	/**
56	* The cached endpoints.
57	*
58	* The second element in the array is the time-to-live for the cache, in seconds.
59	*
60	* @var array<array{0: Base_Service_Endpoint, 1: int}> $cached_endpoints
61	*/
62	$cached_endpoints = array(
63	array( new Endpoints\Endpoint_Analytics_Posts( $this ), 300 ), // 5 minutes.
64	array( new Endpoints\Endpoint_Related( $this ), 600 ), // 10 minutes.
65	array( new Endpoints\Endpoint_Referrers_Post_Detail( $this ), 300 ), // 5 minutes.
66	array( new Endpoints\Endpoint_Analytics_Post_Details( $this ), 300 ), // 5 minutes.
67	);
68
69	foreach ( $cached_endpoints as $cached_endpoint ) {
70	$this->register_cached_endpoint( $cached_endpoint[0], $cached_endpoint[1] );
71	}
72	}
73
74	/**
75	* Returns the post’s metadata, as well as total views and visitors in the metrics field.
76	*
77	* By default, this returns the total pageviews on the link for the last 90 days.
78	*
79	* @since 3.17.0
80	*
81	* @link https://docs.parse.ly/api-analytics-endpoint/#2-get-analytics-post-detail
82	*
83	* @param string $url The URL of the post.
84	* @param string\|null $period_start The start date of the period to get the data for.
85	* @param string\|null $period_end The end date of the period to get the data for.
86	* @return array<mixed>\|WP_Error Returns the post details or a WP_Error object in case of an error.
87	*/
88	public function get_post_details(
89	string $url,
90	?string $period_start = null,
91	?string $period_end = null
92	) {
93	/** @var Endpoints\Endpoint_Analytics_Post_Details $endpoint */
94	$endpoint = $this->get_endpoint( '/analytics/post/detail' );
95
96	$args = array(
97	'url' => $url,
98	'period_start' => $period_start,
99	'period_end' => $period_end,
100	);
101
102	return $endpoint->call( $args );
103	}
104
105	/**
106	* Returns the referrers for a given post URL.
107	*
108	* @since 3.17.0
109	*
110	* @link https://docs.parse.ly/api-referrers-endpoint/#3-get-referrers-post-detail
111	*
112	* @param string $url The URL of the post.
113	* @param string\|null $period_start The start date of the period to get the data for.
114	* @param string\|null $period_end The end date of the period to get the data for.
115	* @return array<mixed>\|WP_Error Returns the referrers or a WP_Error object in case of an error.
116	*/
117	public function get_post_referrers(
118	string $url,
119	?string $period_start = null,
120	?string $period_end = null
121	) {
122	/** @var Endpoints\Endpoint_Referrers_Post_Detail $endpoint */
123	$endpoint = $this->get_endpoint( '/referrers/post/detail' );
124
125	$args = array(
126	'url' => $url,
127	'period_start' => $period_start,
128	'period_end' => $period_end,
129	);
130
131	return $endpoint->call( $args );
132	}
133
134	/**
135	* Returns the related posts for a given URL.
136	*
137	* @since 3.17.0
138	*
139	* @link https://docs.parse.ly/content-recommendations/#h-get-related
140	*
141	* @param string $url The URL of the post.
142	* @param array<string,mixed> $params The parameters to pass to the API request.
143	* @return array<mixed>\|WP_Error Returns the related posts or a WP_Error object in case of an error.
144	*/
145	public function get_related_posts_with_url( string $url, array $params = array() ) {
146	/** @var Endpoints\Endpoint_Related $endpoint */
147	$endpoint = $this->get_endpoint( '/related' );
148
149	$args = array(
150	'url' => $url,
151	);
152
153	// Merge the optional params.
154	$args = array_merge( $params, $args );
155
156	return $endpoint->call( $args );
157	}
158
159	/**
160	* Returns the related posts for a given UUID.
161	*
162	* @since 3.17.0
163	*
164	* @link https://docs.parse.ly/content-recommendations/#h-get-related
165	*
166	* @param string $uuid The UUID of the user.
167	* @param array<string,mixed> $params The parameters to pass to the API request.
168	* @return array<mixed>\|WP_Error Returns the related posts or a WP_Error object in case of an error.
169	*/
170	public function get_related_posts_with_uuid( string $uuid, array $params = array() ) {
171	/** @var Endpoints\Endpoint_Related $endpoint */
172	$endpoint = $this->get_endpoint( '/related' );
173
174	$args = array(
175	'uuid' => $uuid,
176	);
177
178	// Merge the optional params.
179	$args = array_merge( $params, $args );
180
181	return $endpoint->call( $args );
182	}
183
184	/**
185	* Returns the posts analytics.
186	*
187	* @since 3.17.0
188	*
189	* @link https://docs.parse.ly/api-analytics-endpoint/#1-get-analytics-posts
190	*
191	* @param array<string,mixed> $params The parameters to pass to the API request.
192	* @return array<mixed>\|WP_Error Returns the posts analytics or a WP_Error object in case of an error.
193	*/
194	public function get_posts( array $params = array() ) {
195	/** @var Endpoints\Endpoint_Analytics_Posts $endpoint */
196	$endpoint = $this->get_endpoint( '/analytics/posts' );
197
198	return $endpoint->call( $params );
199	}
200
201	/**
202	* Validates the Parse.ly API credentials.
203	*
204	* The API will return a 200 response if the credentials are valid and a 401 response if they are not.
205	*
206	* @since 3.17.0
207	*
208	* @param string $api_key The API key to validate.
209	* @param string $secret_key The secret key to validate.
210	* @return bool\|WP_Error Returns true if the credentials are valid, false otherwise.
211	*/
212	public function validate_credentials( string $api_key, string $secret_key ) {
213	/** @var Endpoints\Endpoint_Validate $endpoint */
214	$endpoint = $this->get_endpoint( '/validate/secret' );
215
216	$args = array(
217	'apikey' => $api_key,
218	'secret' => $secret_key,
219	);
220
221	$response = $endpoint->call( $args );
222
223	if ( is_wp_error( $response ) ) {
224	/** @var WP_Error $response */
225	return $response;
226	}
227
228	if ( true === $response['success'] ) {
229	return true;
230	}
231
232	return false;
233	}
234	}
235