SmartCT Plugin
Documentation
Overview
SmartCT is a WordPress plugin that integrates Cloudflare
Turnstile CAPTCHA protection with WordPress forms. It provides
lightweight and privacy-first protection for login, registration,
password reset, comments, and WooCommerce forms.
Plugin Details:
- Version: 1.0.0
- Requires WordPress: 5.8+
- Requires PHP: 7.4+
- Author: Mayank Majeji
- License: GPL v2 or later
Plugin Architecture
Main Files Structure
turnstilewp/
├── turnstilewp.php - Main plugin file
├── includes/ - Core plugin classes
│ ├── class-init.php - Plugin initialization
│ ├── class-loader.php - Autoloader
│ ├── class-settings.php - Settings management
│ ├── class-verify.php - Token verification
│ ├── class-ajax-handlers.php - AJAX functionality
│ ├── functions-common.php - Common utility functions
│ └── settings/ - Settings framework
├── integrations/ - Form integrations
│ ├── class-turnstile.php - Main Turnstile widget
│ ├── class-core-wp.php - WordPress core forms
│ └── class-woocommerce.php - WooCommerce integration
├── admin/ - Admin interface
├── templates/ - Template files
└── assets/ - CSS/JS assets
Core Functions Documentation
1. Main Plugin File
(turnstilewp.php)
Global Functions
turnstilewp_init()
- Purpose: Initialize the plugin after WordPress
loads
- Parameters: None
- Returns: void
- Description: Loads text domain, initializes the
main plugin class as singleton
- Hook:
plugins_loaded
Anonymous Activation Hook
Function
- Purpose: Handle plugin activation
- Parameters: None
- Returns: void
- Description: Requires the Init class and calls the
activate method
Anonymous Deactivation
Hook Function
- Purpose: Handle plugin deactivation
- Parameters: None
- Returns: void
- Description: Requires the Init class and calls the
deactivate method
Global Constants
TURNSTILEWP_VERSION: Plugin version (1.0.0)
TURNSTILEWP_PLUGIN_DIR: Plugin directory path
TURNSTILEWP_PLUGIN_URL: Plugin URL
TURNSTILEWP_PLUGIN_BASENAME: Plugin basename
2. Init Class
(includes/class-init.php)
Class Properties
$settings: Settings instance
$verify: Verify instance
$ajax_handlers: AJAX handlers instance
$admin_hooks_registered: Static flag to prevent
duplicate admin hooks
$instance: Singleton instance
Methods
get_instance(): Init
- Purpose: Get singleton instance of the Init
class
- Parameters: None
- Returns: Init instance
- Description: Implements singleton pattern for
plugin initialization
init(): void
- Purpose: Initialize the plugin components
- Parameters: None
- Returns: void
- Description: Loads dependencies, initializes
components, sets up integrations and hooks
load_dependencies(): void
- Purpose: Load required plugin dependencies
- Parameters: None
- Returns: void
- Description: Includes common functions file
init_hooks(): void
- Purpose: Initialize WordPress hooks
- Parameters: None
- Returns: void
- Description: Sets up admin and frontend hooks for
the plugin
enqueue_admin_assets(): void
- Purpose: Enqueue admin-specific CSS and
JavaScript
- Parameters: None
- Returns: void
- Description: Loads admin styles, Turnstile API
script, and admin settings JavaScript on plugin pages
enqueue_frontend_assets(): void
- Purpose: Enqueue frontend CSS and JavaScript
- Parameters: None
- Returns: void
- Description: Loads Turnstile API script and
frontend styles when needed
should_load_turnstile(): bool
- Purpose: Determine if Turnstile should be loaded on
current page
- Parameters: None
- Returns: bool - Whether to load Turnstile
- Description: Checks user login status, page type,
and settings to determine if Turnstile is needed
activate(): void
- Purpose: Handle plugin activation tasks
- Parameters: None
- Returns: void
- Description: Initializes settings and adds default
options
deactivate(): void
- Purpose: Handle plugin deactivation tasks
- Parameters: None
- Returns: void
- Description: Placeholder for cleanup tasks
verify_keys_ajax(): void
- Purpose: Handle AJAX request for key
verification
- Parameters: None (uses $_POST data)
- Returns: void (outputs JSON)
- Description: Verifies Cloudflare API keys via
AJAX
remove_keys_ajax(): void
- Purpose: Handle AJAX request for removing API
keys
- Parameters: None (uses $_POST data)
- Returns: void (outputs JSON)
- Description: Removes stored API keys and
verification status
get_client_ip(): string
- Purpose: Get client IP address
- Parameters: None
- Returns: string - Client IP address
- Description: Extracts client IP from various server
headers
init_integrations(): void
- Purpose: Initialize form integrations
- Parameters: None
- Returns: void
- Description: Creates instances of Core_WP and
WooCommerce integration classes
3. Loader Class
(includes/class-loader.php)
Static Methods
register(): void
- Purpose: Register the autoloader and load
integrations
- Parameters: None
- Returns: void
- Description: Registers SPL autoloader and loads all
integration files
autoload(string $class): void
- Purpose: Autoload classes in the SmartCT
namespace
- Parameters:
$class: Full class name including namespace
- Returns: void
- Description: Converts class names to file paths and
loads class files
load_integrations(): void
- Purpose: Load all integration class files
- Parameters: None
- Returns: void
- Description: Automatically includes all class files
in the integrations directory
4. Settings Class
(includes/class-settings.php)
Class Properties
OPTION_NAME: WordPress option name
(‘turnstilewp_settings’)
$defaults: Array of default setting values
$fields: Centralized settings fields array
Methods
__construct()
- Purpose: Initialize settings class
- Parameters: None
- Description: Adds default options and registers
centralized fields
get_settings(): array
- Purpose: Get all plugin settings
- Parameters: None
- Returns: array - All plugin settings merged with
defaults
- Description: Retrieves settings from WordPress
options table
get_option(string $key, $default = null)
- Purpose: Get a specific setting value
- Parameters:
$key: Setting key name
$default: Default value if not found
- Returns: mixed - Setting value or default
- Description: Retrieves individual setting
value
add_default_options(): void
- Purpose: Add default options to database
- Parameters: None
- Returns: void
- Description: Creates initial settings in WordPress
options table
register_settings(): void
- Purpose: Register settings with WordPress Settings
API
- Parameters: None
- Returns: void
- Description: Registers the main settings group with
sanitization callback
- Purpose: Sanitize settings input
- Parameters:
$input: Raw input array from form submission
- Returns: array - Sanitized settings array
- Description: Validates and sanitizes all setting
values based on field types
- Purpose: Add admin menu pages
- Parameters: None
- Returns: void
- Description: Creates main menu and submenu pages
for the plugin
render_dashboard_page(): void
- Purpose: Render the dashboard page
- Parameters: None
- Returns: void
- Description: Includes dashboard template file
render_integrations_page(): void
- Purpose: Render the integrations page
- Parameters: None
- Returns: void
- Description: Includes integrations template
file
render_settings_main_page(): void
- Purpose: Render the main settings page
- Parameters: None
- Returns: void
- Description: Includes settings template file
render_tools_page(): void
- Purpose: Render the tools page
- Parameters: None
- Returns: void
- Description: Includes tools template file
render_faqs_page(): void
- Purpose: Render the FAQs page
- Parameters: None
- Returns: void
- Description: Includes FAQs template file
register_centralized_fields(): void
- Purpose: Register all settings fields in
centralized system
- Parameters: None
- Returns: void
- Description: Sets up the organized field structure
for settings
organize_fields(array $fields): array
- Purpose: Organize fields by tabs and sections
- Parameters:
$fields: Array of field definitions
- Returns: array - Organized field structure
- Description: Groups fields into hierarchical
structure for rendering
get_fields_structure(): array
- Purpose: Get the organized fields structure
- Parameters: None
- Returns: array - Organized fields by tab and
section
- Description: Returns the complete field
organization for rendering
5. Verify Class
(includes/class-verify.php)
Class Properties
$settings: Settings instance
Methods
__construct()
- Purpose: Initialize verification class
- Parameters: None
- Description: Creates Settings instance for
accessing configuration
verify_token(string $token, ?string $custom_secret_key = null): bool
- Purpose: Verify Turnstile token with Cloudflare
API
- Parameters:
$token: Turnstile response token
$custom_secret_key: Optional custom secret key for
admin verification
- Returns: bool - Whether verification was
successful
- Description: Sends verification request to
Cloudflare Turnstile API
get_client_ip(): string
- Purpose: Get client IP address for
verification
- Parameters: None
- Returns: string - Client IP address
- Description: Extracts client IP from various server
headers
log_error(string $message): void
- Purpose: Log error messages when debug mode is
enabled
- Parameters:
$message: Error message to log
- Returns: void
- Description: Writes error messages to WordPress
error log if debug mode is active
6. Ajax
Handlers Class (includes/class-ajax-handlers.php)
Methods
__construct()
- Purpose: Initialize AJAX handlers
- Parameters: None
- Description: Registers AJAX action hooks
export_settings(): void
- Purpose: Export plugin settings as JSON file
- Parameters: None (uses $_GET data)
- Returns: void (outputs file download)
- Description: Verifies permissions and nonce, then
exports settings as downloadable JSON
7. Common
Functions (includes/functions-common.php)
Utility Functions
is_login(): bool
- Purpose: Check if current page is login page
- Parameters: None
- Returns: bool - Whether on login page
- Description: Determines if user is on
wp-login.php
is_registration_page(): bool
- Purpose: Check if current page is registration
page
- Parameters: None
- Returns: bool - Whether on registration page
- Description: Checks for wp-login.php with register
action
is_lost_password_page(): bool
- Purpose: Check if current page is lost password
page
- Parameters: None
- Returns: bool - Whether on lost password page
- Description: Checks for wp-login.php with
lostpassword action
- Purpose: Check if current page has comment
form
- Parameters: None
- Returns: bool - Whether page has comment form
- Description: Determines if page is singular and
comments are open
8.
Turnstile Integration Class
(integrations/class-turnstile.php)
Class Properties
$settings: Settings instance
Methods
__construct()
- Purpose: Initialize Turnstile integration
- Parameters: None
- Description: Creates Settings instance and hooks
into WordPress actions
enqueue_script(): void
- Purpose: Enqueue Turnstile JavaScript API
- Parameters: None
- Returns: void
- Description: Loads Cloudflare Turnstile script when
site key is configured
render(string $action): void
- Purpose: Render Turnstile widget
- Parameters:
$action: Action name for the widget
- Returns: void
- Description: Outputs Turnstile widget HTML with
configured settings
verify(?string $token = null): bool
- Purpose: Verify Turnstile response token
- Parameters:
$token: Optional token (uses POST data if not
provided)
- Returns: bool - Verification result
- Description: Verifies token with Cloudflare
API
render_dynamic(array $args = []): void
- Purpose: Render Turnstile widget with dynamic
configuration
- Parameters:
$args: Array of rendering arguments
- Returns: void
- Description: Renders widget with customizable
attributes and hooks
9.
Core WordPress Integration
(integrations/class-core-wp.php)
Class Properties
$settings: Settings instance
$verify: Verify instance
Methods
__construct()
- Purpose: Initialize WordPress core integration
- Parameters: None
- Description: Sets up Settings and Verify instances,
initializes hooks
init_hooks(): void
- Purpose: Initialize hooks for WordPress core
forms
- Parameters: None
- Returns: void
- Description: Sets up hooks for login, registration,
password reset, and comment forms
render_turnstile_field(): void
- Purpose: Render Turnstile field for core WordPress
forms
- Parameters: None
- Returns: void
- Description: Outputs Turnstile widget if keys are
verified and conditions are met
get_form_context(): string
- Purpose: Determine current form context
- Parameters: None
- Returns: string - Form context identifier
- Description: Uses current filter to identify which
form is being processed
verify_login($user, string $username, string $password)
- Purpose: Verify Turnstile for login attempts
- Parameters:
$user: User object or WP_Error from previous
callbacks
$username: Username being verified
$password: Password being verified
- Returns: WP_User|WP_Error - User object or
error
- Description: Validates Turnstile token during login
process
verify_registration(\WP_Error $errors, string $sanitized_user_login, string $user_email): \WP_Error
- Purpose: Verify Turnstile for user
registration
- Parameters:
$errors: Existing registration errors
$sanitized_user_login: Sanitized username
$user_email: User email address
- Returns: WP_Error - Updated errors object
- Description: Adds Turnstile verification to
registration process
verify_lost_password(\WP_Error $errors): \WP_Error
- Purpose: Verify Turnstile for password reset
requests
- Parameters:
$errors: Existing password reset errors
- Returns: WP_Error - Updated errors object
- Description: Validates Turnstile token for password
reset
- Purpose: Verify Turnstile for comment
submissions
- Parameters:
$commentdata: Comment data array
- Returns: array - Comment data (unchanged if
valid)
- Description: Validates Turnstile token before
processing comments
verify_token(): bool
- Purpose: Verify Turnstile token from POST data
- Parameters: None
- Returns: bool - Verification result
- Description: Helper method to verify token using
Verify class
should_show_turnstile(): bool
- Purpose: Check if Turnstile should be
displayed
- Parameters: None
- Returns: bool - Whether to show Turnstile
- Description: Considers user login status and
settings to determine display
10.
WooCommerce Integration
(integrations/class-woocommerce.php)
Class Properties
$settings: Settings instance
Methods
__construct()
- Purpose: Initialize WooCommerce integration
- Parameters: None
- Description: Sets up Settings instance, registers
fields, and initializes hooks
register_settings_fields(): void
- Purpose: Register WooCommerce-specific settings
fields
- Parameters: None
- Returns: void
- Description: Adds WooCommerce form integration
settings to centralized system
init_hooks(): void
- Purpose: Initialize WooCommerce form hooks
- Parameters: None
- Returns: void
- Description: Sets up hooks for various WooCommerce
forms based on settings
add_checkout_hooks(string $location): void
- Purpose: Add checkout hooks based on selected
location
- Parameters:
$location: Where to place the Turnstile widget on
checkout
- Returns: void
- Description: Hooks into appropriate WooCommerce
checkout actions
render_turnstile(): void
- Purpose: Render Turnstile widget for WooCommerce
forms
- Parameters: None
- Returns: void
- Description: Outputs Turnstile widget if keys are
verified
verify_token(): bool
- Purpose: Verify Turnstile token
- Parameters: None
- Returns: bool - Verification result
- Description: Helper method to verify token using
Verify class
verify_turnstile($validation_error, $username, $password): \WP_Error
- Purpose: Verify Turnstile for WooCommerce
login
- Parameters:
$validation_error: Existing validation errors
$username: Login username
$password: Login password
- Returns: WP_Error - Updated validation errors
- Description: Adds Turnstile verification to
WooCommerce login
verify_turnstile_registration($errors, $username, $email): \WP_Error
- Purpose: Verify Turnstile for WooCommerce
registration
- Parameters:
$errors: Existing registration errors
$username: Registration username
$email: Registration email
- Returns: WP_Error - Updated errors
- Description: Validates Turnstile for WooCommerce
user registration
verify_turnstile_reset_password($errors, $user_data): \WP_Error
- Purpose: Verify Turnstile for WooCommerce password
reset
- Parameters:
$errors: Existing reset errors
$user_data: User data for reset
- Returns: WP_Error - Updated errors
- Description: Validates Turnstile for password reset
requests
verify_turnstile_checkout(): void
- Purpose: Verify Turnstile for WooCommerce
checkout
- Parameters: None
- Returns: void
- Description: Validates Turnstile during checkout
process, adds error if failed
verify_turnstile_pay_order(): void
- Purpose: Verify Turnstile for pay-for-order
process
- Parameters: None
- Returns: void
- Description: Validates Turnstile when paying for
existing orders
11. Field
Renderer (includes/settings/field-renderer.php)
Functions
render_setting_field($field, $value)
- Purpose: Render individual settings field
- Parameters:
$field: Field configuration array
$value: Current field value
- Returns: void (outputs HTML)
- Description: Renders form fields based on type
(text, checkbox, select, etc.)
render_setting_fields_grouped($fields, $values)
- Purpose: Render grouped settings fields
- Parameters:
$fields: Array of field configurations
$values: Array of current values
- Returns: void (outputs HTML)
- Description: Renders fields in groups with
appropriate titles and containers
Settings Field Types
The plugin supports various field types for the settings system:
Field Types
- text - Standard text input
- password - Password input (masked)
- email - Email input with validation
- url - URL input with validation
- number - Numeric input
- checkbox - Boolean checkbox with toggle
styling
- select - Dropdown selection
- textarea - Multi-line text input
- content - Static content display
Field Configuration
Each field can have the following properties:
field_id: Unique identifier
label: Display label
description: Help text
type: Field type
default: Default value
options: Options for select fields
tab: Settings tab
section: Settings section
group: Field group
priority: Display order
sanitize_callback: Custom sanitization function
Hooks and Filters
Actions
turnstilewp_before_field: Before widget rendering
turnstilewp_after_field: After widget rendering
- Various WordPress core hooks for form integration
Filters
turnstilewp_settings: Add/modify settings fields
turnstilewp_widget_disable: Conditionally disable
widget
turnstilewp_should_show: Control widget display
Security Features
Token Verification
- Server-side verification with Cloudflare API
- IP address validation
- Nonce verification for admin actions
- Input sanitization and validation
Data Protection
- Sensitive data handling (secret keys)
- Debug logging controls
- Secure AJAX endpoints
- WordPress capability checks
Error Handling
Debug Mode
- Configurable debug logging
- Error message customization
- Detailed verification logs
- Admin notification system
Fallback Behavior
- Graceful degradation when API is unavailable
- User-friendly error messages
- Automatic retry mechanisms
- Admin tools for troubleshooting
Extensibility
Developer Hooks
The plugin provides numerous hooks for customization:
- Field rendering hooks
- Verification process hooks
- Settings modification filters
- Widget display controls
Integration Framework
- Modular integration system
- Easy addition of new form types
- Standardized verification process
- Consistent widget rendering
Database Schema
Options Table
turnstilewp_settings: Main plugin settings
turnstilewp_keys_verified: Key verification status
Transients
turnstilewp_debug_log: Debug logging data
This documentation covers all major functions and classes in the
SmartCT plugin. Each function is documented with its purpose,
parameters, return values, and functionality to provide a complete
reference for developers and users working with this plugin.