wp-parsely / src / services / content-api / endpoints / class-endpoint-analytics-posts.php

class-endpoint-analytics-posts.php in Parse.ly 3.24.2, at src/services/content-api/endpoints/class-endpoint-analytics-posts.php

186 lines 4.6 KB

Raw Download Zip

1	<?php
2	/**
3	* Parse.ly Content API Endpoint: Analytics Posts
4	*
5	* @package Parsely
6	* @since 3.17.0
7	*/
8
9	declare(strict_types=1);
10
11	namespace Parsely\Services\Content_API\Endpoints;
12
13	use WP_Error;
14
15	/**
16	* The endpoint for the /analytics/posts API request.
17	*
18	* @since 3.17.0
19	*
20	* @link https://docs.parse.ly/api-analytics-endpoint/#0-get-analytics-type-
21	*
22	* @phpstan-type Analytics_Posts_API_Params array{
23	* apikey?: string,
24	* secret?: string,
25	* period_start?: string,
26	* period_end?: string,
27	* pub_date_start?: string,
28	* pub_date_end?: string,
29	* sort?: string,
30	* limit?: int<0, 2000>,
31	* }
32	*
33	* @phpstan-type Analytics_Post array{
34	* title?: string,
35	* url?: string,
36	* link?: string,
37	* author?: string,
38	* authors?: string[],
39	* section?: string,
40	* tags?: string[],
41	* metrics?: Analytics_Post_Metrics,
42	* full_content_word_count?: int,
43	* image_url?: string,
44	* metadata?: string,
45	* pub_date?: string,
46	* thumb_url_medium?: string,
47	* }
48	*
49	* @phpstan-type Analytics_Post_Metrics array{
50	* avg_engaged?: float,
51	* views?: int,
52	* visitors?: int,
53	* }
54	*/
55	class Endpoint_Analytics_Posts extends Content_API_Base_Endpoint {
56	private const MAX_RECORDS_LIMIT = 2000;
57	private const ANALYTICS_API_DAYS_LIMIT = 7;
58
59	/**
60	* Maximum limit for the number of records to return, to be
61	* used in the limit parameter.
62	*
63	* @since 3.17.0
64	*
65	* @var string
66	*/
67	public const MAX_LIMIT = 'max';
68
69	/**
70	* Maximum period for the API request, to be used in the period_start parameter.
71	*
72	* @since 3.17.0
73	*
74	* @var string
75	*/
76	public const MAX_PERIOD = 'max_days';
77
78	/**
79	* Returns the endpoint for the API request.
80	*
81	* @since 3.17.0
82	*
83	* @return string
84	*/
85	public function get_endpoint(): string {
86	return '/analytics/posts';
87	}
88
89	/**
90	* Returns the endpoint URL for the API request.
91	*
92	* This function supports repeating keys in the URL, which is a Parse.ly API
93	* requirement for specifying multiple values (e.g. tag=tag1&tag=tag2).
94	*
95	* @since 3.17.0
96	*
97	* @param array<mixed> $query_args The arguments to pass to the API request.
98	* @return string The endpoint URL for the API request.
99	*/
100	public function get_endpoint_url( array $query_args = array() ): string {
101	// Store the values of the parameters requiring repeating keys.
102	/** @var array<string> $tags */
103	$tags = $query_args['tag'] ?? array();
104
105	/** @var array<string> $urls */
106	$urls = $query_args['urls'] ?? array();
107
108	// Remove the parameters requiring repeating keys.
109	unset( $query_args['tag'] );
110	unset( $query_args['urls'] );
111
112	// Generate the endpoint URL.
113	$endpoint_url = parent::get_endpoint_url( $query_args );
114
115	// Append the parameters requiring repeating keys to the endpoint URL.
116	$endpoint_url = $this->append_same_key_params_to_url( $endpoint_url, $tags, 'tag' );
117	$endpoint_url = $this->append_same_key_params_to_url( $endpoint_url, $urls, 'url' );
118
119	return $endpoint_url;
120	}
121
122	/**
123	* Executes the API request.
124	*
125	* @since 3.17.0
126	*
127	* @param array<mixed> $args The arguments to pass to the API request.
128	* @return WP_Error\|array<mixed> The response from the API request.
129	*/
130	public function call( array $args = array() ) {
131	// Filter out the empty values.
132	$query_args = array_filter( $args );
133
134	// If the period_start is set to 'max_days', set it to the maximum days limit.
135	if ( isset( $query_args['period_start'] ) && self::MAX_PERIOD === $query_args['period_start'] ) {
136	$query_args['period_start'] = self::ANALYTICS_API_DAYS_LIMIT . 'd';
137	}
138
139	// If the limit is set to 'max' or greater than the maximum records limit,
140	// set it to the maximum records limit.
141	if ( isset( $query_args['limit'] ) && (
142	self::MAX_LIMIT === $query_args['limit'] \|\| $query_args['limit'] > self::MAX_RECORDS_LIMIT )
143	) {
144	$query_args['limit'] = self::MAX_RECORDS_LIMIT;
145	}
146
147	return $this->request( 'GET', $query_args );
148	}
149
150	/**
151	* Appends multiple parameters with the same key to the passed URL.
152	*
153	* @since 3.17.0
154	*
155	* @param string $url The URL to append the parameters to.
156	* @param array<string> $values The parameter values to append.
157	* @param string $key The common key to be used for the parameters.
158	* @return string The URL with the appended parameters.
159	*/
160	protected function append_same_key_params_to_url(
161	string $url,
162	array $values,
163	string $key
164	): string {
165	if ( '' === $key ) {
166	return $url;
167	}
168
169	foreach ( $values as $value ) {
170	if ( '' === $value ) {
171	continue;
172	}
173
174	$value = rawurlencode( $value );
175
176	if ( false === strpos( $url, '?' ) ) {
177	$url .= '?' . $key . '=' . $value;
178	} else {
179	$url .= '&' . $key . '=' . $value;
180	}
181	}
182
183	return $url;
184	}
185	}
186