templately / modules / library-tour / REST / Tour.php

Tour.php in Templately – Elementor & Gutenberg Template Library: 6500+ Free & Pro Ready Templates And Cloud! 3.8.0, at modules/library-tour/REST/Tour.php

135 lines 3.7 KB

Raw Download Zip

1	<?php
2
3	namespace Templately\Modules\LibraryTour\REST;
4
5	use Templately\API\API;
6
7	class Tour extends API {
8
9	private static $tour_meta_key = 'tour_status';
10
11	/**
12	* Server-side allowlist of legal tour keys (spec 036 FR-017).
13	*
14	* `mark_complete()` and `reset()` reject any `tour_key` that is not present
15	* here with an HTTP 400 `invalid_tour_key` error, so arbitrary strings can
16	* never be written into (or targeted inside) the per-user `tour_status`
17	* option. This is the AUTHORITATIVE, server-side source of truth for which
18	* tours exist.
19	*
20	* KEEP IN SYNC with the frontend key constants in
21	* `modules/library-tour/assets/js/tourSteps.js`
22	* (`LIBRARY_TOUR_KEY` / `DETAIL_TOUR_KEY`) — the two runtimes cannot share a
23	* literal, so when a tour key is added, renamed, or its `_vN` suffix bumped,
24	* both lists must be updated together. Tests assert the exact membership of
25	* this list.
26	*
27	* @var string[]
28	*/
29	const ALLOWED_TOUR_KEYS = [
30	'templately_library_tour_v1',
31	'templately_detail_tour_v1',
32	];
33
34	public function register_routes() {
35	$this->get( 'tour/status', [ $this, 'get_status' ] );
36	$this->post( 'tour/complete', [ $this, 'mark_complete' ] );
37	$this->post( 'tour/reset', [ $this, 'reset' ] );
38	}
39
40	/**
41	* Whether a tour key is present in the server-side allowlist.
42	*
43	* @param mixed $tour_key
44	* @return bool
45	*/
46	private function is_allowed_tour_key( $tour_key ): bool {
47	return in_array( $tour_key, self::ALLOWED_TOUR_KEYS, true );
48	}
49
50	/**
51	* Get the current tour completion status.
52	*
53	* @return \WP_REST_Response
54	*/
55	public function get_status() {
56	$status = $this->utils( 'options' )->get( self::$tour_meta_key, [] );
57
58	if ( ! is_array( $status ) ) {
59	$status = [];
60	}
61
62	return $this->success( $status );
63	}
64
65	/**
66	* Mark a tour as complete.
67	*
68	* Expects a `tour_key` parameter (e.g. "templately_library_tour_v1").
69	*
70	* @return \WP_REST_Response\|\WP_Error
71	*/
72	public function mark_complete() {
73	$tour_key = $this->get_param( 'tour_key', '' );
74
75	if ( empty( $tour_key ) ) {
76	return $this->error( 'missing_tour_key', __( 'tour_key is required.', 'templately' ), 'tour/complete', 400 );
77	}
78
79	if ( ! $this->is_allowed_tour_key( $tour_key ) ) {
80	return $this->error( 'invalid_tour_key', __( 'Unrecognised tour_key.', 'templately' ), 'tour/complete', 400 );
81	}
82
83	$status = $this->utils( 'options' )->get( self::$tour_meta_key, [] );
84
85	if ( ! is_array( $status ) ) {
86	$status = [];
87	}
88
89	$status[ $tour_key ] = 'done';
90
91	$this->utils( 'options' )->set( self::$tour_meta_key, $status );
92
93	return $this->success( $status );
94	}
95
96	/**
97	* Reset one or all tours.
98	*
99	* Optional `tour_key` parameter:
100	* - Present: must be an allowlisted key (HTTP 400 `invalid_tour_key`
101	* otherwise); deletes that entry (idempotent — a no-op success if the
102	* key is valid but absent; other keys untouched).
103	* - Omitted: resets ALL tours by emptying the status map. The Developer
104	* Tools "reset tour" action depends on this reset-all form.
105	*
106	* @return \WP_REST_Response\|\WP_Error
107	*/
108	public function reset() {
109	$tour_key = $this->get_param( 'tour_key', '' );
110
111	if ( ! empty( $tour_key ) ) {
112	if ( ! $this->is_allowed_tour_key( $tour_key ) ) {
113	return $this->error( 'invalid_tour_key', __( 'Unrecognised tour_key.', 'templately' ), 'tour/reset', 400 );
114	}
115
116	$status = $this->utils( 'options' )->get( self::$tour_meta_key, [] );
117
118	if ( ! is_array( $status ) ) {
119	$status = [];
120	}
121
122	unset( $status[ $tour_key ] );
123
124	$this->utils( 'options' )->set( self::$tour_meta_key, $status );
125
126	return $this->success( $status );
127	}
128
129	// Reset all
130	$this->utils( 'options' )->set( self::$tour_meta_key, [] );
131
132	return $this->success( [] );
133	}
134	}
135