convertkit / admin / section / class-convertkit-settings-base.php

class-convertkit-settings-base.php in Kit (formerly ConvertKit) – Email Newsletter, Email Marketing, Membership, Subscribers and Landing Pages 2.5.2, at admin/section/class-convertkit-settings-base.php

660 lines 15.4 KB

Raw Download Zip

1	<?php
2	/**
3	* ConvertKit Settings Base class.
4	*
5	* @package ConvertKit
6	* @author ConvertKit
7	*/
8
9	/**
10	* ConvertKit Settings class
11	*
12	* @package ConvertKit
13	* @author ConvertKit
14	*/
15	abstract class ConvertKit_Settings_Base {
16
17	/**
18	* Section name
19	*
20	* @var string
21	*/
22	public $name;
23
24	/**
25	* Section title
26	*
27	* @var string
28	*/
29	public $title;
30
31	/**
32	* Section tab text
33	*
34	* @var string
35	*/
36	public $tab_text;
37
38	/**
39	* Options table key
40	*
41	* @var string
42	*/
43	public $settings_key;
44
45	/**
46	* Holds the settings class for the section.
47	*
48	* @since 1.9.6
49	*
50	* @var false\|ConvertKit_Settings\|ConvertKit_ContactForm7_Settings\|ConvertKit_Wishlist_Settings\|ConvertKit_Settings_Restrict_Content\|ConvertKit_Settings_Broadcasts\|ConvertKit_Forminator_Settings
51	*/
52	public $settings;
53
54	/**
55	* Holds whether this settings section is for beta functionality.
56	*
57	* @since 2.1.0
58	*
59	* @var bool
60	*/
61	public $is_beta = false;
62
63	/**
64	* Holds whether the save button should be disabled e.g. there are no
65	* settings on screen to save.
66	*
67	* @since 2.4.9
68	*
69	* @var bool
70	*/
71	public $save_disabled = false;
72
73	/**
74	* Constructor
75	*/
76	public function __construct() {
77
78	// If tab text is not defined, use the title for the tab's text.
79	if ( empty( $this->tab_text ) ) {
80	$this->tab_text = $this->title;
81	}
82
83	// Register the settings section.
84	$this->register_section();
85
86	}
87
88	/**
89	* Helper method to determine if we're viewing the current settings screen.
90	*
91	* @since 2.5.0
92	*
93	* @param string $tab Current settings tab (general\|tools\|restrict-content\|broadcasts).
94	* @return bool
95	*/
96	public function on_settings_screen( $tab ) {
97
98	// phpcs:disable WordPress.Security.NonceVerification
99
100	// Bail if we're not on the settings screen.
101	if ( ! array_key_exists( 'page', $_REQUEST ) ) {
102	return false;
103	}
104	if ( sanitize_text_field( $_REQUEST['page'] ) !== '_wp_convertkit_settings' ) {
105	return false;
106	}
107
108	// Define current settings tab.
109	// General screen won't always be loaded with a `tab` parameter.
110	$current_tab = ( array_key_exists( 'tab', $_REQUEST ) ? sanitize_text_field( $_REQUEST['tab'] ) : 'general' );
111
112	// Return whether the request is for the current settings tab.
113	return ( $current_tab === $tab );
114
115	// phpcs:enable
116
117	}
118
119	/**
120	* Register settings section.
121	*/
122	public function register_section() {
123
124	add_settings_section(
125	$this->name,
126	$this->title,
127	array( $this, 'print_section_info' ),
128	$this->settings_key
129	);
130
131	$this->register_fields();
132
133	register_setting(
134	$this->settings_key,
135	$this->settings_key,
136	array( $this, 'sanitize_settings' )
137	);
138
139	}
140
141	/**
142	* Register fields for this section
143	*/
144	abstract public function register_fields();
145
146	/**
147	* Prints help info for this section
148	*/
149	abstract public function print_section_info();
150
151	/**
152	* Returns the URL for the ConvertKit documentation for this setting section.
153	*/
154	abstract public function documentation_url();
155
156	/**
157	* Outputs success and/or error notices if required.
158	*
159	* @since 2.0.0
160	*/
161	public function maybe_output_notices() {
162
163	// Define notices that might be displayed as a notification.
164	$notices = array();
165
166	/**
167	* Register success and error notices for settings screens.
168	*
169	* @since 2.5.1
170	*
171	* @param array $notices Regsitered success and error notices.
172	* @return array
173	*/
174	$notices = apply_filters( 'convertkit_settings_base_register_notices', $notices );
175
176	// Output the verbose error description if supplied (e.g. OAuth).
177	if ( isset( $_REQUEST['error_description'] ) ) { // phpcs:ignore WordPress.Security.NonceVerification
178	$this->output_error( sanitize_text_field( $_REQUEST['error_description'] ) ); // phpcs:ignore WordPress.Security.NonceVerification
179	}
180
181	// Output error notification if defined.
182	if ( isset( $_REQUEST['error'] ) && array_key_exists( sanitize_text_field( $_REQUEST['error'] ), $notices ) ) { // phpcs:ignore WordPress.Security.NonceVerification
183	$this->output_error( $notices[ sanitize_text_field( $_REQUEST['error'] ) ] ); // phpcs:ignore WordPress.Security.NonceVerification
184	}
185
186	// Output success notification if defined.
187	if ( isset( $_REQUEST['success'] ) && array_key_exists( sanitize_text_field( $_REQUEST['success'] ), $notices ) ) { // phpcs:ignore WordPress.Security.NonceVerification
188	$this->output_success( $notices[ sanitize_text_field( $_REQUEST['success'] ) ] ); // phpcs:ignore WordPress.Security.NonceVerification
189	}
190
191	}
192
193	/**
194	* Renders the section
195	*/
196	public function render() {
197
198	/**
199	* Performs actions prior to rendering the settings form.
200	*
201	* @since 1.9.6
202	*/
203	do_action( 'convertkit_settings_base_render_before' );
204
205	$this->render_container_start();
206
207	do_settings_sections( $this->settings_key );
208
209	settings_fields( $this->settings_key );
210
211	if ( ! $this->save_disabled ) {
212	submit_button();
213	}
214
215	$this->render_container_end();
216
217	/**
218	* Performs actions after rendering of the settings form.
219	*
220	* @since 1.9.6
221	*/
222	do_action( 'convertkit_settings_base_render_after' );
223
224	}
225
226	/**
227	* Outputs .metabox-holder and .postbox container div elements,
228	* used before beginning a setting screen's output.
229	*
230	* @since 2.0.0
231	*/
232	public function render_container_start() {
233
234	?>
235	<div class="metabox-holder">
236	<div class="postbox <?php echo sanitize_html_class( $this->is_beta ? 'convertkit-beta' : '' ); ?>">
237	<?php
238
239	}
240
241	/**
242	* Outputs closing .metabox-holder and .postbox container div elements,
243	* used after finishing a setting screen's output.
244	*
245	* @since 2.0.0
246	*/
247	public function render_container_end() {
248
249	?>
250	</div>
251	</div>
252	<?php
253
254	}
255
256	/**
257	* Redirects to the settings screen.
258	*
259	* @since 2.2.9
260	*/
261	public function redirect() {
262
263	wp_safe_redirect(
264	add_query_arg(
265	array(
266	'page' => '_wp_convertkit_settings',
267	'tab' => $this->name,
268	),
269	'options-general.php'
270	)
271	);
272	exit();
273
274	}
275
276	/**
277	* Redirects to the settings screen with an error notice key.
278	*
279	* The function maybe_output_notices() will then output the translated error notice
280	* based on the supplied key.
281	*
282	* @since 2.5.1
283	*
284	* @param string $error The error notice key, registered using `convertkit_settings_base_register_notices`.
285	*/
286	public function redirect_with_error_notice( $error ) {
287
288	wp_safe_redirect(
289	add_query_arg(
290	array(
291	'page' => '_wp_convertkit_settings',
292	'tab' => $this->name,
293	'error' => $error,
294	),
295	'options-general.php'
296	)
297	);
298	exit();
299
300	}
301
302	/**
303	* Redirects to the settings screen with the verbose error description.
304	*
305	* @since 2.5.1
306	*
307	* @param string $error_description The error description.
308	*/
309	public function redirect_with_error_description( $error_description ) {
310
311	wp_safe_redirect(
312	add_query_arg(
313	array(
314	'page' => '_wp_convertkit_settings',
315	'tab' => $this->name,
316	'error_description' => $error_description,
317	),
318	'options-general.php'
319	)
320	);
321	exit();
322
323	}
324
325	/**
326	* Redirects to the settings screen with a success notice key.
327	*
328	* The function maybe_output_notices() will then output the translated success notice
329	* based on the supplied key.
330	*
331	* @since 2.5.1
332	*
333	* @param string $success The success notice key, registered using `convertkit_settings_base_register_notices`.
334	*/
335	public function redirect_with_success_notice( $success ) {
336
337	wp_safe_redirect(
338	add_query_arg(
339	array(
340	'page' => '_wp_convertkit_settings',
341	'tab' => $this->name,
342	'success' => $success,
343	),
344	'options-general.php'
345	)
346	);
347	exit();
348
349	}
350
351	/**
352	* Outputs the given success message in an inline notice.
353	*
354	* @since 2.0.0
355	*
356	* @param string $success_message Success Message.
357	*/
358	public function output_success( $success_message ) {
359
360	?>
361	<div class="notice notice-success is-dismissible">
362	<p>
363	<?php echo esc_attr( $success_message ); ?>
364	</p>
365	</div>
366	<?php
367
368	}
369
370	/**
371	* Outputs the given error message in an inline notice.
372	*
373	* @since 1.9.6
374	*
375	* @param string $error_message Error Message.
376	*/
377	public function output_error( $error_message ) {
378
379	?>
380	<div class="notice notice-error is-dismissible">
381	<p>
382	<?php echo esc_attr( $error_message ); ?>
383	</p>
384	</div>
385	<?php
386
387	}
388
389	/**
390	* Returns a masked value.
391	*
392	* @since 1.9.6
393	*
394	* @param string $value Value.
395	* @param bool\|string $description Description.
396	* @return string Masked Value
397	*/
398	public function get_masked_value( $value, $description = false ) {
399
400	$html = sprintf(
401	'<code>%s</code>',
402	str_repeat( '*', strlen( $value ) - 4 ) . substr( $value, - 4 )
403	);
404
405	if ( $description ) {
406	$html .= $this->get_description( $description );
407	}
408
409	return $html;
410
411	}
412
413	/**
414	* Returns a text field.
415	*
416	* @since 1.9.6
417	*
418	* @param string $name Name.
419	* @param string $value Value.
420	* @param bool\|string\|array $description Description (false\|string\|array).
421	* @param bool\|array $css_classes CSS Classes (false\|array).
422	* @return string HTML Field
423	*/
424	public function get_text_field( $name, $value = '', $description = false, $css_classes = false ) {
425
426	$html = sprintf(
427	'<input type="text" class="%s" id="%s" name="%s[%s]" value="%s" />',
428	( is_array( $css_classes ) ? implode( ' ', $css_classes ) : 'regular-text' ),
429	$name,
430	$this->settings_key,
431	$name,
432	$value
433	);
434
435	return $html . $this->get_description( $description );
436
437	}
438
439	/**
440	* Returns a textarea field.
441	*
442	* @since 2.3.5
443	*
444	* @param string $name Name.
445	* @param string $value Value.
446	* @param bool\|string\|array $description Description (false\|string\|array).
447	* @param bool\|array $css_classes CSS Classes (false\|array).
448	* @return string HTML Field
449	*/
450	public function get_textarea_field( $name, $value = '', $description = false, $css_classes = false ) {
451
452	$html = sprintf(
453	'<textarea class="%s" id="%s" name="%s[%s]">%s</textarea>',
454	( is_array( $css_classes ) ? implode( ' ', $css_classes ) : 'regular-text' ),
455	$name,
456	$this->settings_key,
457	$name,
458	$value
459	);
460
461	return $html . $this->get_description( $description );
462
463	}
464
465	/**
466	* Returns a date field.
467	*
468	* @since 2.2.8
469	*
470	* @param string $name Name.
471	* @param string $value Value.
472	* @param bool\|string\|array $description Description (false\|string\|array).
473	* @param bool\|array $css_classes CSS Classes (false\|array).
474	* @return string HTML Field
475	*/
476	public function get_date_field( $name, $value = '', $description = false, $css_classes = false ) {
477
478	$html = sprintf(
479	'<input type="date" class="%s" id="%s" name="%s[%s]" value="%s" />',
480	( is_array( $css_classes ) ? implode( ' ', $css_classes ) : 'regular-text' ),
481	$name,
482	$this->settings_key,
483	$name,
484	$value
485	);
486
487	return $html . $this->get_description( $description );
488
489	}
490
491	/**
492	* Returns a select dropdown field.
493	*
494	* @since 1.9.6
495	*
496	* @param string $name Name.
497	* @param string $value Value.
498	* @param array $options Options / Choices.
499	* @param bool\|string $description Description.
500	* @param bool\|array $css_classes <select> CSS class(es).
501	* @param bool\|array $attributes <select> attributes.
502	* @return string HTML Select Field
503	*/
504	public function get_select_field( $name, $value = '', $options = array(), $description = false, $css_classes = false, $attributes = false ) {
505
506	// Build opening <select> tag.
507	$html = sprintf(
508	'<select id="%s" name="%s[%s]" class="%s" size="1" %s>',
509	$this->settings_key . '_' . $name,
510	$this->settings_key,
511	$name,
512	( is_array( $css_classes ) ? implode( ' ', $css_classes ) : '' ),
513	( is_array( $attributes ) ? $this->array_to_attributes( $attributes ) : '' )
514	);
515
516	// Build <option> tags.
517	foreach ( $options as $option => $label ) {
518	$html .= sprintf(
519	'<option value="%s"%s>%s</option>',
520	$option,
521	selected( $value, $option, false ),
522	$label
523	);
524	}
525
526	// Close <select>.
527	$html .= '</select>';
528
529	// If no description exists, just return the select field.
530	if ( empty( $description ) ) {
531	return $html;
532	}
533
534	// Return select field with description appended to it.
535	return $html . $this->get_description( $description );
536
537	}
538
539	/**
540	* Returns a checkbox field.
541	*
542	* @since 1.9.6
543	*
544	* @param string $name Name.
545	* @param string $value Value.
546	* @param bool $checked Should checkbox be checked/ticked.
547	* @param bool\|string $label Label.
548	* @param bool\|string\|array $description Description.
549	* @param bool\|array $css_classes CSS class(es).
550	* @return string HTML Checkbox
551	*/
552	public function get_checkbox_field( $name, $value, $checked = false, $label = '', $description = false, $css_classes = false ) {
553
554	$html = '';
555
556	if ( $label ) {
557	$html .= sprintf(
558	'<label for="%s">',
559	$name
560	);
561	}
562
563	$html .= sprintf(
564	'<input type="checkbox" id="%s" name="%s[%s]" class="%s" value="%s" %s />',
565	$name,
566	$this->settings_key,
567	$name,
568	( is_array( $css_classes ) ? implode( ' ', $css_classes ) : '' ),
569	$value,
570	( $checked ? ' checked' : '' )
571	);
572
573	if ( $label ) {
574	$html .= sprintf(
575	'%s</label>',
576	$label
577	);
578	}
579
580	// If no description exists, just return the field.
581	if ( empty( $description ) ) {
582	return $html;
583	}
584
585	// Return field with description appended to it.
586	return $html . $this->get_description( $description );
587
588	}
589
590	/**
591	* Returns the given text wrapped in a paragraph with the description class.
592	*
593	* @since 1.9.6
594	*
595	* @param bool\|string\|array $description Description.
596	* @return string HTML Description
597	*/
598	public function get_description( $description ) {
599
600	// Return blank string if no description specified.
601	if ( ! $description ) {
602	return '';
603	}
604
605	// Return description in paragraph if a string.
606	if ( ! is_array( $description ) ) {
607	return '<p class="description">' . $description . '</p>';
608	}
609
610	// Return description lines in a paragraph, using breaklines for each description entry in the array.
611	return '<p class="description">' . implode( '<br />', $description ) . '</p>';
612
613	}
614
615	/**
616	* Converts the given key/value array pairs into a HTML attribute="value" string.
617	*
618	* @since 1.9.8.5
619	*
620	* @param array $attributes_array Attributes.
621	* @return string HTML attributes string
622	*/
623	private function array_to_attributes( $attributes_array ) {
624
625	$attributes = '';
626	foreach ( $attributes_array as $key => $value ) {
627	$attributes .= esc_attr( $key ) . '="' . esc_attr( $value ) . '" ';
628	}
629
630	return trim( $attributes );
631
632	}
633
634	/**
635	* Sanitizes the settings prior to being saved.
636	*
637	* @since 1.9.6
638	*
639	* @param array $settings Submitted Settings Fields.
640	* @return array Sanitized Settings with Defaults
641	*/
642	public function sanitize_settings( $settings ) {
643
644	// Merge settings with defaults.
645	$updated_settings = wp_parse_args( $settings, $this->settings->get_defaults() );
646
647	/**
648	* Performs actions prior to settings being saved.
649	*
650	* @since 2.2.8
651	*/
652	do_action( 'convertkit_settings_base_sanitize_settings', $this->name, $updated_settings );
653
654	// Return settings to be saved.
655	return $updated_settings;
656
657	}
658
659	}
660