wp-parsely / src / rest-api / content-helper / class-endpoint-excerpt-generator.php

class-endpoint-excerpt-generator.php in Parse.ly 3.24.2, at src/rest-api/content-helper/class-endpoint-excerpt-generator.php

202 lines 5.1 KB

Raw Download Zip

1	<?php
2	/**
3	* Endpoint: Excerpt Suggestions
4	* Parse.ly Content Intelligence `/excerpt-generator` API endpoint class
5	*
6	* @package Parsely
7	* @since 3.17.0
8	*/
9
10	declare(strict_types=1);
11
12	namespace Parsely\REST_API\Content_Helper;
13
14	use Parsely\REST_API\Base_Endpoint;
15	use Parsely\REST_API\Settings\Endpoint_Editor_Sidebar_Settings;
16	use Parsely\Services\Suggestions_API\Suggestions_API_Service;
17	use WP_Error;
18	use WP_REST_Request;
19	use WP_REST_Response;
20
21	/**
22	* The Excerpt Suggestions API.
23	*
24	* Provides an endpoint for generating excerpts for the given content.
25	*
26	* @since 3.17.0
27	*/
28	class Endpoint_Excerpt_Generator extends Base_Endpoint {
29	use Content_Helper_Feature;
30
31	/**
32	* The Suggestions API service.
33	*
34	* @since 3.17.0
35	*
36	* @var Suggestions_API_Service $suggestions_api
37	*/
38	protected $suggestions_api;
39
40	/**
41	* Initializes the class.
42	*
43	* @since 3.17.0
44	*
45	* @param Content_Helper_Controller $controller The Content Intelligence controller.
46	*/
47	public function __construct( Content_Helper_Controller $controller ) {
48	parent::__construct( $controller );
49	$this->suggestions_api = $controller->get_parsely()->get_suggestions_api();
50	}
51
52	/**
53	* Returns the name of the endpoint.
54	*
55	* @since 3.17.0
56	*
57	* @return string The endpoint's name.
58	*/
59	public static function get_endpoint_name(): string {
60	return 'excerpt-generator';
61	}
62
63	/**
64	* Returns the name of the feature associated with the current endpoint.
65	*
66	* @since 3.17.0
67	*
68	* @return string The feature's name.
69	*/
70	public function get_pch_feature_name(): string {
71	return 'excerpt_suggestions';
72	}
73
74	/**
75	* Registers the routes for the endpoint.
76	*
77	* @since 3.17.0
78	*/
79	public function register_routes(): void {
80	/**
81	* POST /excerpt-generator/generate
82	* Generates an excerpt for the given content.
83	*/
84	$this->register_rest_route(
85	'generate',
86	array( 'POST' ),
87	array( $this, 'generate_excerpt' ),
88	array(
89	'text' => array(
90	'description' => __( 'The text to generate the excerpt from.', 'wp-parsely' ),
91	'type' => 'string',
92	'required' => true,
93	),
94	'title' => array(
95	'description' => __( 'The title of the content.', 'wp-parsely' ),
96	'type' => 'string',
97	'required' => true,
98	),
99	'persona' => array(
100	'description' => __( 'The persona to use for the suggestion.', 'wp-parsely' ),
101	'type' => 'string',
102	'required' => false,
103	'default' => Endpoint_Editor_Sidebar_Settings::DEFAULT_EXCERPT_PERSONA,
104	),
105	'style' => array(
106	'description' => __( 'The style to use for the suggestion.', 'wp-parsely' ),
107	'type' => 'string',
108	'required' => false,
109	'default' => Endpoint_Editor_Sidebar_Settings::DEFAULT_EXCERPT_TONE,
110	),
111	'max_items' => array(
112	'description' => __( 'The maximum number of items to generate.', 'wp-parsely' ),
113	'type' => 'integer',
114	'required' => false,
115	'default' => 1,
116	),
117	'max_characters' => array(
118	'description' => __( 'The maximum number of characters to generate.', 'wp-parsely' ),
119	'type' => 'integer',
120	'required' => false,
121	'default' => Endpoint_Editor_Sidebar_Settings::DEFAULT_EXCERPT_LENGTH,
122	'minimum' => Endpoint_Editor_Sidebar_Settings::MIN_EXCERPT_LENGTH,
123	'maximum' => Endpoint_Editor_Sidebar_Settings::MAX_EXCERPT_LENGTH,
124	),
125	)
126	);
127	}
128
129	/**
130	* API Endpoint: POST /excerpt-generator/generate
131	*
132	* Generates an excerpt for the passed content.
133	*
134	* @since 3.17.0
135	*
136	* @param WP_REST_Request $request The request object.
137	* @return WP_REST_Response\|WP_Error The response object.
138	*/
139	public function generate_excerpt( WP_REST_Request $request ) {
140	/**
141	* The post content to be sent to the API.
142	*
143	* @var string $post_content
144	*/
145	$post_content = $request->get_param( 'text' );
146
147	/**
148	* The post title to be sent to the API.
149	*
150	* @var string $post_title
151	*/
152	$post_title = $request->get_param( 'title' );
153
154	/**
155	* The persona to be sent to the API.
156	*
157	* @var string $persona
158	*/
159	$persona = $request->get_param( 'persona' );
160
161	/**
162	* The style to be sent to the API.
163	*
164	* @var string $style
165	*/
166	$style = $request->get_param( 'style' );
167
168	/**
169	* The maximum number of items to generate.
170	*
171	* @var int $max_items
172	*/
173	$max_items = $request->get_param( 'max_items' );
174
175	/**
176	* The maximum number of characters to generate.
177	*
178	* @var int $max_characters
179	*/
180	$max_characters = $request->get_param( 'max_characters' );
181
182	$response = $this->suggestions_api->get_brief_suggestions(
183	$post_title,
184	$post_content,
185	array(
186	'persona' => $persona,
187	'style' => $style,
188	'max_items' => $max_items,
189	'max_characters' => $max_characters,
190	)
191	);
192
193	if ( is_wp_error( $response ) ) {
194	return $response;
195	}
196
197	// TODO: For now, only return the first suggestion. When the UI is ready to handle multiple suggestions, we can return the entire array.
198	$response = $response[0] ?? '';
199	return new WP_REST_Response( array( 'data' => $response ), 200 );
200	}
201	}
202