code-snippets / php / Settings / Setting_Field.php

Setting_Field.php in Code Snippets 3.10.0, at php/Settings/Setting_Field.php

271 lines 6.4 KB

Raw Download Zip

1	<?php
2
3	namespace Code_Snippets\Settings;
4
5	/**
6	* Represents a single setting field.
7	*
8	* @property-read string $desc Field description.
9	* @property-read string $label Field label.
10	* @property-read string $type Field type.
11	* @property-read string $name Setting name.
12	*
13	* @property-read int $min Minimum value (for numerical inputs).
14	* @property-read int $max Maximum value(for numerical inputs).
15	* @property-read array<string, string> $options List of options for a select or checkboxes field.
16	* @property-read callable $render_callback Custom function to use when rendering a callback field.
17	* @property-read callable $sanitize_callback Custom function to use when sanitize the setting value.
18	* @property-read mixed $default Default setting value.
19	*
20	* @property-read string $input_name Value of `name` HTML attribute on an input element.
21	* @property-read string $element_id
22	*/
23	class Setting_Field {
24
25	/**
26	* Input field identifier.
27	*
28	* @var string
29	*/
30	private string $field_id;
31
32	/**
33	* Settings section identifier.
34	*
35	* @var string
36	*/
37	private string $section;
38
39	/**
40	* List of possible arguments.
41	*
42	* @var array<string, mixed>
43	*/
44	private array $args = array(
45	'desc' => '',
46	'label' => '',
47	'min' => null,
48	'max' => null,
49	'options' => [],
50	);
51
52	/**
53	* Class constructor.
54	*
55	* @param string $section_id Settings section identifier.
56	* @param string $field_id Setting field identifier.
57	* @param array<string, mixed> $args The setting field attributes.
58	*/
59	public function __construct( string $section_id, string $field_id, array $args ) {
60	$this->field_id = $field_id;
61	$this->section = $section_id;
62	$this->args = array_merge( $this->args, $args );
63	}
64
65	/**
66	* Retrieve a single setting attribute.
67	*
68	* @param string $argument Attribute name.
69	*
70	* @return mixed Attribute value.
71	*/
72	public function __get( string $argument ) {
73
74	if ( 'input_name' === $argument ) {
75	return sprintf( '%s[%s][%s]', OPTION_NAME, $this->section, $this->field_id );
76	}
77
78	return $this->args[ $argument ];
79	}
80
81	/**
82	* Retrieve the saved value for this setting.
83	*
84	* @return mixed
85	*/
86	private function get_saved_value() {
87	return get_setting( $this->section, $this->field_id );
88	}
89
90	/**
91	* Render the setting field
92	*/
93	public function render() {
94	switch ( $this->type ) {
95	case 'callback':
96	if ( is_callable( $this->render_callback ) ) {
97	call_user_func( $this->render_callback, $this->args );
98	}
99	break;
100
101	case 'checkbox':
102	$this->render_checkbox( $this->input_name, $this->label, $this->get_saved_value() ?? false );
103	break;
104
105	case 'checkboxes':
106	$this->render_checkboxes_field();
107	break;
108
109	case 'text':
110	$this->render_text_field();
111	break;
112
113	case 'number':
114	$this->render_number_field();
115	break;
116
117	case 'select':
118	$this->render_select_field();
119	break;
120
121	case 'action':
122	$this->render_action_field();
123	break;
124
125	default:
126	// Error message, not necessary to translate.
127	printf( 'Cannot render a %s field.', esc_html( $this->type ) );
128	return;
129
130	}
131
132	if ( $this->desc ) {
133	echo '<p class="description">', wp_kses_post( $this->desc ), '</p>';
134	}
135	}
136
137	/**
138	* Render a single checkbox field.
139	*
140	* @param string $input_name Input name.
141	* @param string $label Input label.
142	* @param bool $checked Whether the checkbox should be checked.
143	*/
144	private static function render_checkbox( string $input_name, string $label, bool $checked ) {
145	$checkbox = sprintf(
146	'<input type="checkbox" name="%s" %s>',
147	esc_attr( $input_name ),
148	checked( $checked, true, false )
149	);
150
151	$allowed_html = [
152	'input' => [
153	'type' => [],
154	'name' => [],
155	'checked' => [],
156	],
157	];
158
159	if ( $label ) {
160	printf(
161	'<label>%s %s</label>',
162	wp_kses( $checkbox, $allowed_html ),
163	wp_kses_post( $label )
164	);
165	} else {
166	echo wp_kses( $checkbox, $allowed_html );
167	}
168	}
169
170	/**
171	* Render a checkbox field for a setting
172	*
173	* @return void
174	* @since 2.0.0
175	*/
176	public function render_checkboxes_field() {
177	$saved_value = $this->get_saved_value();
178	$saved_value = is_array( $saved_value ) ? $saved_value : [];
179
180	echo '<fieldset>';
181	printf( '<legend class="screen-reader-text"><span>%s</span></legend>', esc_html( $this->name ) );
182
183	foreach ( $this->options as $option => $label ) {
184	$this->render_checkbox( $this->input_name . "[$option]", $label, in_array( $option, $saved_value, true ) );
185	echo '<br>';
186	}
187
188	echo '</fieldset>';
189	}
190
191	/**
192	* Render a basic text field for an editor setting.
193	*
194	* @return void
195	*/
196	private function render_text_field() {
197	printf(
198	'<input id="%s" type="text" name="%s" value="%s" class="regular-text %s">',
199	esc_attr( $this->element_id ),
200	esc_attr( $this->input_name ),
201	esc_attr( $this->get_saved_value() ),
202	esc_attr( $this->element_id )
203	);
204
205	if ( $this->label ) {
206	echo ' ' . wp_kses_post( $this->label );
207	}
208	}
209
210	/**
211	* Render a number select field for an editor setting
212	*
213	* @since 2.0.0
214	*/
215	private function render_number_field() {
216	printf(
217	'<input type="number" name="%s" value="%s"',
218	esc_attr( $this->input_name ),
219	esc_attr( $this->get_saved_value() )
220	);
221
222	if ( is_numeric( $this->min ) ) {
223	printf( ' min="%d"', intval( $this->min ) );
224	}
225
226	if ( is_numeric( $this->max ) ) {
227	printf( ' max="%d"', intval( $this->max ) );
228	}
229
230	echo '>';
231
232	if ( $this->label ) {
233	echo ' ' . wp_kses_post( $this->label );
234	}
235	}
236
237	/**
238	* Render a number select field for an editor setting.
239	*
240	* @since 3.0.0
241	*/
242	private function render_select_field() {
243	$saved_value = $this->get_saved_value();
244	printf( '<select name="%s">', esc_attr( $this->input_name ) );
245
246	foreach ( $this->options as $option => $option_label ) {
247	printf(
248	'<option value="%s" %s>%s</option>',
249	esc_attr( $option ),
250	selected( $option, $saved_value, false ),
251	esc_html( $option_label )
252	);
253	}
254
255	echo '</select>';
256	}
257
258	/**
259	* Render a button link.
260	*
261	* @since 3.5.1
262	*/
263	private function render_action_field() {
264	printf(
265	'<button type="submit" name="%s" class="button">%s</button>',
266	esc_attr( $this->input_name ),
267	esc_html( $this->label ? $this->label : $this->name )
268	);
269	}
270	}
271