formidable / classes / controllers / FrmOnboardingWizardController.php

FrmOnboardingWizardController.php in Formidable Forms – WordPress Form Builder for Contact Forms, Calculators, Quizzes & More trunk, at classes/controllers/FrmOnboardingWizardController.php

730 lines 20.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Onboarding Wizard Controller class.
4	*
5	* @package Formidable
6	*/
7
8	if ( ! defined( 'ABSPATH' ) ) {
9	die( 'You are not allowed to call this page directly.' );
10	}
11
12	/**
13	* Handles the Onboarding Wizard page in the admin area.
14	*
15	* @since 6.9
16	*/
17	class FrmOnboardingWizardController {
18
19	/**
20	* The slug of the Onboarding Wizard page.
21	*
22	* @var string
23	*/
24	const PAGE_SLUG = 'formidable-onboarding-wizard';
25
26	/**
27	* The script handle.
28	*
29	* @var string
30	*/
31	const SCRIPT_HANDLE = 'frm-onboarding-wizard';
32
33	/**
34	* The required user capability to view the Onboarding Wizard page.
35	*
36	* @var string
37	*/
38	const REQUIRED_CAPABILITY = 'frm_view_forms';
39
40	/**
41	* Transient name used for managing redirection to the Onboarding Wizard page.
42	*
43	* @var string
44	*/
45	const TRANSIENT_NAME = 'frm_activation_redirect';
46
47	/**
48	* Transient value associated with the redirection to the Onboarding Wizard page.
49	* Used when activating a single plugin.
50	*
51	* @var string
52	*/
53	const TRANSIENT_VALUE = 'formidable-welcome';
54
55	/**
56	* Transient value associated with the redirection to the Onboarding Wizard page.
57	* Used when activating multiple plugins at once.
58	*
59	* @var string
60	*/
61	const TRANSIENT_MULTI_VALUE = 'formidable-welcome-multi';
62
63	/**
64	* Option name for storing the redirect status for the Onboarding Wizard page.
65	*
66	* @var string
67	*/
68	const REDIRECT_STATUS_OPTION = 'frm_welcome_redirect';
69
70	/**
71	* Option name for tracking if the onboarding wizard was skipped.
72	*
73	* @var string
74	*/
75	const ONBOARDING_SKIPPED_OPTION = 'frm_onboarding_skipped';
76
77	/**
78	* Defines the initial step for redirection within the application flow.
79	*
80	* @var string
81	*/
82	const INITIAL_STEP = 'consent-tracking';
83
84	/**
85	* Option name to store usage data.
86	*
87	* @var string
88	*/
89	const USAGE_DATA_OPTION = 'frm_onboarding_usage_data';
90
91	/**
92	* Holds the URL to access the Onboarding Wizard's page.
93	*
94	* @var string
95	*/
96	private static $page_url = '';
97
98	/**
99	* Holds a list of add-ons available for installation.
100	*
101	* @var array
102	*/
103	private static $available_addons = array();
104
105	/**
106	* Path to views.
107	*
108	* @var string
109	*/
110	private static $view_path = '';
111
112	/**
113	* Upgrade URL.
114	*
115	* @var string
116	*/
117	private static $upgrade_link = '';
118
119	/**
120	* Initialize hooks for template page only.
121	*
122	* @since 6.9
123	*
124	* @return void
125	*/
126	public static function load_admin_hooks() {
127	self::set_page_url();
128	add_action( 'admin_init', self::class . '::do_admin_redirects' );
129
130	if ( self::has_onboarding_been_skipped() ) {
131	add_filter( 'option_frm_inbox', self::class . '::add_wizard_to_floating_links' );
132	}
133
134	/**
135	* Load page if admin page is Onboarding Wizard.
136	* This waits for init because it reads the inbox option, and the filter above translates
137	* when it does. Translating before the text domain is loaded triggers a
138	* _load_textdomain_just_in_time notice in WordPress 6.7+.
139	*/
140	add_action( 'init', self::class . '::maybe_load_page' );
141	}
142
143	/**
144	* Performs a safe redirect to the welcome screen when the plugin is activated.
145	* On single activation, we will redirect immediately.
146	* When activating multiple plugins, the redirect is delayed until a Formidable page is loaded.
147	*
148	* @return void
149	*/
150	public static function do_admin_redirects() {
151	$current_page = FrmAppHelper::simple_get( 'page', 'sanitize_title' );
152
153	// Prevent endless loop.
154	if ( $current_page === self::PAGE_SLUG ) {
155	return;
156	}
157
158	// Only do this for single site installs.
159	if ( is_network_admin() ) { // phpcs:ignore WordPress.Security.NonceVerification.Missing
160	self::mark_onboarding_as_skipped();
161	return;
162	}
163
164	if ( self::has_onboarding_been_skipped() \|\| FrmAppHelper::pro_is_connected() ) {
165	return;
166	}
167
168	$transient_value = get_transient( self::TRANSIENT_NAME );
169
170	if ( ! in_array( $transient_value, array( self::TRANSIENT_VALUE, self::TRANSIENT_MULTI_VALUE ), true ) ) {
171	return;
172	}
173
174	if ( isset( $_GET['activate-multi'] ) ) {
175	/**
176	* $_GET['activate-multi'] is set after activating multiple plugins.
177	* In this case, change the transient value so we know for future checks.
178	*/
179	set_transient( self::TRANSIENT_NAME, self::TRANSIENT_MULTI_VALUE, 60 );
180	return;
181	}
182
183	if ( self::TRANSIENT_MULTI_VALUE === $transient_value && ! FrmAppHelper::is_formidable_admin() ) {
184	// For multi-activations we want to only redirect when a user loads a Formidable page.
185	return;
186	}
187
188	set_transient( self::TRANSIENT_NAME, 'no', 60 );
189
190	// Prevent redirect with every activation.
191	if ( self::has_already_redirected() ) {
192	return;
193	}
194
195	// Redirect to the onboarding wizard's initial step.
196	$page_url = add_query_arg( 'step', self::INITIAL_STEP, self::$page_url );
197
198	if ( wp_safe_redirect( esc_url_raw( $page_url ) ) ) {
199	exit;
200	}
201	}
202
203	/**
204	* Initializes the Onboarding Wizard setup if on its designated admin page.
205	*
206	* @since 6.9
207	*
208	* @return void
209	*/
210	public static function maybe_load_page() {
211	if ( ! self::is_onboarding_wizard_page() ) {
212	return;
213	}
214
215	// Dismiss the onboarding wizard message so it stops appearing after it is clicked.
216	$message = new FrmInbox();
217	$message->dismiss( 'onboarding_wizard' );
218
219	add_action( 'admin_menu', self::class . '::menu', 99 );
220	add_action( 'admin_init', self::class . '::assign_properties' );
221	add_action( 'admin_enqueue_scripts', self::class . '::enqueue_assets', 15 );
222	add_action( 'admin_head', self::class . '::remove_menu' );
223
224	add_filter( 'admin_body_class', self::class . '::add_admin_body_classes', 999 );
225	add_filter( 'frm_show_footer_links', '__return_false' );
226	}
227
228	/**
229	* Initializes class properties with essential values for operation.
230	*
231	* @since 6.9
232	*
233	* @return void
234	*/
235	public static function assign_properties() {
236	self::$view_path = FrmAppHelper::plugin_path() . '/classes/views/onboarding-wizard/';
237
238	self::$upgrade_link = FrmAppHelper::admin_upgrade_link(
239	array(
240	'medium' => 'onboarding-wizard',
241	'content' => 'upgrade',
242	)
243	);
244
245	self::set_available_addons();
246	}
247
248	/**
249	* Add Onboarding Wizard menu item to sidebar and define index page.
250	*
251	* @since 6.9
252	*
253	* @return void
254	*/
255	public static function menu() {
256	if ( ! current_user_can( 'activate_plugins' ) ) {
257	return;
258	}
259
260	$label = __( 'Onboarding Wizard', 'formidable' );
261
262	add_submenu_page(
263	'formidable',
264	'Formidable \| ' . $label,
265	$label,
266	self::REQUIRED_CAPABILITY,
267	self::PAGE_SLUG,
268	array( self::class, 'render' )
269	);
270	}
271
272	/**
273	* Renders the Onboarding Wizard page in the WordPress admin area.
274	*
275	* @since 6.9
276	*
277	* @return void
278	*/
279	public static function render() {
280	if ( self::has_onboarding_been_skipped() ) {
281	delete_option( self::ONBOARDING_SKIPPED_OPTION );
282	self::has_already_redirected();
283	}
284
285	// Include SVG images for icons.
286	FrmAppHelper::include_svg();
287
288	$view_path = self::get_view_path();
289	$available_addons = self::get_available_addons();
290	$upgrade_link = self::get_upgrade_link();
291	$addons_count = FrmAddonsController::get_addons_count();
292	$license_key = base64_decode( rawurldecode( FrmAppHelper::get_param( 'key', '', 'request', 'sanitize_text_field' ) ) );
293	$pro_is_installed = FrmAppHelper::pro_is_installed();
294
295	// Note: Add step parts in order.
296	$step_parts = array(
297	'consent-tracking' => 'steps/consent-tracking-step.php',
298	'install-addons' => 'steps/install-addons-step.php',
299	'success' => 'steps/success-step.php',
300	'unsuccessful' => 'steps/unsuccessful-step.php',
301	);
302
303	include $view_path . 'index.php';
304	}
305
306	/**
307	* Handle AJAX request to setup the "Never miss an important update" step.
308	*
309	* @since 6.9
310	*
311	* @return void
312	*/
313	public static function ajax_consent_tracking() {
314	// Check permission and nonce.
315	FrmAppHelper::permission_check( self::REQUIRED_CAPABILITY );
316	check_ajax_referer( 'frm_ajax', 'nonce' );
317
318	// Update Settings.
319	$frm_settings = FrmAppHelper::get_settings();
320	$frm_settings->update_setting( 'tracking', true, 'rest_sanitize_boolean' );
321
322	// Remove the 'FrmProSettingsController::store' action to avoid PHP errors during AJAX call.
323	remove_action( 'frm_store_settings', 'FrmProSettingsController::store' );
324	$frm_settings->store();
325
326	FrmEmailCollectionHelper::subscribe_to_active_campaign();
327
328	// Send response.
329	wp_send_json_success();
330	}
331
332	/**
333	* Handle AJAX request to set up usage data for the Onboarding Wizard.
334	*
335	* @since 6.9
336	*
337	* @return void
338	*/
339	public static function setup_usage_data() {
340	// Check permission and nonce.
341	FrmAppHelper::permission_check( self::REQUIRED_CAPABILITY );
342	check_ajax_referer( 'frm_ajax', 'nonce' );
343
344	// Retrieve the current usage data.
345	$usage_data = self::get_usage_data();
346
347	$fields_to_update = array(
348	'allows_tracking' => 'rest_sanitize_boolean',
349	'installed_addons' => 'sanitize_text_field',
350	'processed_steps' => 'sanitize_text_field',
351	'completed_steps' => 'rest_sanitize_boolean',
352	);
353
354	foreach ( $fields_to_update as $field => $sanitize_callback ) {
355	if ( isset( $_POST[ $field ] ) ) {
356	$usage_data[ $field ] = FrmAppHelper::get_post_param( $field, '', $sanitize_callback );
357	}
358	}
359
360	update_option( self::USAGE_DATA_OPTION, $usage_data );
361	wp_send_json_success();
362	}
363
364	/**
365	* Enqueues the Onboarding Wizard page scripts and styles.
366	*
367	* @since 6.9
368	*
369	* @return void
370	*/
371	public static function enqueue_assets() {
372	$plugin_url = FrmAppHelper::plugin_url();
373	$version = FrmAppHelper::plugin_version();
374	$js_dependencies = array(
375	'wp-i18n',
376	// This prevents a console error "wp.hooks is undefined" in WP versions older than 5.7.
377	'wp-hooks',
378	'formidable_dom',
379	);
380
381	// Enqueue styles that needed.
382	wp_enqueue_style( 'formidable-admin' );
383	wp_enqueue_style( 'formidable-grids' );
384
385	// Register and enqueue Onboarding Wizard style.
386	wp_register_style( self::SCRIPT_HANDLE, $plugin_url . '/css/admin/onboarding-wizard.css', array(), $version );
387	wp_enqueue_style( self::SCRIPT_HANDLE );
388
389	// Register and enqueue Onboarding Wizard script.
390	wp_register_script( self::SCRIPT_HANDLE, $plugin_url . '/js/onboarding-wizard.js', $js_dependencies, $version, true );
391	wp_localize_script( self::SCRIPT_HANDLE, 'frmOnboardingWizardVars', self::get_js_variables() );
392	wp_enqueue_script( self::SCRIPT_HANDLE );
393
394	/**
395	* Fires after the Onboarding Wizard enqueue assets.
396	*
397	* @since 6.9
398	*/
399	do_action( 'frm_onboarding_wizard_enqueue_assets' );
400
401	FrmAppHelper::dequeue_extra_global_scripts();
402	}
403
404	/**
405	* Get the Onboarding Wizard JS variables as an array.
406	*
407	* @since 6.9
408	*
409	* @return array
410	*/
411	private static function get_js_variables() {
412	return array(
413	'INITIAL_STEP' => self::INITIAL_STEP,
414	);
415	}
416
417	/**
418	* Remove the Onboarding Wizard submenu page from the formidable parent menu
419	* since it is not necessary to show that link there.
420	*
421	* @since 6.9
422	*
423	* @return void
424	*/
425	public static function remove_menu() {
426	remove_submenu_page( 'formidable', self::PAGE_SLUG );
427	}
428
429	/**
430	* Adds custom classes to the existing string of admin body classes.
431	*
432	* The function appends a custom class to the existing admin body classes, enabling full-screen mode for the admin interface.
433	*
434	* @since 6.9
435	*
436	* @param string $classes Existing body classes.
437	*
438	* @return string Updated list of body classes, including the newly added classes.
439	*/
440	public static function add_admin_body_classes( $classes ) {
441	return $classes . ' frm-admin-full-screen';
442	}
443
444	/**
445	* Checks if the Onboarding Wizard was skipped during the plugin's installation.
446	*
447	* @since 6.9
448	*
449	* @return bool True if the Onboarding Wizard was skipped, false otherwise.
450	*/
451	public static function has_onboarding_been_skipped() {
452	return get_option( self::ONBOARDING_SKIPPED_OPTION, false );
453	}
454
455	/**
456	* Marks the Onboarding Wizard as skipped to prevent automatic redirects to the wizard.
457	*
458	* @since 6.9
459	*
460	* @return void
461	*/
462	public static function mark_onboarding_as_skipped() {
463	update_option( self::ONBOARDING_SKIPPED_OPTION, true, false );
464	}
465
466	/**
467	* Adds an Onboarding Wizard welcome message to the floating notifications.
468	*
469	* @since 6.9
470	*
471	* @param mixed $inbox_messages The inbox option data. An array of existing inbox messages if there is valid data set in the option.
472	*
473	* @return array Configuration for the onboarding wizard slide-in notification.
474	*/
475	public static function add_wizard_to_floating_links( $inbox_messages ) {
476	$message = __( 'Welcome to Formidable Forms! Click here to run the Onboarding Wizard and it will guide you through the basic settings and get you started in 2 minutes.', 'formidable' ); // phpcs:ignore SlevomatCodingStandard.Files.LineLength.LineTooLong
477
478	if ( ! is_array( $inbox_messages ) ) {
479	$inbox_messages = array();
480	}
481
482	$inbox_messages['onboarding_wizard'] = array(
483	'subject' => esc_html__( 'Begin With Ease!', 'formidable' ),
484	'message' => esc_html( $message ),
485	'slidein' => esc_html( $message ),
486	'cta' => '<a href="' . esc_url( self::$page_url ) . '" class="button-primary frm-button-primary" target="_blank" rel="noopener noreferrer">' . esc_html__( 'Begin Setup', 'formidable' ) . '</a>', // phpcs:ignore SlevomatCodingStandard.Files.LineLength.LineTooLong
487	'created' => time(),
488	'key' => 'onboarding_wizard',
489	);
490
491	return $inbox_messages;
492	}
493
494	/**
495	* Check if the current page is the Onboarding Wizard page.
496	*
497	* @since 6.9
498	*
499	* @return bool True if the current page is the Onboarding Wizard page, false otherwise.
500	*/
501	public static function is_onboarding_wizard_page() {
502	return FrmAppHelper::is_admin_page( self::PAGE_SLUG );
503	}
504
505	/**
506	* Checks if the plugin has already performed a redirect to avoid repeated redirections.
507	*
508	* @return bool Returns true if already redirected, otherwise false.
509	*/
510	private static function has_already_redirected() {
511	if ( get_option( self::REDIRECT_STATUS_OPTION ) ) {
512	return true;
513	}
514
515	update_option( self::REDIRECT_STATUS_OPTION, FrmAppHelper::plugin_version(), false );
516	return false;
517	}
518
519	/**
520	* Get the path to the Onboarding Wizard views.
521	*
522	* @since 6.9
523	*
524	* @return string Path to views.
525	*/
526	public static function get_page_url() {
527	return self::$page_url;
528	}
529
530	/**
531	* Set the URL to access the Onboarding Wizard's page.
532	*
533	* @return void
534	*/
535	private static function set_page_url() {
536	self::$page_url = admin_url( 'admin.php?page=' . self::PAGE_SLUG );
537	}
538
539	/**
540	* Get the list of add-ons available for installation.
541	*
542	* @since 6.9
543	*
544	* @return array A list of add-ons.
545	*/
546	public static function get_available_addons() {
547	return self::$available_addons;
548	}
549
550	/**
551	* Set the list of add-ons available for installation.
552	*
553	* @since 6.9
554	*
555	* @return void
556	*/
557	private static function set_available_addons() {
558	$pro_is_installed = FrmAppHelper::pro_is_installed();
559	$plugins = get_plugins();
560
561	// Base add-ons always included.
562	self::$available_addons['spam-protection'] = array(
563	'title' => esc_html__( 'Spam Protection', 'formidable' ),
564	'is-checked' => true,
565	'is-disabled' => true,
566	'help-text' => esc_html__( 'Get anti-spam options like reCAPTCHA, hCaptcha, Akismet, Turnstile and the blocklist.', 'formidable' ),
567	);
568	self::$available_addons['stripe-payments'] = array(
569	'title' => esc_html__( 'Stripe Payments', 'formidable' ),
570	'is-checked' => true,
571	'is-disabled' => true,
572	'help-text' => esc_html__( 'Collect donations and payments with your forms. Offer physical products, digital goods, services, and more.', 'formidable' ),
573	);
574
575	// Add-ons included when Pro is not installed.
576	if ( ! $pro_is_installed ) {
577	self::$available_addons['visual-styler'] = array(
578	'title' => esc_html__( 'Visual Styler', 'formidable' ),
579	'is-checked' => true,
580	'is-disabled' => true,
581	'help-text' => esc_html__( 'Customize form appearance with an intuitive styling interface.', 'formidable' ),
582	);
583	self::$available_addons['save-entries'] = array(
584	'title' => esc_html__( 'Save Entries', 'formidable' ),
585	'is-checked' => true,
586	'is-disabled' => true,
587	'help-text' => esc_html__( 'Save form submissions to your database for future reference and analysis.', 'formidable' ),
588	);
589	}
590
591	// SMTP add-on if wp_mail_smtp is not installed.
592	if ( ! function_exists( 'wp_mail_smtp' ) ) {
593	$wp_mail_smtp_plugin = 'wp-mail-smtp/wp_mail_smtp.php';
594	$is_installed_wp_mail_smtp = array_key_exists( $wp_mail_smtp_plugin, $plugins );
595
596	self::$available_addons['wp-mail-smtp'] = array(
597	'title' => esc_html__( 'SMTP', 'formidable' ),
598	'rel' => $is_installed_wp_mail_smtp ? $wp_mail_smtp_plugin : 'wp-mail-smtp',
599	'is-checked' => false,
600	'is-vendor' => true,
601	'is-installed' => $is_installed_wp_mail_smtp,
602	'help-text' => esc_html__( 'Improve email deliverability by routing WordPress emails through SMTP.', 'formidable' ),
603	);
604	}
605
606	// Add-ons available when Pro is installed.
607	if ( $pro_is_installed ) {
608	$available_pro_addons = array(
609	'formidable-views' => array(
610	'addon_key' => 'views',
611	'title' => __( 'Views', 'formidable' ),
612	'plugin_file' => 'formidable-views/formidable-views.php',
613	),
614	'formidable-mailchimp' => array(
615	'addon_key' => 'mailchimp',
616	'title' => __( 'Mailchimp', 'formidable' ),
617	'plugin_file' => 'formidable-mailchimp/formidable-mailchimp.php',
618	),
619	'formidable-registration' => array(
620	'addon_key' => 'registration',
621	'title' => __( 'User Registration', 'formidable' ),
622	'plugin_file' => 'formidable-registration/formidable-registration.php',
623	),
624	'formidable-api' => array(
625	'addon_key' => 'api',
626	'title' => __( 'Form Rest API', 'formidable' ),
627	'plugin_file' => 'formidable-api/formidable-api.php',
628	),
629	'formidable-signature' => array(
630	'addon_key' => 'signature',
631	'title' => __( 'Signature Forms', 'formidable' ),
632	'plugin_file' => 'formidable-signature/signature.php',
633	),
634	);
635
636	// Include ACF Forms add-on if ACF is installed.
637	if ( class_exists( 'ACF' ) ) {
638	$available_pro_addons['formidable-acf'] = array(
639	'addon_key' => 'acf',
640	'title' => __( 'ACF Forms', 'formidable' ),
641	'plugin_file' => 'formidable-acf/formidable-acf.php',
642	);
643	}
644
645	foreach ( $available_pro_addons as $key => $data ) {
646	$addon = FrmAddonsController::get_addon( $data['addon_key'] );
647	$plugin_file = $data['plugin_file'];
648
649	if ( is_plugin_active( $plugin_file ) \|\| ! isset( $addon['url'] ) ) {
650	continue;
651	}
652
653	$is_installed = array_key_exists( $plugin_file, $plugins );
654
655	self::$available_addons[ $key ] = array(
656	'title' => $data['title'],
657	'rel' => $is_installed ? $plugin_file : $addon['url'],
658	'is-checked' => false,
659	'is-installed' => $is_installed,
660	'help-text' => $addon['excerpt'],
661	);
662	}
663	}//end if
664
665	// Gravity Forms Migrator add-on.
666	$gravity_forms_plugin = 'formidable-gravity-forms-importer/formidable-gravity-forms-importer.php';
667
668	if ( ! class_exists( 'GFForms' ) \|\| is_plugin_active( $gravity_forms_plugin ) ) {
669	return;
670	}
671
672	$is_installed_gravity_forms = array_key_exists( $gravity_forms_plugin, $plugins );
673
674	self::$available_addons['formidable-gravity-forms-importer'] = array(
675	'title' => esc_html__( 'Gravity Forms Migrator', 'formidable' ),
676	'rel' => $is_installed_gravity_forms ? $gravity_forms_plugin : 'formidable-gravity-forms-importer',
677	'is-checked' => false,
678	'is-vendor' => true,
679	'is-installed' => $is_installed_gravity_forms,
680	'help-text' => esc_html__( 'Easily migrate your forms from Gravity Forms to Formidable.', 'formidable' ),
681	);
682	}
683
684	/**
685	* Get the path to the Onboarding Wizard views.
686	*
687	* @since 6.9
688	*
689	* @return string Path to views.
690	*/
691	public static function get_view_path() {
692	return self::$view_path;
693	}
694
695	/**
696	* Get the upgrade link.
697	*
698	* @since 6.9
699	*
700	* @return string URL for upgrading accounts.
701	*/
702	public static function get_upgrade_link() {
703	return self::$upgrade_link;
704	}
705
706	/**
707	* Retrieves the current Onboarding Wizard usage data, returning an empty array if none exists.
708	*
709	* @since 6.9
710	*
711	* @return array Current usage data.
712	*/
713	public static function get_usage_data() {
714	return get_option( self::USAGE_DATA_OPTION, array() );
715	}
716
717	/**
718	* Validates if the Onboarding Wizard page is being displayed.
719	*
720	* @since 6.9
721	* @deprecated 6.16
722	*
723	* @return bool True if the Onboarding Wizard page is displayed, false otherwise.
724	*/
725	public static function is_onboarding_wizard_displayed() {
726	_deprecated_function( __METHOD__, '6.16' );
727	return get_transient( self::TRANSIENT_NAME ) === self::TRANSIENT_VALUE;
728	}
729	}
730