<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- File name follows plugin slug convention; class name cannot be changed without breaking the codebase.
/**
* Admin controller for the Complianz Terms & Conditions plugin.
*
* Defines the cmplz_tc_admin singleton class which manages all WordPress
* admin integration: asset enqueuing, menu registration (standalone or nested
* under the Complianz GDPR plugin), plugin action links, activation redirect,
* companion-plugin status links, and the upgrade routine. All hooks are
* registered in the constructor so the class is self-contained.
*
* @package Complianz_Terms_Conditions
* @subpackage Admin
* @author Complianz
* @copyright 2023 Complianz.io
* @license GPL-2.0-or-later
* @link https://complianz.io
*
* @since 1.0.0
*/
// Prevent direct file access outside of the WordPress bootstrap.
defined( 'ABSPATH' ) || die( 'you do not have acces to this page!' );
if ( ! class_exists( 'cmplz_tc_admin' ) ) {
// phpcs:disable PEAR.NamingConventions.ValidClassName.StartWithCapital, PEAR.NamingConventions.ValidClassName.Invalid, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedClassFound -- Established public API; class name cannot be changed without breaking all callers.
/**
* Admin controller singleton for the Complianz T&C plugin.
*
* Registers all admin-area hooks and provides helper methods used by
* templates and other classes. Only one instance is ever created; access
* it through COMPLIANZ_TC::$admin.
*
* @package Complianz_Terms_Conditions
* @subpackage Admin
*
* @since 1.0.0
*/
class cmplz_tc_admin {
// phpcs:enable PEAR.NamingConventions.ValidClassName.StartWithCapital, PEAR.NamingConventions.ValidClassName.Invalid, WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedClassFound
/**
* Holds the single instance of this class (singleton pattern).
*
* @since 1.0.0
* @access private
* @var cmplz_tc_admin|null
*/
private static $_this; // phpcs:ignore PSR2.Classes.PropertyDeclaration.Underscore -- Underscore prefix is part of the established singleton accessor pattern used throughout this codebase.
/**
* Error message to display in the admin area after a failed operation.
*
* @since 1.0.0
* @access public
* @var string
*/
public $error_message = '';
/**
* Success message to display in the admin area after a successful operation.
*
* @since 1.0.0
* @access public
* @var string
*/
public $success_message = '';
/**
* Initialises the admin controller and registers all WordPress hooks.
*
* Guards against a second instantiation (singleton). When the Complianz
* GDPR/CCPA plugin is active (`cmplz_version` defined) the T&C menu
* page is nested under the Complianz top-level menu via the
* `cmplz_admin_menu` action; otherwise a standalone "Tools > Terms &
* Conditions" submenu is registered. Plugin action links are added for
* both the standard and network admin plugins screens.
*
* @since 1.0.0
* @access public
*/
public function __construct() {
if ( isset( self::$_this ) ) {
wp_die(
esc_html(
sprintf(
'%s is a singleton class and you cannot create a second instance.',
get_class( $this )
)
)
);
}
self::$_this = $this;
// Enqueue admin styles and scripts on T&C plugin screens.
add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_assets' ) );
// Register the admin menu: nest under Complianz when available, otherwise use Tools.
if ( ! defined( 'cmplz_version' ) ) {
add_action( 'admin_menu', array( $this, 'register_main_menu' ), 20 );
} else {
add_action( 'cmplz_admin_menu', array( $this, 'register_admin_page' ), 20 );
}
// Add Settings and Support links to the Plugins list table.
$plugin = cmplz_tc_plugin;
add_filter( "plugin_action_links_$plugin", array( $this, 'plugin_settings_link' ) );
add_filter( "network_admin_plugin_action_links_$plugin", array( $this, 'plugin_settings_link' ) );
// Run the upgrade check and activation redirect on every admin_init.
add_action( 'admin_init', array( $this, 'check_upgrade' ), 10, 2 );
add_action( 'admin_init', array( $this, 'maybe_redirect_to_settings' ), 10, 2 );
}
/**
* Returns the single instance of this class.
*
* @since 1.0.0
* @access public
*
* @return cmplz_tc_admin The singleton instance.
*/
public static function this() {
return self::$_this;
}
/**
* Redirects the user to the plugin settings page after first activation.
*
* Consumes the `cmplz_tc_redirect_to_settings` transient set by
* `cmplz_tc_activation()`. The transient is deleted before the redirect
* to ensure it fires only once and is not triggered by subsequent page
* loads. Hooked to `admin_init`.
*
* @since 1.0.0
* @access public
*
* @see cmplz_tc_activation() Sets the transient on plugin activation.
*
* @return void
*/
public function maybe_redirect_to_settings() {
if ( get_transient( 'cmplz_tc_redirect_to_settings' ) ) {
// Delete the transient first so the redirect only happens once.
delete_transient( 'cmplz_tc_redirect_to_settings' );
wp_safe_redirect( add_query_arg( array( 'page' => 'terms-conditions' ), admin_url( 'admin.php' ) ) );
exit;
}
}
/**
* Returns the install, upgrade, or "Installed" status link for a companion plugin.
*
* Determines the current state of a companion plugin by checking whether
* its free or premium PHP constants are defined, then returns the
* appropriate HTML anchor or plain-text label:
*
* - Neither free nor premium active → "Install" link to wordpress.org search.
* - Free active but no premium → "Upgrade to pro" link to the plugin website.
* - Premium (or wpsi_plugin) active → Plain "Installed" text (no action needed).
*
* @since 1.0.0
* @access public
*
* @see templates/wizard/other-plugins.php Calls this method for each plugin card.
*
* @param array $item Plugin descriptor array with keys:
* - `constant_free` (string) PHP constant for the free edition.
* - `constant_premium` (string) PHP constant for the premium edition.
* - `search` (string) WordPress.org search query string.
* - `website` (string) URL to the premium/pricing page.
* @return string HTML anchor tag or plain-text status label.
*/
public function get_status_link( $item ) {
$status = '';
if ( ! defined( $item['constant_free'] ) && ! defined( $item['constant_premium'] ) ) {
// Plugin is not installed: link to the wordpress.org search results.
$link = admin_url() . 'plugin-install.php?s=' . $item['search'] . '&tab=search&type=term';
$text = __( 'Install', 'complianz-terms-conditions' );
$status = '<a href="' . esc_url( $link ) . '">' . esc_html( $text ) . '</a>';
} elseif ( 'wpsi_plugin' === $item['constant_free'] || defined( $item['constant_premium'] ) ) {
// Premium (or a special-cased plugin) is active: no further action required.
$status = esc_html__( 'Installed', 'complianz-terms-conditions' );
} elseif ( defined( $item['constant_free'] ) && ! defined( $item['constant_premium'] ) ) {
// Free edition is active but premium is not: offer an upgrade link.
$link = $item['website'];
$text = __( 'Upgrade to pro', 'complianz-terms-conditions' );
$status = '<a href="' . esc_url( $link ) . '">' . esc_html( $text ) . '</a>';
}
return $status;
}
/**
* Runs version-specific upgrade routines and updates the stored version number.
*
* Compares the previously stored plugin version against known migration
* thresholds and applies any required data changes. After all migrations
* are complete it fires the `cmplz_tc_upgrade` action (used by add-ons)
* and writes the current version to the database.
*
* Note: when SCRIPT_DEBUG is enabled, a timestamp is appended to
* `cmplz_tc_version`; the stored option value is compared without the
* timestamp by reading it directly from the database.
*
* Hooked to: admin_init (priority 10).
*
* @since 1.0.0
* @access public
*
* @return void
*/
public function check_upgrade() {
// Read the previously stored version; false when the plugin has never been upgraded.
$prev_version = get_option( 'cmplz-tc-current-version', false );
if ( $prev_version
&& version_compare( $prev_version, '1.0.4', '<' )
) {
// Migration for < 1.0.4: re-save the documents update date to trigger a regeneration.
update_option( 'cmplz_tc_documents_update_date', get_option( 'cmplz_tc_documents_update_date' ) );
}
if ( $prev_version
&& version_compare( $prev_version, '1.3.1', '<' )
) {
// Migration for < 1.3.1 (EU Directive 2023/2673): clear stored withdrawal
// links that point to our own default/generated PDF, so users are prompted
// to add a real withdrawal-function link. Deliberate custom links are kept.
$options = get_option( 'complianz_tc_options_terms-conditions' );
if ( is_array( $options ) && ! empty( $options['if_returns_custom_link'] ) ) {
$link = $options['if_returns_custom_link'];
if ( false !== strpos( $link, 'custom-withdrawal-form.pdf' )
|| false !== strpos( $link, '/complianz/withdrawal-forms/withdrawal-form-' )
) {
$options['if_returns_custom_link'] = '';
update_option( 'complianz_tc_options_terms-conditions', $options );
}
}
}
if ( $prev_version
&& version_compare( $prev_version, '1.4.0', '<' )
) {
// Migration for < 1.4.0 (EU Directive 2023/2673): the legacy withdrawal-form
// PDF generation has been removed. Drop its language queue option and purge
// any stale generated withdrawal PDFs. The Terms & Conditions document PDF
// (generate_pdf + download.php) is unaffected.
delete_option( 'cmplz_generate_pdf_languages' );
$this->remove_withdrawal_pdf_dir();
// Pre-1.4.0 installs never saw the "Complianz form vs. own link" choice, so keep them
// on the own-link path rather than letting the new 'no' default silently opt them into
// the Complianz form; only a fresh install (no prior T&C options) defaults to the form.
$tc_options = get_option( 'complianz_tc_options_terms-conditions' );
if ( is_array( $tc_options ) && ! isset( $tc_options['if_returns_custom'] ) ) {
$tc_options['if_returns_custom'] = 'yes';
update_option( 'complianz_tc_options_terms-conditions', $tc_options );
}
}
/**
* Fires after version-specific upgrade routines have been applied.
*
* Add-ons can hook here to run their own migration logic.
*
* @since 1.0.0
*
* @param string|false $prev_version The version string stored before this upgrade, or false on first run.
*/
do_action( 'cmplz_tc_upgrade', $prev_version );
// Persist the current version so future requests can detect upgrades.
update_option( 'cmplz-tc-current-version', cmplz_tc_version );
}
/**
* Delete the legacy generated-withdrawal-forms directory and its PDFs.
*
* The directory (uploads/complianz/withdrawal-forms/) only ever held the
* now-removed withdrawal-form PDFs, so it can be purged wholesale. Uses
* WP's wp_delete_file() for the files and a direct rmdir() for the empty
* directory (WordPress provides no filesystem helper for that). Missing
* directories are a no-op.
*
* @since 1.4.0
* @access private
*
* @return void
*/
private function remove_withdrawal_pdf_dir() {
$uploads = wp_upload_dir();
$withdrawal_dir = trailingslashit( $uploads['basedir'] ) . 'complianz/withdrawal-forms';
if ( ! is_dir( $withdrawal_dir ) ) {
return;
}
foreach ( (array) glob( $withdrawal_dir . '/*' ) as $file ) {
if ( is_file( $file ) ) {
wp_delete_file( $file );
}
}
rmdir( $withdrawal_dir ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_rmdir -- Removing an empty uploads subdirectory; WP_Filesystem is not reliably available in the upgrade context.
}
/**
* Enqueues admin stylesheet and script on T&C plugin screens.
*
* Runs on `admin_enqueue_scripts` and bails immediately for any admin
* page that is not part of the T&C plugin (detected by checking whether
* `'terms-conditions'` appears in the hook suffix). In non-debug mode
* the `.min` variants of all assets are loaded; in SCRIPT_DEBUG mode
* the un-minified sources are used. The admin AJAX URL and a nonce are
* passed to the script via `wp_localize_script()`.
*
* @since 1.0.0
* @access public
*
* @param string $hook The current admin page hook suffix
* (e.g. `'tools_page_terms-conditions'`).
* @return void
*/
public function enqueue_assets( $hook ) {
// Only enqueue assets on screens that belong to this plugin.
if ( false === strpos( $hook, 'terms-conditions' ) ) {
return;
}
// Remove any conflicting Complianz GDPR wizard stylesheet.
wp_dequeue_style( 'cmplz-wizard' );
// Use un-minified assets when SCRIPT_DEBUG is active.
$minified = ( defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ) ? '' : '.min';
wp_register_style( 'cmplz-tc', trailingslashit( cmplz_tc_url ) . "assets/css/admin$minified.css", array(), cmplz_tc_version );
wp_enqueue_style( 'cmplz-tc' );
wp_register_style( 'cmplz-tc-tips-tricks', trailingslashit( cmplz_tc_url ) . "assets/css/tips-tricks$minified.css", array(), cmplz_tc_version );
wp_enqueue_style( 'cmplz-tc-tips-tricks' );
wp_enqueue_script( 'cmplz-tc-admin', cmplz_tc_url . "assets/js/admin$minified.js", array( 'jquery' ), cmplz_tc_version, true );
// Pass the AJAX endpoint URL and a save nonce to the admin JavaScript.
wp_localize_script(
'cmplz-tc-admin',
'complianz_tc_admin',
array(
'admin_url' => admin_url( 'admin-ajax.php' ),
'nonce' => wp_create_nonce( 'complianz_tc_save' ),
)
);
}
/**
* Prepends Settings and Support links to the plugin's action links row.
*
* Hooked to both `plugin_action_links_{plugin}` (single-site) and
* `network_admin_plugin_action_links_{plugin}` (multisite). The Support
* link points to WordPress.org for the free edition and to
* complianz.io/support for the premium edition.
*
* @since 1.0.0
* @access public
*
* @param array $links Existing action links for the plugin row.
* @return array Modified links array with Settings and Support prepended.
*/
public function plugin_settings_link( $links ) {
// Prepend the Settings link; placed after Support due to unshift order.
$settings_link = '<a href="'
. esc_url( cmplz_tc_settings_page() )
. '" class="cmplz-tc-settings-link">'
. esc_html__( 'Settings', 'complianz-terms-conditions' ) . '</a>';
array_unshift( $links, $settings_link );
// Link to WP.org support for free users; to complianz.io for premium.
$support_link = defined( 'cmplz_free' )
? 'https://wordpress.org/support/plugin/complianz-terms-conditions'
: 'https://complianz.io/support';
$faq_link = '<a target="_blank" href="' . esc_url( $support_link ) . '">'
. esc_html__( 'Support', 'complianz-terms-conditions' ) . '</a>';
array_unshift( $links, $faq_link );
return $links;
}
/**
* Registers a standalone "Terms & Conditions" submenu page under Tools.
*
* Used when the Complianz GDPR/CCPA plugin is not active. Capability-
* gated via `cmplz_tc_user_can_manage()`. After adding the submenu the
* `cmplz_admin_menu` action is fired so that add-ons can register their
* own sub-items under this menu.
*
* Hooked to: admin_menu (priority 20).
*
* @since 1.0.0
* @access public
*
* @see cmplz_tc_user_can_manage() Capability check.
* @see register_admin_page() Alternative used when Complianz GDPR is active.
*
* @return void
*/
public function register_main_menu() {
if ( ! cmplz_tc_user_can_manage() ) {
return;
}
global $cmplz_admin_page;
$cmplz_admin_page = add_submenu_page(
'tools.php', // Parent menu slug.
__( 'Terms & Conditions', 'complianz-terms-conditions' ), // Page title.
__( 'Terms & Conditions', 'complianz-terms-conditions' ), // Menu label.
'manage_options', // Required capability.
'terms-conditions', // Menu slug.
array( $this, 'wizard_page' ), // Page render callback.
40 // Menu position.
);
/**
* Fires after the standalone T&C admin menu has been registered.
*
* Add-ons hook here to append sub-items under the T&C menu entry.
*
* @since 1.0.0
*/
do_action( 'cmplz_admin_menu' );
}
/**
* Registers a "Terms & Conditions" submenu page nested under the Complianz GDPR menu.
*
* Used when the Complianz GDPR/CCPA plugin is active and has already
* registered its top-level `complianz` menu. Capability-gated via
* `cmplz_tc_user_can_manage()`.
*
* Hooked to: cmplz_admin_menu (priority 20).
*
* @since 1.0.0
* @access public
*
* @see cmplz_tc_user_can_manage() Capability check.
* @see register_main_menu() Alternative used when Complianz GDPR is absent.
*
* @return void
*/
public function register_admin_page() {
if ( ! cmplz_tc_user_can_manage() ) {
return;
}
add_submenu_page(
'complianz', // Parent menu slug (Complianz GDPR).
__( 'Terms & Conditions', 'complianz-terms-conditions' ), // Page title.
__( 'Terms & Conditions', 'complianz-terms-conditions' ), // Menu label.
'manage_options', // Required capability.
'terms-conditions', // Menu slug.
array( $this, 'wizard_page' ) // Page render callback.
);
}
/**
* Renders the wizard admin page for the Terms & Conditions document type.
*
* Delegates entirely to `cmplz_tc_wizard::wizard()`, which builds and
* outputs the full wizard UI including the admin wrap, sidebar menu,
* and step content. Registered as the `page_callback` for both
* `register_main_menu()` and `register_admin_page()`.
*
* @since 1.0.0
* @access public
*
* @see cmplz_tc_wizard::wizard() Outputs the full wizard HTML.
*
* @return void
*/
public function wizard_page() {
COMPLIANZ_TC::$wizard->wizard( 'terms-conditions' );
}
/**
* Outputs a tooltip icon with the provided help text as a data attribute.
*
* Renders a dashicon question-mark element whose tooltip content is set
* via the `data-cmplz-tooltip` attribute and revealed by CSS/JS on hover.
* The caller is responsible for escaping `$str` before passing it in.
*
* @since 1.0.0
* @access public
*
* @param string $str Pre-escaped help text to display in the tooltip.
* @return void
*/
public function get_help_tip( $str ) {
?>
<span class="cmplz-tooltip-right tooltip-right"
data-cmplz-tooltip="<?php echo esc_attr( $str ); ?>">
<span class="dashicons dashicons-editor-help"></span>
</span>
<?php
}
}
} // class closure