booking / includes / page-setup-wizard / interface-wpbc-setup-wizard-step-module.php

interface-wpbc-setup-wizard-step-module.php in Booking Calendar 11.9, at includes/page-setup-wizard/interface-wpbc-setup-wizard-step-module.php

193 lines 6.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Reusable step-module contract for the Setup Wizard module.
4	*
5	* @package Booking Calendar
6	*/
7
8	if ( ! defined( 'ABSPATH' ) ) {
9	exit;
10	}
11
12	/**
13	* Define the server-owned boundary implemented by a reusable setup editor.
14	*
15	* A module owns its field contract, read-only initial data, presentation
16	* context, validation, template, and compiled assets. Consumer pages own
17	* navigation, authorization, persistence, and any canonical mutation.
18	*/
19	interface WPBC_Setup_Wizard_Step_Module {
20
21	/**
22	* Return the stable module and step identifier.
23	*
24	* @return string Stable identifier.
25	*/
26	public function get_step_id();
27
28	/**
29	* Return the rail and template metadata contributed by this module.
30	*
31	* @return array{id:string,label:string,template:string,footer_note?:string} Step definition.
32	*/
33	public function get_step_definition();
34
35	/**
36	* Return the absolute server-owned template path.
37	*
38	* @return string Absolute template path.
39	*/
40	public function get_template_path();
41
42	/**
43	* Return the ordered field names accepted by this module.
44	*
45	* @return string[] Field allow-list.
46	*/
47	public function get_field_names();
48
49	/**
50	* Return fields required when the consumer advances.
51	*
52	* @return string[] Required field identifiers.
53	*/
54	public function get_required_fields();
55
56	/**
57	* Return authorized canonical values or safe read-only suggestions.
58	*
59	* @return array<string,mixed> Initial field values.
60	*/
61	public function get_initial_values();
62
63	/**
64	* Return other step values required to build this module's context.
65	*
66	* Dependencies are read-only presentation inputs. They do not grant access
67	* to another step's mutation or persistence behavior.
68	*
69	* @return string[] Stable dependency step identifiers.
70	*/
71	public function get_context_dependencies();
72
73	/**
74	* Build the data-only template context for one consumer.
75	*
76	* @param array<string,mixed> $field_values Validated module field values.
77	* @param array<string,mixed> $consumer_context Read-only dependency values keyed by step ID.
78	*
79	* @return array<string,mixed> Authorized presentation context.
80	*/
81	public function get_context( array $field_values, array $consumer_context = array() );
82
83	/**
84	* Validate one allow-listed module field.
85	*
86	* @param string $field_id Stable field identifier.
87	* @param mixed $raw_value Untrusted submitted or stored value.
88	* @param bool $is_required Whether an empty value is invalid.
89	*
90	* @return mixed\|WP_Error Normalized value or a validation error.
91	*/
92	public function validate_field( $field_id, $raw_value, $is_required );
93
94	/**
95	* Enqueue compiled module assets for an authorized consumer page.
96	*
97	* @param string $module_url Absolute URL to the Setup Wizard module root.
98	* @param string\|false $asset_version Plugin version used for cache busting.
99	* @param string $shared_style_handle Consumer shell style handle.
100	* @param string $shared_script_handle Consumer shell script handle.
101	*
102	* @return void
103	*/
104	public function enqueue_assets( $module_url, $asset_version, $shared_style_handle, $shared_script_handle );
105	}
106
107	/**
108	* Identify step fields that must be rebuilt from current plugin state.
109	*
110	* The Setup Wizard checkpoint records the values submitted at each successful
111	* save boundary. That history is useful for navigation, idempotency, and
112	* wizard-only metadata, but it must not become a stale cache of canonical
113	* Booking Calendar settings. Modules implement this companion contract for
114	* fields whose initial values are read from current canonical state, or whose
115	* value is an intentionally one-request lifecycle reset such as a consumed
116	* mutation intent.
117	*
118	* Fields not returned by this contract remain checkpoint-owned wizard
119	* metadata. This distinction is intentionally explicit because some steps,
120	* such as publishing and Booking Form template selection, store choices that
121	* cannot be reconstructed safely from canonical records.
122	*/
123	interface WPBC_Setup_Wizard_Current_Values_Module {
124
125	/**
126	* Return fields that always use the module's latest initial values.
127	*
128	* Every returned name must also be present in the module field allow-list.
129	* Unknown names are ignored by the shared presentation service.
130	*
131	* @return string[] Current-value field identifiers.
132	*/
133	public function get_current_value_field_names();
134	}
135
136	/**
137	* Define optional validation for relationships between normalized fields.
138	*
139	* Modules implement this companion contract only when correctness depends on
140	* more than one field. Field-level validation always runs first, so this method
141	* receives scalar values that already passed the module's allow-list.
142	*/
143	interface WPBC_Setup_Wizard_Step_Values_Validator {
144
145	/**
146	* Validate relationships across one module's normalized field set.
147	*
148	* @param array<string,mixed> $validated_values Field values after individual validation.
149	*
150	* @return array<string,mixed>\|WP_Error Validated values or a field-addressable error.
151	*/
152	public function validate_values( array $validated_values );
153	}
154
155	/**
156	* Define optional validation that depends on earlier wizard-step values.
157	*
158	* This companion contract keeps cross-step business rules inside the consuming
159	* domain module. The shared draft validator supplies only allow-listed,
160	* normalized dependency values and remains unaware of their business meaning.
161	*/
162	interface WPBC_Setup_Wizard_Contextual_Values_Validator {
163
164	/**
165	* Validate normalized module values against read-only dependency values.
166	*
167	* @param array<string,mixed> $validated_values Field values after module validation.
168	* @param array<string,mixed> $consumer_context Allow-listed dependency values keyed by step ID.
169	*
170	* @return array<string,mixed>\|WP_Error Validated values or a field-addressable error.
171	*/
172	public function validate_values_with_context( array $validated_values, array $consumer_context );
173	}
174
175	/**
176	* Define optional route availability for a registered step module.
177	*
178	* Registration keeps the template and validation contract explicit. Route
179	* availability determines whether the consumer may expose the step in the
180	* current site context, such as omitting publishing from live-demo websites.
181	*/
182	interface WPBC_Setup_Wizard_Conditional_Step_Module {
183
184	/**
185	* Determine whether the module belongs to the current active route.
186	*
187	* @param array<string,mixed> $consumer_context Optional read-only route context.
188	*
189	* @return bool True when the module may be exposed.
190	*/
191	public function is_available( array $consumer_context = array() );
192	}
193