woocommerce-pos / includes / Interfaces / Settings_Section_Interface.php

Settings_Section_Interface.php in WCPOS – Point of Sale (POS) plugin for WooCommerce trunk, at includes/Interfaces/Settings_Section_Interface.php

75 lines 2.2 KB

Raw Download Zip

1	<?php
2	/**
3	* Settings Section interface.
4	*
5	* @package WCPOS\WooCommercePOS
6	*/
7
8	namespace WCPOS\WooCommercePOS\Interfaces;
9
10	use WP_Error;
11
12	/**
13	* A Settings Section owns one settings group end to end: schema, defaults,
14	* sanitization, secret redaction, and merge strategy. Sections are registered
15	* with the Section Registry (see Services\Settings\Section_Registry); the
16	* Settings facade and the REST controller call sections through this
17	* interface only.
18	*/
19	interface Settings_Section_Interface {
20	/**
21	* The section id, e.g. 'general'. Also the option-name suffix for
22	* option-backed sections (woocommerce_pos_settings_{id}).
23	*
24	* @return string
25	*/
26	public function id(): string;
27
28	/**
29	* The full default shape for this section (used for typed-accessor
30	* fallback). Non-option-backed sections may return an empty array.
31	*
32	* @return array
33	*/
34	public function defaults(): array;
35
36	/**
37	* Read the section's public view: defaults merged, legacy shapes migrated
38	* in memory, the woocommerce_pos_{id}_settings filter applied where the
39	* section uses the option-backed template (wholesale-override sections may
40	* skip it), secrets redacted. Reads are pure — they never write to the
41	* database.
42	*
43	* @return array
44	*/
45	public function read(): array;
46
47	/**
48	* Persist a full settings array (not a patch — callers merge first).
49	*
50	* @param array $settings The full settings array to persist.
51	*
52	* @return array\|WP_Error The section's post-save response on success — typically the post-save read; sections may return a bespoke shape (e.g. cloud_print includes one-time generated poll tokens).
53	*/
54	public function write( array $settings );
55
56	/**
57	* PATCH semantics for REST updates: merge an incoming partial payload
58	* over the existing view. Default is array_replace_recursive; sections
59	* with full-replacement keys (e.g. tax_ids write_map) override this.
60	*
61	* @param array $existing Existing settings view.
62	* @param array $patch Incoming partial payload.
63	*
64	* @return array
65	*/
66	public function merge( array $existing, array $patch ): array;
67
68	/**
69	* REST endpoint args (validation schema) for the section's update route.
70	*
71	* @return array
72	*/
73	public function endpoint_args(): array;
74	}
75