wp-parsely / src / services / suggestions-api / endpoints / class-endpoint-suggest-linked-reference.php

class-endpoint-suggest-linked-reference.php in Parse.ly 3.24.2, at src/services/suggestions-api/endpoints/class-endpoint-suggest-linked-reference.php

112 lines 2.9 KB

Raw Download Zip

1	<?php
2	/**
3	* Parse.ly Suggestions API Endpoint: Suggest Linked Reference
4	*
5	* @package Parsely
6	* @since 3.17.0
7	*/
8
9	declare(strict_types=1);
10
11	namespace Parsely\Services\Suggestions_API\Endpoints;
12
13	use Parsely\Models\Smart_Link;
14	use WP_Error;
15
16	/**
17	* The endpoint for the Suggest Linked Reference (Smart Links) API request.
18	*
19	* @since 3.17.0
20	*
21	* @phpstan-type Traffic_Source = array{
22	* source: string,
23	* weight: float
24	* }
25	*
26	* @phpstan-type Endpoint_Suggest_Linked_Reference_Options = array{
27	* max_items?: int,
28	* max_link_words?: int,
29	* traffic_sources?: array<int, Traffic_Source>,
30	* url_exclusion_list?: array<string>
31	* }
32	*/
33	class Endpoint_Suggest_Linked_Reference extends Suggestions_API_Base_Endpoint {
34	/**
35	* Returns the endpoint for the API request.
36	*
37	* @since 3.17.0
38	*
39	* @return string The endpoint for the API request.
40	*/
41	public function get_endpoint(): string {
42	return '/suggest-linked-reference';
43	}
44
45	/**
46	* Gets suggested smart links for the given content using the Parse.ly
47	* Content Suggestion API.
48	*
49	* @since 3.14.0
50	* @since 3.17.0 Updated to use the new API service.
51	*
52	* @param string $content The content to generate links for.
53	* @param Endpoint_Suggest_Linked_Reference_Options $options The options to pass to the API request.
54	* @return array<Smart_Link>\|WP_Error The response from the remote API, or a WP_Error
55	* object if the response is an error.
56	*/
57	public function get_links(
58	string $content,
59	$options = array()
60	) {
61	$request_body = array(
62	'output_config' => array(
63	'max_link_words' => $options['max_link_words'] ?? 4,
64	'max_items' => $options['max_items'] ?? 10,
65	),
66	'text' => wp_strip_all_tags( $content ),
67	);
68
69	if ( isset( $options['url_exclusion_list'] ) && count( $options['url_exclusion_list'] ) > 0 ) {
70	$request_body['url_exclusion_list'] = $options['url_exclusion_list'];
71	}
72
73	$response = $this->request( 'POST', array(), $request_body );
74
75	if ( is_wp_error( $response ) ) {
76	return $response;
77	}
78
79	// Convert the links to Smart_Link objects.
80	$links = array();
81	foreach ( $response as $link ) {
82	$link = apply_filters( 'wp_parsely_suggest_linked_reference_link', $link );
83	$link_obj = new Smart_Link(
84	esc_url( $link['canonical_url'] ),
85	esc_attr( $link['title'] ),
86	wp_kses_post( $link['text'] ),
87	$link['offset']
88	);
89	$links[] = $link_obj;
90	}
91
92	return $links;
93	}
94
95	/**
96	* Executes the API request.
97	*
98	* @since 3.17.0
99	*
100	* @param array<mixed> $args The arguments to pass to the API request.
101	* @return WP_Error\|array<mixed> The response from the API.
102	*/
103	public function call( array $args = array() ) {
104	/** @var string $content */
105	$content = $args['content'] ?? '';
106	/** @var Endpoint_Suggest_Linked_Reference_Options $options */
107	$options = $args['options'] ?? array();
108
109	return $this->get_links( $content, $options );
110	}
111	}
112