code-snippets / php / REST_API / Preferences / Demos_Seen_REST_Controller.php

Demos_Seen_REST_Controller.php in Code Snippets trunk, at php/REST_API/Preferences/Demos_Seen_REST_Controller.php

120 lines 3.2 KB

Raw Download Zip

1	<?php
2
3	namespace Code_Snippets\REST_API\Preferences;
4
5	use WP_REST_Request;
6	use WP_REST_Response;
7
8	/**
9	* Controller for recording which feature demos have been watched through to the end.
10	*
11	* Unlike the other preferences, this one accumulates: the stored value is the list of
12	* demos already seen, while an update names the single demo just watched and is appended
13	* to that list. Appending on the server keeps concurrent recordings from clobbering each
14	* other, so the read and write keys differ.
15	*
16	* @package Code_Snippets
17	*/
18	final class Demos_Seen_REST_Controller extends Preference_REST_Controller {
19
20	/**
21	* Current API version.
22	*/
23	public const VERSION = 1;
24
25	/**
26	* The base suffix of this controller's route.
27	*/
28	public const BASE_ROUTE = 'demos-seen';
29
30	/**
31	* The key naming the demo watched, used when updating the preference.
32	*/
33	protected const PREFERENCE_KEY = 'demo';
34
35	/**
36	* The key listing the demos watched, used when reading the preference.
37	*/
38	protected const RESPONSE_KEY = 'demos';
39
40	/**
41	* The name of the option recording which feature demos have been watched.
42	*/
43	public const OPTION_NAME = 'code_snippets_demos_seen';
44
45	/**
46	* Feature demos whose completion is recorded.
47	*/
48	public const DEMOS = [ 'ai-agent', 'blueprints' ];
49
50	/**
51	* Retrieve the feature demos that have been watched through to the end.
52	*
53	* @return string[]
54	*/
55	public static function get_demos_seen(): array {
56	$seen = get_option( self::OPTION_NAME, [] );
57
58	return is_array( $seen ) ? array_values( array_intersect( self::DEMOS, $seen ) ) : [];
59	}
60
61	/**
62	* Forget which feature demos have been watched, so their toolbar tabs
63	* announce themselves as new again.
64	*
65	* @return void
66	*/
67	public static function reset_demos_seen(): void {
68	delete_option( self::OPTION_NAME );
69	}
70
71	/**
72	* Retrieve the stored preference value, discarding any unrecognized demo names.
73	*
74	* @return string[]
75	*/
76	protected function get_option_value(): array {
77	return self::get_demos_seen();
78	}
79
80	/**
81	* Get the schema for the update request argument.
82	*
83	* @return array The schema for the update request argument.
84	*/
85	protected function get_update_request_schema(): array {
86	return [
87	'description' => esc_html__( 'Identifier of the feature demo that has been watched.', 'code-snippets' ),
88	'type' => 'string',
89	'enum' => self::DEMOS,
90	'required' => true,
91	];
92	}
93
94	/**
95	* Retrieve the demos watched so far as a REST response.
96	*
97	* @return WP_REST_Response
98	*/
99	public function get_option_value_callback(): WP_REST_Response {
100	return new WP_REST_Response( [ self::RESPONSE_KEY => $this->get_option_value() ] );
101	}
102
103	/**
104	* Record that a feature demo has been watched through to the end.
105	*
106	* @param WP_REST_Request $request Full data about the request.
107	*
108	* @return WP_REST_Response
109	*/
110	public function update_option_value_callback( WP_REST_Request $request ): WP_REST_Response {
111	$demos = self::get_demos_seen();
112	$demos[] = $request->get_param( self::PREFERENCE_KEY );
113
114	$demos = array_values( array_intersect( self::DEMOS, array_unique( $demos ) ) );
115	update_option( self::OPTION_NAME, $demos );
116
117	return new WP_REST_Response( [ self::RESPONSE_KEY => $demos ] );
118	}
119	}
120