Forem: Shahibur Rahman

Demystifying WordPress Plugin License Activation: A Step-by-Step Client-Server Guide

Shahibur Rahman — Sun, 05 Apr 2026 17:12:27 +0000

Understanding WordPress Plugin License Activation can often feel opaque for developers and users. How do commercial plugins truly verify legitimate usage? How are domain limits gracefully enforced without being overly restrictive or easily bypassed? This article aims to pull back the curtain, breaking down a robust, complementary client-server process for managing plugin licenses effectively.

We'll explore how modern payment and license key generation platforms (like Lemon Squeezy or Easy Digital Downloads) integrate with custom license hubs. This intricate dance involves webhooks, secure database management, and API validation, ensuring your WordPress Plugin License Activation system is both secure and scalable.

The Core of WordPress Plugin License Activation: Client-Server Harmony

At its core, a robust WordPress Plugin License Activation system involves two main components working in harmony:

Server-Side (License Management Hub): This is typically a dedicated WordPress installation or a separate web application. It acts as the central authority, listening for purchase events (via webhooks), securely storing license data, and providing an API for client plugins to validate their licenses.
Client-Side (Your Premium WordPress Plugin): This is your plugin, installed on a user's site. It communicates with the License Management Hub to activate, validate, and periodically check its license status.

Let's dive into the technical details of how these two sides interact.

Part 1: The Server-Side Foundation - Webhooks & Database Management

Our journey begins the moment a customer purchases your plugin. Upon a successful payment, the payment platform dispatches a license_key_created webhook to a specified endpoint on your License Management Hub. This webhook carries crucial information about the newly generated license key.

Securely Receiving Webhooks with `LicenseHubWebhookReceiver`

The LicenseHubWebhookReceiver class is designed to set up a REST API endpoint within your WordPress License Management Hub. This endpoint securely catches incoming webhooks and processes them.

<?php
defined( 'ABSPATH' ) || exit;

class LicenseHubWebhookReceiver {
    private $plugin_base_slug;

    public function __construct($plugin_base_slug) {
        $this->plugin_base_slug = $plugin_base_slug;
    }

    public function register_webhook_route() {
        register_rest_route('my-licensing-api/v1', '/payment-webhook', [
            'methods'  => 'POST',
            'callback' => [$this, 'handle_incoming_webhook'],
            'permission_callback' => '__return_true', // Signature verification inside callback
        ]);
    }

    public function handle_incoming_webhook(WP_REST_Request $request) {
        $body      = $request->get_body();
        $signature = $request->get_header('x-signature'); // Example header for webhook signature
        $secret    = get_option($this->plugin_base_slug . '_webhook_secret'); // Stored securely

        // 1. SECURITY: Verify the Webhook Signature
        if (!$this->is_valid_webhook_signature($body, $signature, $secret)) {
            error_log("Invalid Webhook Signature detected.");
            return new WP_REST_Response(['message' => 'Invalid signature'], 401);
        }

        $data = json_decode($body, true);
        if (empty($data)) {
            return new WP_REST_Response(['status' => 'empty_payload'], 400);
        }

        $event = $data['meta']['event_name'] ?? ''; // e.g., 'license_key_created'
        $db    = new LicenseHubDataManager($this->plugin_base_slug);

        if ($event === 'license_key_created') {
            $attributes = $data['data']['attributes']; // Contains license key, email, limits, etc.
            $inserted   = $db->insert_new_license($attributes);

            if ($inserted) {
                error_log("New license key inserted: " . $attributes['key']);
            }
        }

        return new WP_REST_Response(['status' => 'success'], 200);
    }

    /**
     * Verifies the webhook signature against a shared secret.
     */
    private function is_valid_webhook_signature($payload, $signature, $secret) {
        if (empty($signature) || empty($secret)) {
            return false;
        }
        $computed_signature = hash_hmac('sha256', $payload, $secret);
        return hash_equals($computed_signature, $signature);
    }
}

Key takeaway here: The is_valid_webhook_signature method is absolutely critical for security. It ensures that the incoming webhook genuinely originated from your payment platform and hasn't been tampered with, preventing malicious actors from forging license keys or triggering false events.

Storing License Data with `LicenseHubDataManager`

Once the webhook is verified, the handle_incoming_webhook method delegates to insert_new_license from LicenseHubDataManager. This class is responsible for all database interactions, including creating the necessary tables and storing the license details.

Here's a simplified look at how a plugin_licenses table might be structured:

<?php
// ... (part of LicenseHubDataManager::create_license_table method)

        $sql_licenses = "CREATE TABLE $table_licenses (
            id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
            license_key varchar(100) NOT NULL,
            product_item_name varchar(255) NOT NULL,
            license_tier varchar(50) DEFAULT 'standard' NOT NULL,
            allowed_activations int(11) DEFAULT 1 NOT NULL,
            customer_email varchar(105) NOT NULL,
            activated_urls text DEFAULT NULL,
            status varchar(20) DEFAULT 'active' NOT NULL,
            created_at datetime NOT NULL,
            PRIMARY KEY  (id),
            UNIQUE KEY license_key (license_key),
            KEY product_item_name (product_item_name)
        ) $charset_collate;";

        require_once ABSPATH . 'wp-admin/includes/upgrade.php';
        dbDelta($sql_licenses);
// ...

And the insert_new_license method that populates this table:

<?php
// ... (part of LicenseHubDataManager class)

    /**
     * Stores new license data from webhook payload.
     */
    public function insert_new_license($license_data) {
        $license_key = sanitize_text_field($license_data['key']);

        // 1. Prevent Duplicates: Check if license key already exists
        $exists = $this->wpdb->get_var($this->wpdb->prepare(
            "SELECT COUNT(*) FROM {$this->table_licenses} WHERE license_key = %s",
            $license_key
        ));

        if ($exists) {
            // License key already exists, skip insert.
            return false;
        }

        // 2. Insert with dynamic fields from the webhook payload
        return $this->wpdb->insert($this->table_licenses, [
            'license_key'         => $license_key,
            'customer_email'      => sanitize_email($license_data['user_email']),
            'product_item_name'   => sanitize_text_field($license_data['variant_name'] ?? 'My Awesome Plugin'),
            'license_tier'        => sanitize_text_field($license_data['status_formatted'] ?? 'Standard'),
            'allowed_activations' => absint($license_data['activation_limit'] ?? 1),
            'status'              => sanitize_text_field($license_data['status'] ?? 'active'),
            'created_at'          => current_time('mysql')
        ]);
    }
// ...

This process ensures that every license key generated by the payment platform is securely recorded in your database, along with crucial details like the customer's email, the product name, the number of allowed activations, and the current status. This forms the authoritative source for all license information.

Part 2: The Client-Side Implementation - Activating Your WordPress Plugin

Now, let's shift our focus to your actual WordPress plugin. This is the part installed on your user's website, where they enter their license key, and the plugin initiates the validation process with your License Management Hub.

Checking License Status with `PluginLicenseClient`

The PluginLicenseClient class within your plugin is responsible for managing the local license state, communicating with the remote server, and caching validation results to optimize performance and reduce server load.

<?php
defined( 'ABSPATH' ) || exit;

class PluginLicenseClient {
    // ... private properties like $api_secret_token, $api_endpoint, $license_option_key, $status_option_key, $cache_transient_key, $plugin_slug

    private $api_secret_token = 'YOUR_SHARED_SECRET_FOR_CLIENT_SERVER'; // Must match server-side
    private $api_endpoint = 'https://your-license-hub.com/wp-json/my-licensing-api/v1/validate';
    private $license_option_key;
    private $status_option_key;
    private $cache_transient_key;
    private $plugin_slug;
    private $product_identifier = 'my-awesome-plugin-slug'; // Unique ID for your plugin

    public function __construct( $plugin_slug ) {
        $this->plugin_slug = $plugin_slug;
        $this->license_option_key = $this->plugin_slug . '_license_key';
        $this->status_option_key = $this->plugin_slug . '_license_status';
        $this->cache_transient_key = $this->plugin_slug . '_license_cache';
    }

    /**
     * Check if the plugin license is currently active.
     */
    public function is_license_active() {
        $cached_status = get_transient( $this->cache_transient_key );

        // If no cached status, perform remote validation
        if ( false === $cached_status ) {
            $license_key = get_option( $this->license_option_key );
            if ( empty( $license_key ) ) {
                return false; // No license key entered locally
            }
            $cached_status = $this->send_validation_request( $license_key );

            // Cache the result for a day if active, otherwise clear cache
            if ( 'active' === $cached_status ) {
                set_transient( $this->cache_transient_key, $cached_status, DAY_IN_SECONDS );
            } else {
                delete_transient( $this->cache_transient_key );
            }
        }

        return 'active' === $cached_status;
    }

    /**
     * Sends a request to the remote License Management Hub for validation.
     */
    public function send_validation_request( $license_key ) {
        $response = wp_remote_post(
            $this->api_endpoint,
            array(
                'timeout'    => 15,
                'user-agent' => $this->plugin_slug . '/1.0.0 (' . home_url() . ')',
                'headers'    => array(
                    'X-Auth-Token' => sanitize_text_field( $this->api_secret_token ), // Custom auth header
                    'Accept'       => 'application/json',
                ),
                'body'       => array(
                    'license_key'        => sanitize_text_field( $license_key ),
                    'product_identifier' => $this->product_identifier,
                    'site_url'           => home_url(),
                ),
            )
        );

        if ( is_wp_error( $response ) ) {
            error_log("License validation API error: " . $response->get_error_message());
            return 'error';
        }

        $body = json_decode( wp_remote_retrieve_body( $response ), true );

        if ( isset( $body['status'] ) && 'valid' === $body['status'] ) {
            update_option( $this->status_option_key, 'active' );
            return 'active';
        }

        update_option( $this->status_option_key, 'inactive' );
        return 'inactive';
    }

    // ... other methods like display_admin_notice, deactivate_local_license
}

When is_license_active() is called, it first checks a WordPress transient (e.g., myplugin_license_cache). If no cached status is found, it proceeds to send_validation_request(). This method performs an HTTP POST request to your License Management Hub's /my-licensing-api/v1/validate endpoint. It sends the license_key, a product_identifier (a unique identifier for your plugin), and the site_url of the client site.

Important: The X-Auth-Token header contains a shared secret, $api_secret_token, which acts as an authorization key for the API request. This token is crucial for securing your validation endpoint and preventing unauthorized calls.

Part 3: The Server-Side Validation API - The Heart of WordPress Plugin License Activation

Back on the License Management Hub, the LicenseHubAPIHandler class handles the incoming validation requests from client plugins. This is the core of the WordPress Plugin License Activation process, where the legitimacy of a license and its domain usage are confirmed.

Handling Validation Requests with `LicenseHubAPIHandler`

The LicenseHubAPIHandler class registers the /my-licensing-api/v1/validate endpoint and defines how to process requests to it.

<?php
defined( 'ABSPATH' ) || exit;

class LicenseHubAPIHandler {
    private $plugin_base_slug;
    private $data_manager;
    // This secret must match the client-side token for API authentication
    private $api_shared_secret = 'YOUR_SHARED_SECRET_FOR_CLIENT_SERVER'; 

    public function __construct($plugin_base_slug) {
        $this->plugin_base_slug = $plugin_base_slug;
        $this->data_manager = new LicenseHubDataManager($this->plugin_base_slug);
    }

    public function register_api_routes() {
        register_rest_route('my-licensing-api/v1', '/validate', array(
            'methods'             => 'POST',
            'callback'            => array($this, 'handle_validation_request'),
            'permission_callback' => array($this, 'authenticate_api_request'), // Custom permission callback
            'args'                => array(
                'license_key'        => array('required' => true, 'sanitize_callback' => 'sanitize_text_field'),
                'product_identifier' => array('required' => true, 'sanitize_callback' => 'sanitize_text_field'),
                'site_url'           => array('required' => true, 'sanitize_callback' => 'esc_url_raw'),
            )
        ));
    }

    /**
     * Authenticates API requests using a shared token.
     */
    public function authenticate_api_request($request) {
        $auth_token = $request->get_header('X-Auth-Token');
        return hash_equals($auth_token, $this->api_shared_secret);
    }

    /**
     * Handles the incoming license validation request.
     */
    public function handle_validation_request($request) {
        $license_key        = sanitize_text_field($request->get_param('license_key'));
        $product_identifier = sanitize_text_field($request->get_param('product_identifier'));
        $site_url           = esc_url_raw($request->get_param('site_url'));

        if (empty($license_key) || empty($product_identifier) || empty($site_url)) {
            return new WP_Error('missing_params', __('Required fields are missing.', 'my-license-hub'), array('status' => 400));
        }

        $license_data = $this->data_manager->get_license_details($license_key, $product_identifier);

        // Check if license exists and is in an 'active' or 'inactive' (but not expired/revoked) state
        if (!$license_data || !in_array(strtolower($license_data->status), ['active', 'inactive'])) {
            return new WP_REST_Response(array(
                'status'  => 'invalid',
                'message' => __('License is invalid or does not exist.', 'my-license-hub')
            ), 200);
        }

        // Perform domain validation and activation logic
        $is_domain_allowed = $this->data_manager->validate_and_update_domain_activation($license_key, $site_url, $license_data);

        if (!$is_domain_allowed) {
            return new WP_REST_Response(array(
                'status'  => 'invalid',
                'message' => __('Domain activation limit reached for this license.', 'my-license-hub')
            ), 200);
        }

        return rest_ensure_response(array(
            'status'               => 'valid',
            'license_tier'         => sanitize_text_field($license_data->license_tier),
            'allowed_activations'  => (int) $license_data->allowed_activations,
            'active_domain_count'  => $this->data_manager->get_activated_domain_count($license_data),
            'created_at'           => mysql_to_rfc3339($license_data->created_at),
            'validation_checksum'  => wp_hash($license_key . $site_url . $this->api_shared_secret) // Simple checksum for client verification
        ));
    }
}

License and Domain Validation Logic

The handle_validation_request method performs several critical checks:

API Authentication: authenticate_api_request verifies the X-Auth-Token header to ensure the request is authorized.
Parameter Validation: Ensures all required data (license_key, product_identifier, site_url) is present.
License Existence: get_license_details fetches the license from the database.
Domain Activation: The validate_and_update_domain_activation method is the core logic for managing domain limits.

<?php
// ... (part of LicenseHubDataManager class)

    /**
     * Validates a license key against a domain and manages activation limits.
     */
    public function validate_and_update_domain_activation($key, $current_domain_url, $license_data) {
        // Ensure license is found and is in an 'active' or 'inactive' state (not revoked/expired)
        if (!$license_data || !in_array(strtolower($license_data->status), ['active', 'inactive'])) {
            return false;
        }

        $activated_urls = !empty($license_data->activated_urls) ? explode(',', $license_data->activated_urls) : array();
        $activated_urls = array_map('trim', $activated_urls);

        // 1. If the current domain is already activated, it's valid.
        if (in_array($current_domain_url, $activated_urls)) {
            return true;
        }

        // 2. Check if there's room to add this new domain activation
        if (count($activated_urls) < (int) $license_data->allowed_activations) {
            $activated_urls[] = $current_domain_url;
            $new_list = implode(',', array_filter($activated_urls)); // Filter empty entries

            // Update the license record with the new activated domain
            $this->wpdb->update(
                $this->table_licenses,
                array(
                    'activated_urls' => $new_list,
                    'status'         => 'active' // Ensure status is 'active' once a domain is linked
                ),
                array('id' => $license_data->id)
            );
            return true;
        }

        // If domain not found and limit reached
        return false; 
    }

    /**
     * Helper to count currently activated domains for a license.
     */
    public function get_activated_domain_count($license_data) {
        if (empty($license_data->activated_urls)) {
            return 0;
        }
        $domains = explode(',', $license_data->activated_urls);
        return count(array_filter(array_map('trim', $domains)));
    }
// ...

This validate_and_update_domain_activation method is pivotal. It first checks if the domain requesting validation is already activated under this license. If not, it then checks if there's available capacity to activate a new domain based on allowed_activations. If successful, it updates the activated_urls list in the database and ensures the license status is active.

The Complete WordPress Plugin License Activation Flow Summarized

Let's put all the pieces together and summarize the entire WordPress Plugin License Activation process:

Purchase: A customer buys your premium plugin through your chosen payment platform (e.g., Lemon Squeezy).
Webhook Trigger: The payment platform sends a license_key_created webhook to your License Management Hub.
Hub Receives Webhook: LicenseHubWebhookReceiver::handle_incoming_webhook receives the webhook, securely verifies its signature, and parses the license data.
License Stored: LicenseHubDataManager::insert_new_license stores the new license key, allowed activations, customer email, and other details in your hub's database.
Client Plugin Activation: The user installs your plugin, enters their license key in their WordPress dashboard, and clicks "Activate."
Client Initiates Validation: Your plugin's PluginLicenseClient::send_validation_request sends an HTTP POST request to your License Management Hub's API. This request includes the license key, your plugin's unique ID, and the client site's URL.
Hub Validates Request: LicenseHubAPIHandler::handle_validation_request receives the request, authenticates it using the X-Auth-Token header, retrieves the license data from its database, and calls LicenseHubDataManager::validate_and_update_domain_activation.
Domain Check & Activation: validate_and_update_domain_activation checks if the domain is already activated or if it can be added within the allowed_activations limit. If a new domain is activated, the database record is updated.
Hub Responds: The API sends a valid or invalid status back to the client plugin, along with other license details.
Client Updates Status: Your plugin receives the response, updates its local license status (e.g., in wp_options), and caches the result using transients (e.g., for 24 hours) to minimize future API calls.

This robust, complementary flow ensures that your licenses are securely managed, domain limits are enforced, and your plugin's premium functionality is exclusively available to legitimate users.

Key Takeaways for Robust WordPress Plugin License Activation

Security is Paramount: Always verify webhook signatures and API tokens to prevent fraudulent license activations and unauthorized access.
Centralized License Management: A dedicated License Management Hub simplifies tracking, updating, and revoking licenses across all your users.
Database as the Source of Truth: A well-structured license table (including license_key, allowed_activations, activated_urls, and status) is fundamental for WordPress Plugin License Activation.
Client-Server Synergy: The client plugin and server API must work hand-in-hand, with client-side caching to reduce the load on your License Management Hub.
Clear Separation of Concerns: Distinct logic for license creation (via webhooks) and license validation (via API requests) makes the system maintainable.

Implementing a system like this provides a solid and secure foundation for selling and managing your WordPress plugins, giving you control and ensuring your users have a smooth, reliable activation experience.

What are your thoughts?

Have you built similar license management systems for your WordPress plugins? What specific challenges did you encounter, and what innovative solutions did you implement? Share your experiences and insights in the comments below! If you found this in-depth analysis of WordPress Plugin License Activation helpful, consider following me for more technical content on plugin development and best practices.

Beyond Basic Chatbots: Revolutionizing WordPress with an Advanced AI Plugin for 24/7 Sales & Support

Shahibur Rahman — Tue, 31 Mar 2026 16:43:02 +0000

In today's fast-paced digital landscape, businesses running on WordPress and WooCommerce face a constant challenge: how to provide exceptional 24/7 customer support and drive sales without overwhelming their teams or budget. Traditional chatbots often fall short, offering canned responses that frustrate users. But what if your website could host an intelligent, always-on digital employee capable of understanding complex queries, recommending products, and even assisting with purchases? This is where a sophisticated WordPress AI plugin steps in, transforming your site from a static presence into a dynamic, revenue-generating powerhouse.

The era of passive websites is over. Customers expect instant gratification and personalized experiences. Missing a sales opportunity because support isn't available after hours, or losing a lead due to slow response times, is no longer an option. Let's delve into how an advanced AI solution can solve these critical pain points for your WordPress ecosystem.

The New Era of 24/7 Customer Engagement with an AI WordPress Plugin

Imagine your website visitors receiving personalized attention at any hour, in any language. A cutting-edge WordPress AI plugin doesn't just answer questions; it actively engages, understands intent, and guides users through their journey. This constant availability means fewer abandoned carts, higher customer satisfaction, and a significant reduction in the workload for your human support staff.

This isn't about replacing human interaction, but augmenting it. By handling routine inquiries and providing instant information, AI frees your team to focus on more complex issues and build deeper customer relationships. It's like having an expert sales assistant and support agent embedded directly into your site, working tirelessly behind the scenes.

Building an Intelligent Knowledge Base: Smart Content Sync in Action

The true power of an intelligent AI assistant lies in its knowledge. Unlike generic AI tools, a purpose-built WordPress solution can learn directly from your website's unique content. Features like Smart Content Sync automatically scan your pages, products, FAQs, and even uploaded documents (PDFs, TXT, images) to build a comprehensive, private knowledge base.

This means your AI agent is always up-to-date with your latest offerings, policies, and information, ensuring accurate and relevant responses. Regular updates via WP-Cron keep this knowledge base fresh, so your AI always speaks with authority and accuracy, reflecting your brand's current status.

Empowering eCommerce: Advanced WooCommerce AI Commerce Capabilities

For WooCommerce store owners, the benefits extend directly to the bottom line. An AI agent integrated deeply with your store can revolutionize the shopping experience:

Personalized Product Recommendations: Based on conversation context and user behavior, the AI can suggest relevant products, increasing average order value.
Direct Add-to-Cart Actions: Customers can add items to their cart directly from the chat interface, streamlining the purchase process.
Seamless Order Tracking: Provide instant updates on order status, reducing common support queries and improving post-purchase satisfaction.
24/7 Sales Assistance: Guide visitors through product discovery, answer pre-sale questions, and overcome objections, leading to more conversions.

This level of automated commerce assistance transforms casual browsers into confident buyers, making your store more efficient and profitable.

Global Reach and Future-Proof Flexibility with Your WordPress AI Plugin

In a global marketplace, language barriers can be a significant hurdle. An advanced WordPress AI plugin overcomes this by offering support for 40+ languages natively. This means you can serve international customers without the need for additional translation plugins or multilingual staff, expanding your market reach effortlessly.

Furthermore, the best AI solutions offer multi-model AI support, allowing you to choose your preferred AI provider – be it OpenAI, Google Gemini, or xAI (Grok). This flexibility ensures you can leverage the latest advancements in AI, optimize for cost or performance, and future-proof your investment against evolving technology trends.

Continuous Improvement and Actionable Insights

An intelligent AI system isn't static; it learns and improves. Features like AI Feedback & Training Systems allow you to review conversations, correct responses, and continuously refine your AI agent's accuracy and performance. This iterative process ensures your digital employee becomes smarter and more effective over time.

Beyond performance, gaining insights into visitor intent and common queries is invaluable. AI summaries and exportable conversation analytics provide data-driven intelligence, helping you understand your audience better and make informed business decisions to further optimize your site and offerings.

Getting Started: Launching Your AI Sales & Support Agent

Integrating an intelligent AI agent into your WordPress site is designed to be straightforward. Here’s a typical flow for deploying such a powerful WordPress AI plugin:

Install Plugin: Upload and activate the plugin within your WordPress dashboard.
Sync Content & Store: Leverage the Smart Content Sync feature to automatically import your pages, FAQs, and WooCommerce products. This builds the core knowledge base.
Configure AI Engine & Persona: Connect your preferred AI model (OpenAI, Gemini, Grok) with your API keys and define your agent's persona, which can often be auto-generated from your site's content.
Go Live: Your AI assistant immediately begins engaging visitors, answering questions, and assisting with sales.

This streamlined process enables you to quickly transform your website into a 24/7 sales and support powerhouse.

Key Takeaways for Your Business

The integration of a powerful AI sales and support engine represents a paradigm shift for WordPress and WooCommerce users. It's about moving beyond reactive customer service to proactive engagement, turning every website visit into an opportunity for connection and conversion.

24/7 Engagement: Provide instant, personalized support and sales assistance around the clock.
Intelligent Knowledge: AI learns directly from your site's content, ensuring accurate responses.
Boost WooCommerce Sales: Personalized recommendations, direct add-to-cart, and order tracking.
Global Reach: Support for 40+ languages expands your market effortlessly.
Future-Proof: Multi-model AI support allows flexibility and adaptability.
Continuous Learning: AI improves over time with feedback and training.

Transform Your WordPress Site Today

If you're ready to automate your customer engagement, drive revenue 24/7, and elevate your online presence, the time to explore this technology is now. We believe deeply in the transformative power of this approach and encourage you to see the benefits firsthand.

⚡️ Action: Discover how this innovative approach can benefit your WordPress site. Check out our 30% OFF PH-exclusive deal here:

producthunt.com

For more details, visit our website:

IntelliAgent AI - Turn Your WordPress Site Into a 24/7 Sales & Support PowerhouseIntelliAgent AI - AI Sales & Support Agent for WordPress & WooCommerce

Turn Your WordPress Site Into a 24/7 Sales & Support Powerhouse Transform your website into an intelligent assistant that answers questions, recommends products, manages FAQs, supports 40+ languages, and helps customers buy — automatically. Formerly AICA IntelliAgent Get IntelliAgent AI Now — One-Time Payment AI Support • AI Sales Assistant • Automated Knowledge Base •

aica-intelliagent.com

If this analysis resonated with you, please consider clapping and following for more insights into leveraging AI for your business!

Deep Dive: Ensuring WordPress Plugin Quality with Plugin Check (PCP)

Shahibur Rahman — Tue, 10 Mar 2026 20:28:28 +0000

Developing robust WordPress plugins demands adherence to high standards. A powerful tool like Plugin Check (PCP) is instrumental in validating that your creations meet stringent WordPress plugin quality, security, and WordPress.org guidelines. This article provides an in-depth analysis of PCP, an open-source solution designed for comprehensive plugin analysis, streamlining compliance and enhancing overall readiness for high-quality WordPress plugin development.

Why Comprehensive WordPress Plugin Quality Checks Matter

Beyond mere functionality, high-quality WordPress plugins integrate best practices in areas such as internationalization, accessibility, performance, and security. Neglecting these aspects can lead to issues ranging from rejection by the WordPress.org directory to compromised user experience and significant security vulnerabilities. PCP serves as an analytical co-pilot, identifying potential problems early in the development cycle and guiding developers towards more compliant and robust solutions.

Utilizing Plugin Check (PCP) for WordPress Plugin Quality Assurance

PCP offers flexible integration methods, catering to different development workflows, from graphical interfaces to command-line automation.

WP Admin User Interface

For developers who prefer a graphical interface, PCP integrates directly into the WordPress admin area. After installation, navigate to Tools > Plugin Check. This interface allows for intuitive analysis, presenting flagged issues in a categorized manner, which helps in systematically addressing concerns. Access to this screen requires appropriate user capabilities to manage plugins.

WP-CLI for Automated WordPress Plugin Checks

For developers favoring command-line workflows and automated testing, WP-CLI integration provides a powerful mechanism. This method supports scriptable analysis, making it ideal for inclusion in continuous integration/continuous deployment (CI/CD) pipelines.

To perform static checks on a plugin, use the wp plugin check command followed by the main plugin file path:

wp plugin check your-plugin/your-plugin.php

For runtime checks, which involve executing parts of your plugin's code within a WordPress environment, a specific --require argument is necessary. This workaround ensures that PCP's CLI helper file is loaded before WordPress fully initializes:

wp plugin check your-plugin/your-plugin.php --require=./wp-content/plugins/plugin-check/cli.php

PCP also supports checking plugins from arbitrary paths or remote URLs, offering flexibility for various testing scenarios:

# Check a plugin from a local path
wp plugin check /path/to/your-plugin/plugin.php

# Check a plugin from a remote ZIP URL
wp plugin check https://example.com/plugin.zip

Understanding PCP's Issue Categories and Resolution for WordPress Plugin Quality

PCP categorizes identified issues, providing structured feedback across critical development facets. This section explores common issue types and approaches to their resolution, crucial for achieving high WordPress plugin quality.

Internationalization Issues

PCP flags instances where text strings are not properly prepared for translation, ensuring your plugin can be localized for a global audience.

Example Issue: A hardcoded string like echo "Hello World!"; without a translation function.
PCP Flag: "String not translatable."
Resolution: Wrap all user-facing strings in __() or _e() functions, e.g.,

_e( 'Hello World!', 'your-text-domain' );

Security Concerns

The tool identifies potential security vulnerabilities, such as improper data sanitization, missing nonces, or inadequate capabilities checks, which are vital for a secure WordPress Plugin Check.

Example Issue: Directly using $_POST['data'] without sanitization or validation.
PCP Flag: "Unsanitized input from $_POST detected."
Resolution: Always sanitize and validate user input. For example,

sanitize_text_field( $_POST['data'] );

and implement nonces for form submissions, e.g., wp_verify_nonce() with check_admin_referer().

Performance Optimizations

PCP can highlight code patterns that might impact plugin performance, such as inefficient database queries or excessive resource loading.

Example Issue: Making a database query inside a loop without caching, e.g.,

foreach ($items as $item) { 
    $wpdb->get_row("SELECT * FROM ..."); 
}

PCP Flag: "Potential performance bottleneck: repeated database query."
Resolution: Optimize queries, use WordPress API functions like get_posts() with appropriate arguments, implement object caching, or perform bulk operations where possible.

Accessibility Best Practices

The tool assists in ensuring your plugin's interface and output are accessible to users with disabilities by checking for proper HTML semantics and attributes.

Example Issue: An <img> tag without an alt attribute, e.g., <img src="image.png">.
PCP Flag: "Image missing alt attribute."
Resolution: Provide descriptive alt text for all images, e.g.,

<img src="image.png" alt="Description of the image for screen readers">

The Plugin Namer Tool

Beyond code quality, PCP includes a Plugin Namer tool, accessible via Tools > Plugin Check Namer. This AI-powered feature helps developers evaluate potential plugin names against existing plugins, trademarks, and WordPress naming guidelines. It provides instant feedback and suggestions for choosing a unique and compliant name, though it's important to remember that final approval always rests with the WordPress.org Plugins team.

Key Takeaways for Enhancing WordPress Plugin Quality

Plugin Check (PCP) is an open-source tool for validating WordPress plugin compliance and best practices.
It supports both WP Admin UI and WP-CLI for flexible integration into various development workflows.
PCP identifies issues across critical categories like internationalization, security, performance, and accessibility.
WP-CLI allows for automated static and runtime checks, which are crucial for CI/CD pipelines.
The Plugin Namer tool aids in selecting unique and compliant plugin names, complementing technical code checks.
Regular use of PCP can significantly improve overall WordPress plugin quality and readiness for the WordPress.org repository.

Integrating automated quality checks like PCP into your WordPress plugin development process can save significant time and effort, leading to more robust and compliant solutions. What are your experiences with automated plugin quality tools? Share your insights and best practices in the comments below! Follow me for more in-depth analyses on WordPress development.

Mastering WordPress Internationalization (i18n): A Beginner's Guide to Global Plugins

Shahibur Rahman — Fri, 27 Feb 2026 17:28:51 +0000

Developing a successful WordPress plugin means reaching a global audience. The key to unlocking this reach is WordPress Internationalization (i18n). By making your plugin translatable, you allow it to adapt to different languages and locales, directly connecting with users worldwide and even tapping into WordPress.org's automatic translation system supporting numerous languages.

This guide will walk you through the essential steps and best practices for properly internationalizing your WordPress plugin, ensuring it's ready for a global audience and compliant with WordPress.org standards.

Why WordPress Internationalization is Crucial for Your Plugin

Imagine a user in a non-English speaking country trying to use your plugin, but all the labels, buttons, and messages are in English. They'll likely abandon it. Internationalization isn't just a nice-to-have; it's a fundamental aspect of user experience and market reach. Here's why WordPress i18n is so important:

Broader Audience: Your plugin becomes accessible to non-English speakers, significantly expanding your potential user base.
WordPress.org Compatibility: Proper i18n is a strict requirement for plugins hosted on WordPress.org, enabling automatic language pack downloads.
Community Contributions: It empowers volunteers to translate your plugin into their native languages through platforms like GlotPress.
Professionalism: A translatable plugin reflects a higher standard of development and attention to user needs.

Let's dive into the core steps to achieve proper WordPress i18n.

1. The Plugin Header: Your i18n Blueprint

Every WordPress plugin starts with a header. For WordPress Internationalization, two fields are critical: Text Domain and Domain Path.

Text Domain: This is a unique identifier for all translatable strings in your plugin. It must match your plugin's slug (the folder name of your plugin).

Domain Path: This tells WordPress where to find your translation files. It's almost always /languages.

<?php
/**
 * Plugin Name: My Awesome Plugin
 * Plugin URI:  https://myawesomeplugin.com/
 * Description: A simple plugin to demonstrate WordPress i18n.
 * Version:     1.0.0
 * Author:      Your Name
 * Author URI:  https://yourwebsite.com/
 * License:     GPL-2.0+
 * License URI: http://www.gnu.org/licenses/gpl-2.0.txt
 * Text Domain: my-awesome-plugin
 * Domain Path: /languages
 */

// ... rest of your plugin code

Key Takeaway: Your Text Domain (e.g., my-awesome-plugin) must be consistent across your entire plugin, both in the header and in every translation function call.

2. Standard Language Folder Structure

WordPress expects your translation files to reside in a specific location within your plugin's directory. Create a folder named languages at the root of your plugin.

Your plugin structure should look like this:

my-awesome-plugin/
│
├── my-awesome-plugin.php
├── languages/
│   ├── my-awesome-plugin.pot
│   ├── my-awesome-plugin-en_US.mo (Optional: Default language)
│   └── ... (Other bundled .mo files, if any)
└── ... (other plugin files and folders)

Naming Rule: Translation files follow the pattern {text-domain}-{locale}.mo (e.g., my-awesome-plugin-fr_FR.mo).

Important: You only need to ship the .pot file and optionally your default language's .mo file. WordPress.org handles downloading other language packs automatically into wp-content/languages/plugins/.

3. Loading Translations the WordPress Standard Way

The timing of loading your plugin's text domain is crucial. It should happen early enough in the WordPress lifecycle for all strings to be available, but not too early. The init hook is the recommended place.

First, in your main plugin file (e.g., my-awesome-plugin.php), define a constant for the main plugin file path. This is crucial for plugin_basename() to work reliably:

// my-awesome-plugin.php

if (!defined('MY_AWESOME_PLUGIN_FILE')) {
    define('MY_AWESOME_PLUGIN_FILE', __FILE__);
}

// ... rest of your plugin code, including your Bootstrap and Main classes

Next, in your main plugin class (e.g., MyAwesomePlugin_Main), add a load_textdomain method and register it to the init hook via your loader class. This ensures proper WordPress i18n initialization.

// includes/class-main.php (or wherever your main plugin class is)

class MyAwesomePlugin_Main {
    protected $loader;
    protected $plugin_slug;
    // ... other properties ...

    public function __construct( $plugin_slug ) {
        $this->plugin_slug = $plugin_slug;
        $this->loader = new MyAwesomePlugin_Loader(); // Assuming you have a loader class
        $this->define_hooks();
    }

    private function define_hooks() {
        // WP Standard: Load textdomain on init hook via loader
        $this->loader->add_action( 'init', $this, 'load_textdomain' );

        // ... rest of your hooks (admin pages, public scripts, etc.) ...
    }

    /**
     * WP Standard: Load the plugin text domain for internationalization.
     * This method first checks for global language packs and then falls back
     * to the plugin's bundled language files. This is key for global language support.
     */
    public function load_textdomain() {
        $locale = determine_locale();

        // 1. Load translations from wp-content/languages/plugins/ (for WP.org language packs)
        load_textdomain(
            $this->plugin_slug,
            WP_LANG_DIR . '/plugins/' . $this->plugin_slug . '-' . $locale . '.mo'
        );

        // 2. Fallback to plugin's bundled /languages/ directory
        load_plugin_textdomain(
            $this->plugin_slug,
            false,
            dirname( plugin_basename( MY_AWESOME_PLUGIN_FILE ) ) . '/languages/'
        );
    }

    public function run() {
        $this->loader->run();
    }
}

Why this is the best practice: This two-step loading process ensures WordPress prioritizes official language packs downloaded from WordPress.org, then falls back to any .mo files you bundle with your plugin. Hooking it to init means translations are loaded at the correct time in the WordPress lifecycle, after all plugins are loaded but before strings are used in the UI.

4. Translating Strings in Your Code

To make any text in your plugin translatable, you must wrap it in a WordPress i18n function and provide your plugin's text domain (e.g., 'my-awesome-plugin').

Here are the most common functions:

__(): Returns a translated string.
_e(): Echos a translated string directly.
esc_html__(): Returns a translated string, escaped for HTML output.
esc_html_e(): Echos a translated string, escaped for HTML output.
esc_attr__(): Returns a translated string, escaped for HTML attribute output.
printf(): For strings with dynamic content (placeholders like %s, %d).

<?php
// Example in an Admin menu
add_submenu_page(
    $this->plugin_slug,
    __( 'Dashboard', 'my-awesome-plugin' ), // Translatable string for the title
    __( 'Dashboard', 'my-awesome-plugin' ), // Translatable string for the menu item
    'manage_options',
    $this->plugin_slug,
    array($this, 'display_admin_dashboard')
);

// Example for plain text output
echo '<p>' . esc_html__( 'Welcome to My Awesome Plugin.', 'my-awesome-plugin' ) . '</p>';

// Example with placeholders and translator comments (CRITICAL for WP-CLI warnings)
if ( !empty($last_sync) ) {
    /* translators: %s = human readable time (e.g. 5 minutes) */
    echo esc_html( sprintf(
        __( 'Last backup completed %s ago', 'my-awesome-plugin' ),
        human_time_diff( $last_sync, wp_date('U') )
    ) );
} else {
    esc_html_e( 'No background sync recorded yet', 'my-awesome-plugin' );
}

Translator Comments (/* translators: ... */): Always add these comments directly above strings that contain placeholders (%s, %d, %1$s, etc.). They provide context to translators, helping them understand what the placeholders represent and ensuring accurate translation, even if the word order changes in another language. This is vital for quality WordPress plugin translation.

5. Generating the `.pot` File

The .pot (Portable Object Template) file is a plain text file that contains all the translatable strings from your plugin. Translators use this file as a template to create language-specific .po (Portable Object) files, which are then compiled into machine-readable .mo (Machine Object) files that WordPress uses.

You don't write this file manually; you generate it using tools.

Option A: Using WP-CLI (Recommended for Developers)

If you have WP-CLI installed, navigate to your plugin's root directory in your terminal and run:

wp i18n make-pot . languages/my-awesome-plugin.pot

This command scans all PHP files in your current directory (.) and extracts all strings wrapped in i18n functions, saving them to languages/my-awesome-plugin.pot.

Option B: Using Poedit (GUI Tool)

Download and install Poedit.
Open Poedit, go to File > New from POT/PO Template.
Select your plugin's root directory.
Set the Text domain to my-awesome-plugin.
Poedit will scan your files and list all translatable strings. Save the generated file as languages/my-awesome-plugin.pot.

After successfully generating your .pot file, you should see a Success: POT file successfully generated. message in your terminal (if using WP-CLI) and the file will be in your languages folder.

Key Takeaways for WordPress Internationalization

Consistent Text Domain: Ensure your Text Domain in the plugin header matches exactly the text domain used in all __(), _e(), esc_html__(), etc., functions throughout your code.
Domain Path: /languages: Always set this in your plugin header.
Load on init Hook: Use load_plugin_textdomain() or load_textdomain() within a method hooked to init for proper loading timing.
Prioritize Global Language Packs: Implement the two-step load_textdomain approach (loading from WP_LANG_DIR first) to support WordPress.org's automatic language downloads and WordPress language support for a global audience.
Wrap All User-Facing Strings: Every piece of text visible to the user must be wrapped in an i18n function.
Escape Output: Use esc_html__(), esc_html_e(), esc_attr__() where appropriate to prevent security vulnerabilities.
Translator Comments for Placeholders: Add /* translators: ... */ comments above strings with %s, %d, etc., to provide context for translators.
Ship Only .pot: For WordPress.org plugins, only include languages/your-plugin.pot in your submission. WordPress handles the rest!

By following these steps, your WordPress plugin will be fully equipped to serve users in numerous languages, significantly boosting its reach and user satisfaction. Happy translating!

What are your thoughts or questions on WordPress i18n? Share your experiences in the comments below!

Mastering WordPress Plugin Best Practices: Security, i18n, and Performance for Beginners

Shahibur Rahman — Tue, 20 Jan 2026 20:02:07 +0000

Developing a WordPress plugin can be a rewarding experience, and adhering to stringent WordPress Plugin Best Practices from the outset is crucial for creating robust, secure, and widely usable software. This isn't just about functionality; it's about security, internationalization, performance, and overall code quality.

For beginners looking to build high-quality plugins, understanding these core principles is essential. In this in-depth analysis, we'll break down the critical refinements needed to elevate your plugin from functional to truly professional, drawing directly from common development standards and crucial feedback points.

Why Robust WordPress Plugin Best Practices Matter

Before diving into the 'how,' let's understand the 'why.' A plugin that meets high standards isn't just easier to maintain; it's more reliable, secure, and user-friendly. Adhering to these WordPress Plugin Best Practices is crucial for protecting your users and ensuring your plugin is a valuable, sustainable asset for the entire WordPress ecosystem.

Internationalization (i18n): Speaking Every Language

One of WordPress's greatest strengths is its global reach. Your plugin should be accessible to users worldwide, which means all text strings must be translatable. This is a fundamental WordPress Plugin Best Practice for broad adoption.

Implementing Basic Translation

Wrap all user-facing strings in __() for echoing or _e() for direct output. Remember to specify your unique text domain, often matching your plugin's slug (e.g., 'aica-plugin').

// For strings that need to be returned
$text = __( 'Hello World', 'aica-plugin' );

// For strings that need to be echoed directly
_e( 'Welcome to my plugin!', 'aica-plugin' );

Advanced Translation with Placeholders and HTML

When you need to include dynamic data or HTML tags within a translatable string, printf() is your best friend. It allows translators to reorder phrases if necessary, without breaking your HTML.

<?php
/* translators: 1: format list, 2: strong tag start, 3: strong tag end */
printf(
    esc_html__( 'JPG, PNG, or SVG, up to 1MB. Ideal size: %2$s535 x 535 pixels%3$s.', 'aica-plugin' ),
    'JPG, PNG, SVG',
    '<strong>',
    '</strong>'
);
?>

Pluralization for Dynamic Messages

For messages that change based on quantity (e.g., "1 minute ago" vs. "5 minutes ago"), use _n() to handle pluralization correctly.

<?php
$count = 5;
printf(
    _n( '%s minute ago', '%s minutes ago', $count, 'aica-plugin' ),
    number_format_i18n( $count )
);
?>

Localizing JavaScript Strings

JavaScript strings also need to be translatable. wp_localize_script() is the standard way to pass translated strings (and other dynamic data) from PHP to your JavaScript files.

// In your PHP file (e.g., during script enqueue)
wp_localize(
    $this->plugin_slug . '-admin',
    'aica_admin_data',
    array(
        'ajax_url'            => admin_url('admin-ajax.php'),
        'nonce'               => wp_create_nonce('aica_admin_nonce'),
        'i18n_visitor'        => __( 'Visitor', 'aica-plugin' ),
        'i18n_ai'             => __( 'AI Agent', 'aica-plugin' ),
        'i18n_deleting'       => __( 'Deleting...', 'aica-plugin' ),
        'i18n_saving'         => __( 'Saving...', 'aica-plugin' ),
        'i18n_summary_title'  => __( 'AI Intelligence Summary', 'aica-plugin' ),
        'i18n_confirm_delete' => __( 'Delete this conversation forever?', 'aica-plugin' ),
    )
);

// In your JavaScript file (e.g., admin.js)
console.log(aica_admin_data.i18n_deleting);

Security & Escaping: Protecting Against Malice

Security is paramount in WordPress development. Every piece of data displayed to the user or processed from user input must be properly escaped and sanitized. This is a non-negotiable WordPress Plugin Best Practice.

Escaping Output: Don't Trust Anything!

Always escape data before outputting it to the browser. This prevents Cross-Site Scripting (XSS) vulnerabilities.

esc_html(): For general HTML content.
esc_attr(): For HTML attribute values.
esc_url(): For URLs.
checked(): Helps securely mark radio buttons/checkboxes.

When generating links or other HTML elements with dynamic PHP content, use functions like add_query_arg for URL building and esc_url for final output. Similarly, for HTML attributes like input values or checked states, esc_attr and checked are essential.

<?php
// Example: Building a secure URL with add_query_arg() and escaping it
$page_url = admin_url( 'admin.php?page=my-plugin' );
$active_tab = 'content'; // Example value

$link_href = esc_url( add_query_arg( 'tab', 'content', $page_url ) );
$tab_class = $active_tab === 'content' ? 'nav-tab-active' : '';

// Translatable link text:
_e( 'Content', 'aica-plugin' );

// Example: Safely outputting an HTML attribute and checked state
$value = 'dark'; // Example value
$current_theme = 'dark'; // Example value

// The value attribute:
echo esc_attr($value); 

// The 'checked' attribute conditionally:
checked($current_theme, $value);
?>

Sanitizing Input: Clean Data is Safe Data

Before saving or using user-provided data, sanitize it to ensure it conforms to expected formats and doesn't contain malicious code.

sanitize_key(): For sanitizing keys/slugs.
intval(): For ensuring integers.
wp_strip_all_tags(): For stripping HTML from strings (e.g., email subjects).
wp_kses_post(): For sanitizing HTML content, allowing only safe tags (useful for rich text in emails).

<?php
// Example: Sanitizing a session ID
$session_id = sanitize_key( $_POST['session_id'] );

// Example: Sanitizing an integer ID
$item_id = intval( $_GET['item_id'] );

// Example: Sanitizing feedback before passing to an LLM
$user_query = esc_html( $_POST['user_query'] ); // Use esc_html for display, or more robust sanitization for LLM input

// Example: Sanitizing email subject and HTML content
$subject = wp_strip_all_tags( $_POST['email_subject'] );
$summary_html = wp_kses_post( $_POST['email_body'] );
?>

Preventing XSS in JavaScript

When dynamically inserting content into the DOM using JavaScript, be extremely careful. Direct use of .html() or template literals without proper escaping can introduce XSS vulnerabilities. Always prefer .text() for plain text or ensure content is sanitized on the server-side if it's expected to contain safe HTML.

// ❌ DANGEROUS: Potential XSS vulnerability
// $('.chat-content').html(msg.content);
// const username = response.data;
// $('#user-display').text(`Welcome, ${username}!`);

// ✅ SAFER: Use .text() for plain text or sanitize before using .html()
// For displaying plain text
$('.user-message').text(msg.user_input);

// If msg.content is *expected* to contain safe HTML, it must be sanitized on the server-side
// before being passed to the client. If it's pure text, use .text()

// For dynamic user names, always use .text() or equivalent for plain text insertion
const username = aica_admin_data.i18n_visitor; // Use localized string
$('#user-display').text(username);

Nonce Verification for AJAX Calls

Always verify nonces for AJAX requests to prevent CSRF (Cross-Site Request Forgery) attacks.

<?php
// In your AJAX handler
if ( ! isset( $_POST['nonce'] ) || ! wp_verify_nonce( $_POST['nonce'], 'aica_admin_nonce' ) ) {
    wp_send_json_error( array( 'message' => __( 'Security check failed.', 'aica-plugin' ) ) );
}
// Proceed with AJAX logic
?>

Database Interaction & SQL Security

Interacting with the database is common, but it's also a prime target for SQL Injection. Adhering to wpdb best practices is a must.

Prepared Queries with `$wpdb->prepare()`

This is the golden rule for database security. Never concatenate user input directly into SQL queries. Always use $wpdb->prepare().

<?php
global $wpdb;
$table_name = $wpdb->prefix . 'my_custom_table';
$data_id = intval( $_GET['data_id'] );

// ✅ Secure way to fetch data
$result = $wpdb->get_row(
    $wpdb->prepare(
        "SELECT * FROM %i WHERE id = %d",
        $table_name,
        $data_id
    )
);

// ✅ Secure way to insert data
$wpdb->insert(
    $table_name,
    array(
        'column1' => sanitize_text_field( $_POST['input1'] ),
        'column2' => intval( $_POST['input2'] )
    ),
    array( '%s', '%d' ) // Format specifiers
);
?>

Indexing for Performance

Proper indexing improves database query speeds. When creating tables, ensure that VARCHAR(255) columns used for indexing are limited to 191 characters to ensure compatibility with older MySQL/MariaDB versions using UTF8mb4.

CREATE TABLE `wp_my_custom_table` (
    `id` BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    `session_key` VARCHAR(191) NOT NULL,
    `created_at` DATETIME NOT NULL,
    PRIMARY KEY (`id`),
    KEY `session_key_idx` (`session_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_520_ci;

Existence Checks for Robustness

Add IF NOT EXISTS logic to your CREATE TABLE statements to prevent errors if the table already exists, making your plugin more robust during updates or re-installations.

<?php
global $wpdb;
$table_name = $wpdb->prefix . 'my_custom_table';
$charset_collate = $wpdb->get_charset_collate();

$sql = "CREATE TABLE IF NOT EXISTS `{$table_name}` (
    id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    session_key VARCHAR(191) NOT NULL,
    created_at DATETIME NOT NULL,
    PRIMARY KEY  (id),
    KEY session_key_idx (session_key)
) {$charset_collate};";

require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );
dbDelta( $sql );
?>

Accessibility & User Experience

Good plugins consider all users. Accessibility features and a smooth user experience are critical WordPress Plugin Best Practices.

Image Alt Tags

Always provide meaningful alt attributes for images, especially in the admin area, to assist users with screen readers.

<?php
// Example: Safely outputting an image's URL and translatable alt text
$avatar_url = 'path/to/avatar.png';

// For the 'src' attribute:
echo esc_url( $avatar_url ); 

// For the 'alt' attribute, which is also translatable:
esc_attr_e( 'AI Agent Avatar', 'aica-plugin' ); 
?>

Localized Dates

Use date_i18n() instead of date() to display dates and times according to the user's WordPress locale settings.

<?php
// Display current date in localized format
echo date_i18n( get_option( 'date_format' ) );

// Display a specific timestamp in localized format
$timestamp = strtotime( '-5 minutes' );
echo date_i18n( 'F j, Y, g:i a', $timestamp );
?>

Robustness & Error Prevention

Preventing fatal errors and ensuring your plugin degrades gracefully is a sign of a well-engineered product.

`class_exists` for Sub-Models

If your plugin relies on dynamically loaded or optional classes, use class_exists() before instantiating them. This prevents fatal errors if a file is missing or a dependency isn't met.

<?php
if ( class_exists( 'My_Grok_Model' ) ) {
    $grok_instance = new My_Grok_Model();
} else {
    // Fallback or log error
    error_log( 'My_Grok_Model class not found.' );
}
?>

Header Security

When sending emails, ensure your headers are secure to prevent injection attacks.

<?php
function aica_filter_from_header( $from_email ) {
    $site_name = get_option( 'blogname' );
    // Strip angle brackets and double quotes from site name to prevent header injection
    $safe_site_name = str_replace( array( '<', '>', '"' ), '', $site_name );
    return $safe_site_name . ' <' . $from_email . '>';
}
add_filter( 'wp_mail_from_name', 'aica_filter_from_header' );
?>

Key Takeaways for Mastering WordPress Plugin Best Practices

Internationalization is mandatory: Translate all strings using __, _e, _n, printf, and wp_localize_script.
Security first: Escape all output (esc_html, esc_attr, esc_url) and sanitize all input (sanitize_key, intval, wp_strip_all_tags, wp_kses_post). Use add_query_arg for URL building and wp_verify_nonce for AJAX.
SQL Safety: Always use $wpdb->prepare() for database queries to prevent SQL injection.
Performance: Implement proper indexing (VARCHAR(191)) and use IF NOT EXISTS for robust table creation.
Accessibility: Provide alt tags for images and use date_i18n() for localized dates.
Error Prevention: Use class_exists checks and secure email headers.

By meticulously applying these WordPress Plugin Best Practices, you'll create a superior plugin that is robust, secure, and user-friendly. These principles are the bedrock of professional WordPress development.

What are your go-to best practices for WordPress plugin development? Share your insights and experiences in the comments below!

Mastering LLM Integrations in WordPress: A Plugin Boilerplate Deep Dive

Shahibur Rahman — Sun, 18 Jan 2026 09:18:00 +0000

LLM integrations are rapidly transforming how developers build intelligent applications. Integrating Large Language Models (LLMs) like OpenAI, Gemini, and Grok into a WordPress plugin can unlock powerful AI capabilities directly within your website. This article will guide you through a robust WordPress plugin boilerplate, detailing the architecture and core classes responsible for these advanced LLM integrations in WordPress.

We'll explore a well-structured plugin designed for extensibility and maintainability, leveraging a popular WordPress plugin development structure to provide a solid foundation. You'll understand how to connect to different LLM APIs, handle multimodal inputs (text, images, documents), and manage conversation context effectively.

Here's the GitHub repository for the complete code:

d5b94396feba3 / llms-apis-wp-boilerplate-plugin

A collection of LLM (Large Language Model) API integration classes for WordPress plugins. Provides unified integration with multiple LLM providers including OpenAI, Google Gemini, and xAI Grok.

LLM APIs WordPress Plugin Component

A collection of LLM (Large Language Model) API integration classes for WordPress plugins. Provides unified integration with multiple LLM providers including OpenAI, Google Gemini, and xAI Grok. Designed to be integrated into WordPress plugins that follow the WP Plugin Boilerplate structure.

📦 What This Is

This repository contains only the LLM API integration classes - it is not a complete WordPress plugin. These classes are designed to be integrated into a parent WordPress plugin that uses the WP Plugin Boilerplate structure.

🚀 Features

Multi-LLM Support: Integrate with OpenAI, Google Gemini, and xAI Grok APIs
File Attachment Support: Upload and process PDFs, images, and text files as knowledge bases
Conversation History: Maintain context across multiple interactions
Multimodal Support: Handle both text and image inputs
WordPress Standards: Built following WordPress coding standards and best practices
Object-Oriented Architecture: Clean, maintainable code…

View on GitHub

The Plugin Boilerplate Foundation for LLM Integrations

Our example plugin, my-wp-plugin, is built upon a standardized WordPress development approach, promoting a scalable and maintainable structure. This separation of concerns makes the plugin easier to develop, debug, and maintain, especially when dealing with complex LLM integrations.

Here's a quick look at the typical directory structure:

my-wp-plugin/
├── 📄 my-wp-plugin.php                 # Main plugin file
├── 📁 includes/                        # Core PHP classes
│   ├── 📄 class-main.php               # Plugin orchestrator
│   ├── 📄 class-loader.php             # Hook manager
│   ├── 📄 class-activator.php          # Activation handler
│   └── 📄 class-deactivator.php        # Deactivation handler
├── 📁 admin/                           # Backend functionality ONLY
│   ├── 📄 class-admin.php              # Admin controller
│   └── 📁 partials/                    # Admin HTML templates
├── 📁 public/                          # Frontend functionality ONLY
│   └── 📄 class-public.php             # Frontend controller
├── 📁 assets/                          # ALL static files (CSS, JS, Images)
├── 📁 languages/                       # Translation files
└── 📄 uninstall.php                    # Cleanup when deleted

For our LLM integrations specifically, the key classes we'll focus on reside within the includes/ directory.

The Central Brain: `AICA_Plugin_LLM_Processor`

The AICA_Plugin_LLM_Processor class acts as the central hub for all LLM interactions within the plugin. It's responsible for orchestrating the entire process: selecting the active LLM, constructing the full system instruction, and dispatching requests to the appropriate LLM-specific integration class.

Constructor (`__construct`)

This method is crucial for dynamically loading the correct LLM integration. Based on the user's settings (e.g., in the WordPress admin), it instantiates either the Grok, OpenAI, or Gemini class.

class AICA_Plugin_LLM_Processor {
    private $plugin_slug;
    private $system_instruction;
    private $llm_model;

    public function __construct($plugin_slug) {
        $this->plugin_slug = $plugin_slug;
        $this->system_instruction = get_option('ai_agent_system_prompt', 'You are an AI Assistant...');

        $active_llm_model = get_option('llm_model', 'Grok');

        if ($active_llm_model == "Grok") {
            $this->llm_model = new AICA_Plugin_LLM_Grok($this->plugin_slug);
        } elseif ($active_llm_model == "OpenAI") {
            $this->llm_model = new AICA_Plugin_LLM_OpenAI($this->plugin_slug);
        } elseif ($active_llm_model == "Gemini") {
            $this->llm_model = new AICA_Plugin_LLM_Gemini($this->plugin_slug);
        }
    }
    // ... rest of the class
}

Getting an LLM Response (`get_llm_response`)

This is the primary method for handling user queries and generating LLM responses. It meticulously constructs the system_instruction by combining a core prompt, user-defined prompt, positive/negative feedback examples from the database, and content from the plugin's knowledge base. It then delegates the actual API call to the llm_api_v2 method of the active LLM model, which supports multimodal inputs.

Chat Summarization (`get_chat_summary`)

This utility method uses the llm_api_v3 (text-only) of the chosen LLM to summarize a conversation history. It prepares a structured prompt with the chat transcript and requests a concise summary.

Automated System Prompt Generation (`generate_automated_system_prompt`)

Leveraging the LLM's own capabilities, this method can automatically generate a sophisticated system prompt based on the website's knowledge base content. It uses a template, replaces a placeholder with extracted content, and then calls llm_api_v3 to generate the prompt.

Deep Dive into Individual LLM Integrations

Each LLM (Gemini, Grok, OpenAI) has its own dedicated class, abstracting the specifics of its API. This modular approach makes it easier to add new LLMs or update existing ones. They share common patterns:

llm_api_v2: Handles multimodal inputs (text, images, documents) and conversation history.
llm_api_v3: Designed for simpler, text-only interactions, often used for tasks like summarization or prompt generation.
prepare_attachments: A private helper to process local files (extract text from PDFs/TXTs, encode images to Base64, or upload large files to the LLM's service).
request_llm_service_name: The core method that makes the actual API call to the respective LLM, including robust error handling.

Let's break down each integration to see how they manage diverse inputs and API requirements for LLM integrations in WordPress.

1. Gemini Integration (`AICA_Plugin_LLM_Gemini`)

This class handles communication with Google's Gemini API, supporting both text and multimodal inputs. It smartly manages file uploads for large documents.

`llm_api_v2` and `prepare_attachments`

Gemini's llm_api_v2 is designed to handle attachments efficiently. For images, it encodes them as Base64 inline_data. For PDFs and plain text files, it checks their size. Small files are directly embedded as file_context_text. Larger files (over 1MB) are uploaded to Gemini's file service via upload_to_gemini to get a file_uri, which is then referenced in the API request. This optimizes API calls and handles large data payloads.

// Excerpt from AICA_Plugin_LLM_Gemini::prepare_attachments
private function prepare_attachments(): array {
    $file_id = get_option('ai_agent_knowledge_file_id');
    $data = ['multimodal_parts'  => [], 'file_context_text' => ""];

    if (!$file_id) return $data;

    $file_path = get_attached_file($file_id);
    $mime_type = get_post_mime_type($file_id);
    $file_size = filesize($file_path);
    $extraction_threshold = 1 * 1024 * 1024; // 1MB

    if (strpos($mime_type, 'image') !== false) {
        $data['multimodal_parts'][] = [
            'inline_data' => [
                'mime_type' => $mime_type,
                'data' => base64_encode(file_get_contents($file_path))
            ]
        ];
    } 
    else if ($mime_type === 'application/pdf' || $mime_type === 'text/plain') {
        if ($file_size < $extraction_threshold) {
            // ... extract text directly ...
        } else {
            $transient_key = 'aica_gemini_uri_' . $file_id;
            $file_uri = get_transient($transient_key);

            if (false === $file_uri) {
                $file_uri = $this->upload_to_gemini($file_path, $mime_type);
                if ($file_uri) set_transient($transient_key, $file_uri, 1 * HOUR_IN_SECONDS);
            }

            if ($file_uri) {
                $data['multimodal_parts'][] = [
                    'file_data' => [
                        'mime_type' => $mime_type,
                        'file_uri'  => $file_uri
                    ]
                ];
            }
        }
    }

    return $data;
}

`upload_to_gemini`

This method handles the resumable upload protocol required by Gemini for large files. It first initiates an upload to get a unique upload URL, then sends the file content in chunks or a single request depending on the protocol's specifics.

`request_gemini`

This private method constructs the final API payload, including the system instruction, conversation contents, and generation configurations like temperature. It then dispatches the wp_remote_post request to the Gemini API endpoint, managing potential errors and parsing the LLM's response.

2. Grok Integration (`AICA_Plugin_LLM_Grok`)

The Grok integration allows your WordPress plugin to tap into xAI's Grok models. This implementation supports both direct text and file-based multimodal interactions, crucial for comprehensive LLM integrations.

`llm_api_v2` and `prepare_attachments`

Similar to Gemini, Grok's llm_api_v2 utilizes prepare_attachments for handling files. Images are Base64 encoded and included directly in the content array for the user message. For PDF or plain text files, if they are small, their content is appended to the system instruction (file_context_text). For larger files, the ensure_grok_file method is called to upload the file to Grok's service, and the returned file_id is used in the multimodal_parts array.

// Excerpt from AICA_Plugin_LLM_Grok::prepare_attachments
private function prepare_attachments(): array {
    $file_id = get_option('ai_agent_knowledge_file_id');
    $data = ['multimodal_parts' => [], 'file_context_text' => ""];

    if (!$file_id) return $data;

    $file_path = get_attached_file($file_id);
    if (!$file_path || !file_exists($file_path)) return $data;

    $mime_type = get_post_mime_type($file_id);
    $file_size = filesize($file_path);
    $threshold = 1 * 1024 * 1024; // 1MB

    if (strpos($mime_type, 'image') !== false) {
        $data['multimodal_parts'][] = [
            'type' => 'image_url',
            'image_url' => ['url' => "data:$mime_type;base64," . base64_encode(file_get_contents($file_path)), 'detail' => 'auto']
        ];
    } 
    else if ($mime_type === 'application/pdf' || $mime_type === 'text/plain') {
        if ($file_size < $threshold) {
            // ... extract text directly ...
        } else {
            $grok_file_id = $this->ensure_grok_file($file_path, $file_id);

            error_log("grok_file_id : ".$grok_file_id);

            if ($grok_file_id) {
                $data['multimodal_parts'][] = [
                    'type' => 'file',
                    'file' => ['file_id' => $grok_file_id]
                ];
            }
        }
    }

    return $data;
}

`ensure_grok_file`

This method handles uploading files to Grok's /v1/files endpoint using a multipart/form-data request. It's designed to be efficient by caching the file ID, preventing redundant uploads of the same file within a short period.

`request_grok`

This method constructs the full message payload for Grok, including the system prompt (referred to as developer_text in the code) and the conversation history. It then sends this payload to the /v1/chat/completions endpoint, managing API keys and error responses.

3. OpenAI Integration (`AICA_Plugin_LLM_OpenAI`)

The OpenAI integration connects your plugin to various OpenAI models, including those supporting multimodal capabilities (like GPT-4o). This specific implementation uses the /v1/responses endpoint, which is optimized for conversational AI with structured input/output, enhancing WordPress LLM integrations.

`llm_api_v2` and `prepare_attachments`

For llm_api_v2, prepare_attachments processes incoming files. Images are Base64 encoded as input_image types. Text-based documents (PDF, TXT) are either directly embedded if small or uploaded to OpenAI's file service via ensure_openai_file to obtain a file_id, which is then referenced as an input_file type. This flexible handling supports diverse data types.

// Excerpt from AICA_Plugin_LLM_OpenAI::prepare_attachments
private function prepare_attachments(): array {
    $file_id = get_option('ai_agent_knowledge_file_id');
    $data = ['multimodal_parts' => [], 'file_context_text' => ""];

    if (!$file_id) return $data;

    $file_path = get_attached_file($file_id);
    if (!$file_path || !file_exists($file_path)) {
        error_log("AICA OpenAI: File path not found for ID $file_id");
        return $data;
    }

    $mime_type = get_post_mime_type($file_id);
    $file_size = filesize($file_path);
    $threshold = 10 * 1024 * 1024; // 10MB

    if (strpos($mime_type, 'image') !== false) {
        $data['multimodal_parts'][] = [
            'type' => 'input_image',
            'image_url' => ['url' => "data:$mime_type;base64," . base64_encode(file_get_contents($file_path))]
        ];
    } 
    else if ($mime_type === 'application/pdf' || $mime_type === 'text/plain') {
        if ($file_size < $threshold) {
            // ... extract text directly ...
        } else {
            $openai_file_id = $this->ensure_openai_file($file_path, $file_id);
            if ($openai_file_id) {
                $data['multimodal_parts'][] = [
                    'type' => 'input_file',
                    'file' => ['file_id' => $openai_file_id]
                ];
            }
        }
    }

    return $data;
}

`ensure_openai_file`

This method uploads files to OpenAI's /v1/files endpoint with a purpose of user_data. It also utilizes a transient cache to store the OpenAI file ID, preventing redundant uploads and speeding up subsequent requests.

`format_conversation_items`

This method is crucial for structuring the conversation for the /v1/responses endpoint. It meticulously formats messages into an items array, differentiating between input_text (user queries) and output_text (assistant responses), and integrating any multimodal parts seamlessly.

`request_openai`

This method constructs the final payload for the /v1/responses endpoint, including instructions (system prompt), input (formatted conversation items), model, and temperature. It then sends the request and processes the structured response from OpenAI, handling potential API errors.

Key Takeaways for WordPress LLM Integrations

Modular Design: The plugin uses a boilerplate to separate concerns, making LLM integrations clean, manageable, and easy to extend.
Dynamic LLM Selection: Users can switch between Grok, OpenAI, and Gemini models directly from WordPress settings without altering core plugin logic.
Multimodal Support: The llm_api_v2 methods and prepare_attachments enable rich interactions with various data types, including images and documents.
Context Management: System instructions are dynamically built, incorporating core prompts, user-defined settings, feedback mechanisms, and knowledge base content for more relevant responses.
Robust Error Handling: Each integration includes checks for missing API keys, connection errors, and specific LLM-reported errors, providing clearer feedback.

This architecture provides a powerful and flexible way to embed cutting-edge AI capabilities directly into your WordPress applications. By understanding these core classes and their interactions, you're well-equipped to build intelligent features that enhance user experience and automate complex tasks in your WordPress plugin development.

Get Involved!

What are your thoughts on building LLM-powered WordPress plugins? Have you implemented similar LLM integrations in WordPress or faced unique challenges? Share your experiences and questions in the comments below!

If you found this deep dive helpful, please consider sharing it with your network and following me for more content on AI, WordPress, and plugin development.

Complete code at this repo:

d5b94396feba3 / llms-apis-wp-boilerplate-plugin

A collection of LLM (Large Language Model) API integration classes for WordPress plugins. Provides unified integration with multiple LLM providers including OpenAI, Google Gemini, and xAI Grok.

LLM APIs WordPress Plugin Component

📦 What This Is

🚀 Features

Multi-LLM Support: Integrate with OpenAI, Google Gemini, and xAI Grok APIs
File Attachment Support: Upload and process PDFs, images, and text files as knowledge bases
Conversation History: Maintain context across multiple interactions
Multimodal Support: Handle both text and image inputs
WordPress Standards: Built following WordPress coding standards and best practices
Object-Oriented Architecture: Clean, maintainable code…

View on GitHub

Demystifying Real-time Admin Previews: JavaScript & PHP for Dynamic Chat Widget Configuration

Shahibur Rahman — Mon, 12 Jan 2026 10:25:08 +0000

Ever configured a plugin or widget in an admin panel and wished you could see your changes instantly, without saving or refreshing? That's the magic of real-time admin previews! This article will break down how a dynamic chat widget's admin preview works, focusing on the interplay between JavaScript (jQuery) and PHP to provide an immediate visual update as you tweak settings. We'll explore the core JavaScript function, its interaction with HTML elements, and how event listeners bring it all to life.

The Foundation: Our HTML and PHP Setup for Real-time Admin Previews

Before diving into the JavaScript, it's crucial to understand the basic HTML structure that PHP generates. The WordPress admin page, powered by PHP, renders both the input fields where you enter settings (like display name, welcome message, colors) and the actual chat widget preview area. Each input field is designed with specific name attributes that JavaScript will target, and many also have a special class like admin-preview-trigger.

Here's a simplified look at how PHP might generate an input field and the corresponding preview element:

<!-- PHP snippet (conceptual) for an input field -->
<input type="text" name="ai_agent_display_name" value="<?php echo esc_attr(get_option('ai_agent_display_name', 'AI Assistant')); ?>" class="large-text professional-input admin-preview-trigger">

<!-- PHP snippet (conceptual) for the preview wrapper -->
<div id="aica-admin-preview-container">
    <div id="ai-chat-wrapper">
        <div class="chat-header">
            <span class="header-name">AI Assistant</span>
        </div>
        <div id="chat-messages">
            <!-- Welcome messages will be dynamically added here -->
        </div>
        <div class="chat-input-area">
            <textarea id="chat-input" placeholder="Message..."></textarea>
        </div>
        <button id="ai-chat-bubble" class="launcher-btn"></button>
    </div>
</div>

Notice the name attributes (e.g., ai_agent_display_name) on the input fields and unique ids or classes (e.g., header-name, ai-chat-wrapper, aica-admin-preview-container) on the preview elements. These are the hooks our JavaScript will use.

The JavaScript Engine: `syncAdminPreview()` Function for Dynamic Updates

The heart of our real-time admin previews is the syncAdminPreview() function, wrapped in a jQuery(document).ready() block to ensure the DOM is fully loaded before execution. This means the function won't try to manipulate elements that haven't been loaded by the browser yet.

jQuery(document).ready(function($) {

    function syncAdminPreview() {
        // ... (function body explained below)
    }

    // ... (event bindings explained later)
});

Step 1: Gathering Your Settings with `syncAdminPreview()`

The first job of syncAdminPreview() is to collect all the current settings from the admin input fields. It smartly uses localStorage as a fallback. This means if you switch between admin tabs (e.g., from 'Content' to 'Style'), the preview can still remember and display the values from the previous tab's inputs.

Here’s how it retrieves key values:

Display Name: $('input[name="ai_agent_display_name"]').val()
Welcome Message: $('textarea[name="ai_agent_welcome_msg"]').val()
Message Placeholder: $('input[name="ai_agent_placeholder"]').val()
Brand Color: $('#ai_agent_primary_color_input').val()
Avatar URL: $('#ai_agent_logo_preview').attr('src')
Launcher Icon Type: $('select[name="ai_agent_bubble_icon"]').val()
Theme Mode: $('input[name="ai_agent_theme_mode"]:checked').val() (for radio buttons)

Let's look at a snippet:

    function syncAdminPreview() {
        // --- 1. GET VALUES WITH LOCAL STORAGE FALLBACK ---
        const nameInput = $('input[name="ai_agent_display_name"]');
        if (nameInput.length) localStorage.setItem('aica_preview_name', nameInput.val());
        const name = localStorage.getItem('aica_preview_name') || 'AI Assistant';

        const welcomeInput = $('textarea[name="ai_agent_welcome_msg"]');
        if (welcomeInput.length) localStorage.setItem('aica_preview_welcome', welcomeInput.val());
        const welcomeText = localStorage.getItem('aica_preview_welcome') || '';

        const brandColor = $('#ai_agent_primary_color_input').val() || '#000000';

        let avatarUrl = $('#ai_agent_logo_preview').attr('src');
        if (!avatarUrl || avatarUrl.includes('default-avater.svg')) {
            avatarUrl = '/wp-content/plugins/ai-chat-agent/assets/images/default-avater.svg'; 
        }
        // ... other value retrievals
    }

Step 2: Updating the Preview in Real-time

Once all settings are gathered, syncAdminPreview() proceeds to update the visual preview. It targets specific HTML elements within the #aica-admin-preview-container and modifies their text, attributes, or even rebuilds entire sections.

Targeting Elements: It first identifies the main preview container and the chat wrapper within it.

    const $preview = $('#aica-admin-preview-container');
    const $wrapper = $preview.find('#ai-chat-wrapper');

Applying Theme Class: It toggles CSS classes to switch between light and dark themes.

    $wrapper.removeClass('theme-light theme-dark').addClass('theme-' + themeMode);

Updating Name & Placeholder: The display name and input placeholder are updated directly.

    $preview.find('.header-name, .msg-bot-name').text(name);
    $preview.find('#chat-input').attr('placeholder', placeholder);

Re-building Welcome Bubbles: This is a dynamic process. The welcomeText (from the textarea) is split by newlines to create individual chat bubbles. The HTML for these bubbles is generated on the fly and then prepended to the #chat-messages container. This effectively clears old welcome messages and adds new ones.

    const lines = welcomeText.split('\n').filter(l => l.trim() !== "");
    let welcomeHtml = '';
    lines.forEach((line, index) => {
        welcomeHtml += `
            <div class="msg ai welcome-msg">
                <div class="msg-avatar-container">
                    ${index === 0 ? `<img src="${avatarUrl}" class="msg-avatar">` : ''}
                </div>
                <div class="msg-content-wrapper">
                    ${index === 0 ? `<div class="msg-bot-name">${name}</div>` : ''}
                    <div class="bubble">${line}</div>
                </div>
            </div>`;
    });

    $preview.find('.welcome-msg').remove(); // Clear existing welcome messages
    $preview.find('#chat-messages').prepend(welcomeHtml); // Add new ones

Updating Colors and Avatars: The primary brand color is applied to the chat bubble launcher and user messages, and the avatar image URL is updated.

    $preview.find('#ai-chat-bubble, .user .bubble').css('background-color', brandColor);
    $preview.find('.header-logo, .msg-avatar').attr('src', avatarUrl);

Launcher Icon Update: This logic determines whether to show the default message icon or the uploaded profile image on the floating chat button.

    const $iconContainer = $preview.find('.launcher-img-container');
    if (iconSelect === 'logo') {
        $iconContainer.removeClass('is-default-icon').html(`<img src="${avatarUrl}" class="launcher-img">`);
    } else {
        $iconContainer.addClass('is-default-icon').html('<svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="white" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"></path></svg>');
    }

Making it Interactive: Event Listeners for Real-time Admin Previews

The syncAdminPreview() function is powerful, but it needs to be called whenever a relevant setting changes. This is where event listeners come in. They "listen" for user interactions on specific HTML elements and trigger the preview update.

Theme Changes: A dedicated listener for radio buttons that control the theme. The change event is suitable here as it fires when a radio button's selection is committed.

$(document).on('change', 'input[name="ai_agent_theme_mode"]', function() {
    const $card = $(this).closest('.aica-theme-card');
    $('.aica-theme-card').removeClass('is-active').find('.theme-card-inner').css('border-color', '#e2e8f0');
    $card.addClass('is-active').find('.theme-card-inner').css('border-color', '#3b82f6');
    syncAdminPreview(); // Call the update function
});

General Input Changes: A more generic listener for text inputs, color pickers, and select dropdowns. The key here is the .admin-preview-trigger class, which is added to any input that should cause a real-time preview update.
```
$(document).on('input change', '.admin-preview-trigger, #ai_agent_primary_color_input, select[name="ai_agent_bubble_icon"]', function() {
    syncAdminPreview(); // Call the update function
});
```

The input event fires immediately as the user types, providing instant feedback.
The change event fires when an element's value is committed (e.g., after typing and blurring, or selecting from a dropdown). Using both ensures broad coverage.

A Live Walkthrough: Changing the Chat Widget Name

Let's trace a simple interaction to solidify our understanding of real-time admin previews:

User Action: You navigate to the 'Content' tab in the admin panel and locate the "Display Name" input field. You start typing "My Awesome AI" into this input.
```
<input type="text" name="ai_agent_display_name" value="AI Assistant" class="large-text professional-input admin-preview-trigger">
```
Event Trigger: As you type, the input event fires on this specific <input> element. Since this input has the class admin-preview-trigger, it matches the selector in our general event listener: $(document).on('input change', '.admin-preview-trigger', ...).
Function Call: The event listener executes the syncAdminPreview() function.
Value Retrieval: Inside syncAdminPreview(), the line const nameInput = $('input[name="ai_agent_display_name"]'); finds your input field. nameInput.val() retrieves "My Awesome AI". This value is then stored in localStorage and assigned to the name variable.
Preview Update: The line $preview.find('.header-name, .msg-bot-name').text(name); targets the <span class="header-name"> element (and other elements with .msg-bot-name) inside your chat widget preview and updates its text content to "My Awesome AI".

Result? As you type, the name in the chat widget preview updates character by character – a seamless, real-time experience!

Key Takeaways

Real-time Admin Previews significantly enhance user experience by providing instant feedback on configuration changes.
The core of the system is a robust JavaScript function (like syncAdminPreview()) that gathers settings and dynamically updates the preview's HTML and CSS.
jQuery selectors ($ functions) are crucial for efficiently targeting specific input fields and preview elements by their name, id, or class attributes.
Event listeners (.on('input change', ...)) act as the glue, triggering the update function whenever a user interacts with a setting.
Using localStorage provides data persistence across different admin tabs, making the preview more reliable and consistent.

Your Turn!

Understanding this pattern is incredibly useful for building dynamic interfaces. Have you implemented similar real-time previews in your projects? Share your experiences, challenges, or alternative approaches in the comments below! If you found this breakdown helpful, consider following for more web development insights.

Automating WordPress Content Scraping: Build a Knowledge Base Plugin (Beginner's Guide)

Shahibur Rahman — Thu, 08 Jan 2026 10:40:48 +0000

Developing robust WordPress plugins often benefits from a structured approach. This tutorial dives into creating a powerful WordPress Content Scraping and knowledge base synchronization plugin, leveraging a solid boilerplate structure. We'll explore how to automatically scan your website's pages, scrape their content, and store it efficiently in your database to build a custom knowledge base.

This guide is designed for beginners looking to understand WordPress plugin architecture and implement advanced functionalities like web scraping within the WordPress ecosystem.

Why Automate WordPress Content Scraping?

In today's dynamic web, keeping an external AI or search index updated with your site's latest content can be a challenge. Manually updating knowledge bases is tedious and prone to errors. By implementing an automated WordPress Content Scraping mechanism, you can:

Maintain a Fresh Knowledge Base: Ensure your AI chatbots or internal search features always have the most current information.
Improve Data Consistency: Reduce discrepancies between your live site and its stored knowledge.
Save Time: Eliminate manual content extraction and updates.

We'll achieve this by building upon a well-organized WordPress Plugin Boilerplate.

The Foundation: WordPress Plugin Boilerplate

A boilerplate provides a standardized, organized, and extensible base for your plugin development. It separates concerns, making your code cleaner and easier to maintain. For this project, we'll imagine using a structure similar to this:

my-wp-plugin/
├── 📄 my-wp-plugin.php
├── 📁 includes/
│   ├── 📄 class-main.php               # Plugin orchestrator
│   ├── 📄 class-loader.php             # Hook manager
│   ├── 📄 class-activator.php          # Activation handler
│   └── 📄 class-deactivator.php        # Deactivation handler
├── 📁 admin/                           # Backend functionality ONLY
│   ├── 📄 class-admin.php              # Admin controller
│   └── 📁 partials/                    # Admin HTML templates
│       └── 📄 admin-settings.php
├── 📁 public/                          # Frontend functionality ONLY
│   └── 📄 class-public.php             # Frontend controller
├── 📁 assets/                          # ALL static files
│   ├── 📁 css/
│   └── 📁 js/
│       ├── 📄 admin.js
│       └── 📄 knowledge-base.js
└── 📁 languages/

This structure helps us organize our PHP logic (includes, admin, public) and static assets (assets).

d5b94396feba3 / WP-Plugin-Boilerplate

A modern, object-oriented WordPress plugin boilerplate following WordPress coding standards. Features a generic structure where you only need to change ONE FILE to create a completely new plugin.

WP Plugin Boilerplate

A modern, object-oriented WordPress plugin boilerplate following WordPress coding standards. Features a generic structure where you only need to change ONE FILE to create a completely new plugin.

🚀 Features

One-File Setup (True Dynamic Naming): Change only the main plugin file's header to rename the plugin, slug, version, menu items, and file handles across the entire codebase.

Object-Oriented Architecture: Clean, maintainable code structure.

WordPress Standards: Follows WordPress coding standards and best practices.

Security Ready: Built-in security measures and data sanitization.

Internationalization: Ready for translations with proper text domains.

Admin & Public Separation: Organized separation of backend and frontend functionality.

Hook Management: Centralized WordPress hook system.

Asset Management: Proper CSS/JS enqueuing for admin and public.

📁 Plugin Structure

my-wp-plugin/
├── 📄 my-wp-plugin.php                 # Main plugin file (ONLY FILE TO EDIT HEADER)
├── 📄 index.php
├── 📁 includes/                        # Core

…

View on GitHub

Core Components for Your WordPress Content Scraper

1. The Admin Controller (`class-admin.php`)

The AICA_Plugin_Admin class is responsible for all backend functionalities, including managing settings and handling AJAX requests for our content scraper.

Here's a snippet showing how it registers settings and handles the content synchronization AJAX:

// In my-wp-plugin/admin/class-admin.php

class AICA_Plugin_Admin {
    // ... other properties and constructor ...

    public function register_settings() {
        // ... other settings ...
        register_setting($this->plugin_slug . '_prompt_settings', 'ai_agent_knowledge_file_id');
    }

    public function handle_sync_website_ajax() {
        check_ajax_referer('admin_proposal_nonce', 'nonce');
        if (!current_user_can('manage_options')) wp_send_json_error('Unauthorized');

        $step = isset($_POST['sync_step']) ? sanitize_text_field($_POST['sync_step']) : 'discovery';
        $db = $this->get_db_manager();

        // Initialize your scraper class (e.g., AICA_Plugin_SimpleHTMLDOM)
        $scraper = new AICA_Plugin_SimpleHTMLDOM(); // This would be your custom scraper implementation

        if ($step === 'discovery') {
            $posts = get_posts([
                'post_type' => ['page', 'post'], 
                'posts_per_page' => -1, 
                'post_status' => 'publish'
            ]);

            $pages = [];
            $excluded_slugs = ['cart', 'checkout', 'my-account', 'logout', 'login', 'register', 'sample-page'];

            foreach ($posts as $post) {
                if (in_array($post->post_name, $excluded_slugs)) continue;
                $url = get_permalink($post->ID);
                $sync_data = $db->get_sync_status($url);

                $pages[] = [
                    'url'    => $url,
                    'title'  => $post->post_title,
                    'status' => $sync_data ? 'Synced' : 'Pending',
                    'last'   => $sync_data ? date_i18n(get_option('date_format'), strtotime($sync_data['last_synced'])) : '-'
                ];
            }
            wp_send_json_success(['pages' => $pages]);
        }

        if ($step === 'sync_page') {
            $url = esc_url_raw($_POST['url']);
            $content = $scraper->scrape_page($url); // The actual scraping happens here

            if (empty($content)) {
                wp_send_json_error('Page empty or ignored');
            }

            $db->update_knowledge_base($url, $content); // Store the scraped content

            wp_send_json_success([
                'status' => 'Synced', 
                'last'   => current_time('mysql')
            ]);
        }
    }
    // ... other methods ...
}

The handle_sync_website_ajax method is crucial. It has two main steps:

Discovery: It fetches all published WordPress pages and posts, filters out common irrelevant pages (like cart/checkout), and prepares a list of URLs to be synced.
Sync Page: For each URL, it uses an instance of AICA_Plugin_SimpleHTMLDOM (which you would implement or integrate from a library) to scrape_page() and extract its content. This extracted content is then passed to the database manager.

2. The Database Manager (`class-db-manager.php`)

The AICA_Plugin_DB_Manager handles all interactions with the database, including creating custom tables and storing/retrieving scraped content.

// In my-wp-plugin/includes/class-db-manager.php

class AICA_Plugin_DB_Manager {
    // ... properties and constructor ...

    public static function create_table( $plugin_slug ) {
        global $wpdb;
        $clean_slug = str_replace('-', '_', sanitize_key($plugin_slug));
        $kb_table = $wpdb->prefix . $clean_slug . '_knowledge_base'; // Our knowledge base table

        $charset_collate = $wpdb->get_charset_collate();

        $sql_kb = "CREATE TABLE $kb_table (
            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
            source_url VARCHAR(255) NOT NULL,
            content LONGTEXT NOT NULL,
            last_synced DATETIME NOT NULL,
            PRIMARY KEY (id),
            UNIQUE KEY source_url (source_url(191))
        ) $charset_collate;";

        require_once ABSPATH . 'wp-admin/includes/upgrade.php';
        dbDelta( $sql_kb ); // Creates or updates the table
    }

    public function update_knowledge_base($url, $content) {
        global $wpdb;
        $table = $this->get_kb_table_name();

        $content = trim($content); // Ensure content is clean

        // Uses wpdb->replace to either insert new or update existing records based on source_url
        return $wpdb->replace(
            $table,
            [
                'source_url'  => esc_url_raw($url),
                'content'     => $content,
                'last_synced' => current_time('mysql')
            ],
            ['%s', '%s', '%s']
        );
    }

    public function get_sync_status($url) {
        $table = $this->get_kb_table_name();
        return $this->wpdb->get_row(
            $this->wpdb->prepare("SELECT last_synced FROM $table WHERE source_url = %s", $url),
            ARRAY_A
        );
    }
}

The create_table method is called during plugin activation to set up our _knowledge_base table. This table stores the source_url, the content scraped from that URL, and the last_synced timestamp. The update_knowledge_base method uses wpdb->replace which is convenient for either inserting new pages or updating existing ones.

3. The Admin User Interface (`admin-settings.php` & `knowledge-base.js`)

The admin-settings page (admin/partials/admin-settings.php) provides the user interface for initiating and monitoring the WordPress Content Scraping process.

// Snippet from admin/partials/admin-settings.php for the Knowledge Base tab
<?php elseif ($active_tab === 'prompt'): ?>
    <form method="post" action="options.php">
        <?php settings_fields($this->plugin_slug . '_prompt_settings'); ?>
        <div class="postbox professional-box knowledge-sync-wrapper">
            <div class="postbox-header" id="toggle-sync-table">
                <h2 class="hndle">Website Knowledge Sync</h2>
                <!-- ... UI elements for status and toggle ... -->
            </div>
            <div class="inside" id="sync-collapsible-content">
                <div id="discovery-loader">...</div>
                <div id="sync-progress-bar">...</div>
                <div id="sync-success-msg">...</div>
                <div id="sync-data-container">
                    <table class="wp-list-table widefat fixed striped">
                        <thead>
                            <tr><th>Page Source</th><th>Status</th><th>Last Sync</th></tr>
                        </thead>
                        <tbody id="sync-table-body"></tbody>
                    </table>
                    <div style="margin-top:20px;">
                        <button type="button" id="run-bulk-sync" class="button button-hero button-primary"></button>
                        <button type="button" id="start-discovery-refresh" class="button button-secondary">Refresh Map</button>
                    </div>
                </div>
            </div>
        </div>
        <!-- ... other AI Persona settings ... -->
        <?php submit_button('Save AI Persona & Knowledge'); ?>
    </form>

The JavaScript file (assets/js/admin/knowledge-base.js) handles the client-side logic:

It triggers the discovery AJAX call on page load (if on the correct tab).
It populates the table with discovered pages and their sync status.
It handles the "Run Bulk Sync" button click, iterating through pending pages and making individual sync_page AJAX calls.
It updates the progress bar and displays success messages.

// In my-wp-plugin/assets/js/admin/knowledge-base.js

jQuery(document).ready(function($) {
    let pages = [];

    // Auto-load Discovery on Page Load
    const urlParams = new URLSearchParams(window.location.search);
    if (urlParams.get('tab') === 'prompt') {
        runDiscovery();
    }

    // Function to initiate page discovery via AJAX
    function runDiscovery() {
        $('#discovery-loader').show(); // Show loading spinner
        $('#sync-data-container, #sync-success-msg, #sync-progress-bar').hide(); // Hide other elements

        $.post(adminProposalData.ajax_url, {
            action: 'sync_website_knowledge',
            sync_step: 'discovery',
            nonce: adminProposalData.nonce
        }, function(res) {
            $('#discovery-loader').hide();
            if(res.success) {
                pages = res.data.pages;
                renderRows(pages); // Populate the table
                updateSyncButtonState(); // Update sync button text
                $('#sync-data-container').fadeIn();
                $('#sync-summary-badge').text(pages.length + ' Pages Found').show();
            }
        });
    }

    // Bulk Sync Logic
    $('#run-bulk-sync').on('click', async function() {
        const $btn = $(this).prop('disabled', true).text('Syncing...');
        $('#sync-progress-bar').slideDown();
        $('#sync-success-msg').hide();

        let syncedCount = 0;

        for(let i=0; i < pages.length; i++) {
            let p = pages[i];
            let percent = Math.round(((i + 1) / pages.length) * 100);

            $('#sync-msg').text(`Processing: ${p.title}`);
            $('#sync-fill').css('width', percent + '%');
            $('#sync-percent').text(percent + '%');

            // Send individual AJAX request for each page sync
            const response = await $.post(adminProposalData.ajax_url, {
                action: 'sync_website_knowledge',
                sync_step: 'sync_page',
                url: p.url,
                nonce: adminProposalData.nonce
            });

            if(response.success) {
                syncedCount++;
                const $row = $(`tr[data-url="${p.url}"]`);
                $row.find('.status-badge').attr('class', 'status-badge status-approved').text('Synced');
                $row.find('.last-sync-col').text('Just now');
                pages[i].status = 'Synced'; // Update local state
            }
        }

        // Completion UI sequence
        $('#sync-progress-bar').delay(500).slideUp(400, function() {
            $('#sync-success-msg').fadeIn();
            updateSyncButtonState();
            setTimeout(function() {
                $('#sync-success-msg').fadeOut(500);
            }, 4000);
        });
    });
    // ... other UI functions like renderRows, updateSyncButtonState ...
});

This JavaScript orchestrates the entire synchronization process, providing real-time feedback to the user on the progress of the WordPress Content Scraping.

Deep Dive: The `AICA_Plugin_SimpleHTMLDOM` for Content Scraping

At the heart of our WordPress Content Scraping mechanism is the AICA_Plugin_SimpleHTMLDOM class. This class acts as a wrapper for the popular simple_html_dom PHP library, making it easy to fetch and parse HTML content from URLs.

Integrating the `simple_html_dom` Library

First, we need to ensure the simple_html_dom.php file is loaded. In a typical WordPress plugin setup using a boilerplate, you might place external libraries in a vendor/ directory.

// In my-wp-plugin/includes/class-simplehtmldom.php

defined( 'ABSPATH' ) || exit;

class AICA_Plugin_SimpleHTMLDOM {

    public function __construct() {
        $this->load_lib();
    }

    private function load_lib() {
        // Path to the simple_html_dom.php library
        $lib_path = AICA_PLUGIN_PATH . 'vendor/simplehtmldom/simple_html_dom.php';
        if ( file_exists( $lib_path ) ) {
            require_once $lib_path;
        } else {
            // Handle error if library not found (e.g., log it)
            error_log('Simple HTML DOM library not found at: ' . $lib_path);
        }
    }

    // ... rest of the class methods ...
}

The load_lib() method checks if the simple_html_dom.php file exists at the expected path and then includes it using require_once. This ensures the library's functions (like str_get_html) are available when needed.

How `scrape_page` Works

The scrape_page method is where the actual content extraction happens. Let's break down its functionality:

// Inside AICA_Plugin_SimpleHTMLDOM class

    public function scrape_page( $url ) {
        // 1. Fetch the HTML content from the URL
        $response = wp_remote_get( $url, ['timeout' => 15] );
        if ( is_wp_error( $response ) ) return ''; // Handle errors

        $html_content = wp_remote_retrieve_body( $response );

        // 2. Use simple_html_dom to parse the HTML string
        $html = str_get_html( $html_content );
        if ( ! $html ) return ''; // Return empty if parsing fails

        // 3. Early exit for 'Page Not Found' titles
        $title = $html->find('title', 0) ? $html->find('title', 0)->plaintext : '';
        if (stripos($title, 'Page not found') !== false) {
            $html->clear();
            return '';
        }

        // 4. Remove unwanted elements (scripts, styles, navigation, footers, etc.)
        foreach($html->find('script, style, nav, footer, header, noscript, .gdpr, .cookie, #cookie-law-info-bar') as $item) {
            $item->outertext = ''; 
        }

        // 5. Extract the pure plain text from the cleaned HTML
        $text = $html->plaintext;

        // 6. Perform a "nuclear cleanup" on the text
        // Convert HTML entities (like &nbsp;) to actual characters
        $text = html_entity_decode($text, ENT_QUOTES, 'UTF-8');

        // Replace all types of whitespace (multiple spaces, newlines, tabs) with a single space
        $text = preg_replace('/\s+/u', ' ', $text);

        // Clean up memory used by simple_html_dom
        $html->clear();
        unset($html);

        return trim($text); // Return the final, cleaned text
    }

// ... other methods like sync_website_content ...

This method demonstrates a robust way to fetch, clean, and extract meaningful text content from a web page, which is essential for accurate WordPress Content Scraping.

Key Takeaways

Structured Development: Using a boilerplate significantly improves plugin organization and maintainability.
AJAX for Background Tasks: WordPress AJAX is ideal for long-running tasks like content scraping, preventing UI freezes.
Custom Database Tables: For storing custom data like scraped content, creating your own tables is often more efficient than using wp_options or wp_posts.
Client-Side Feedback: Providing progress bars and status updates through JavaScript enhances the user experience for intensive operations.
Targeted Scraping: By fetching post_type and filtering slugs, you can control exactly which content your WordPress Content Scraping targets.
Simple HTML DOM: A powerful PHP library that simplifies parsing and manipulating HTML content for scraping purposes.

Next Steps

This framework provides a solid foundation for your WordPress Content Scraping plugin. You could extend it by:

Implementing a more sophisticated AICA_Plugin_SimpleHTMLDOM class to handle various content structures or even external websites.
Adding scheduling options to run the sync automatically using WordPress Cron.
Integrating with external AI services to process the scraped content for advanced knowledge base features.

What are your thoughts on building an automated content scraper for WordPress? Share your ideas and experiences in the comments below!

Mastering CSS Grid for Responsive Layouts: A Comprehensive Guide

Shahibur Rahman — Tue, 16 Dec 2025 14:40:56 +0000

Are you tired of wrestling with floats, complex media queries, and fragile layout systems to achieve responsive designs? It's time to master CSS Grid Responsive Layouts! CSS Grid is a powerful two-dimensional layout system that allows you to design complex, responsive web layouts with unparalleled ease and flexibility. If you're an intermediate developer looking to elevate your front-end skills and build robust, adaptive interfaces, you're in the right place.

In this guide, we'll dive deep into CSS Grid, covering its core concepts, practical implementation, and advanced techniques to create truly responsive designs that adapt seamlessly across all devices. Get ready to transform your approach to web layouts!

Understanding the Core Concepts of CSS Grid

Before we start building, let's grasp the fundamental terminology that makes CSS Grid so intuitive.

Grid Container: The element on which display: grid; is applied. It becomes the parent for all grid items.
Grid Items: The direct children of the grid container.
Grid Lines: The dividing lines that make up the structure of the grid, both vertical (column lines) and horizontal (row lines).
Grid Tracks: The space between two adjacent grid lines, forming columns or rows.
Grid Cells: The intersection of a grid row and a grid column, similar to a table cell.
Grid Areas: Named regions of the grid, defined by grid-template-areas, making placement of items incredibly semantic.

Unlike Flexbox, which is primarily for one-dimensional layouts (rows or columns), CSS Grid excels at two-dimensional layouts, giving you control over both rows and columns simultaneously. This makes it the ideal tool for overall page structure and complex component arrangements.

Defining Your Grid Structure with Ease

The magic of CSS Grid begins by defining your grid container and its tracks. Let's look at the essential properties.

Setting Up Your Grid Container

First, turn an element into a grid container:

.container {
  display: grid;
}

Now, define your columns and rows using grid-template-columns and grid-template-rows. You can use fixed units (px, em, rem), percentages, or the flexible fr unit, which distributes available space proportionally.

.container {
  display: grid;
  grid-template-columns: 1fr 2fr 1fr; /* Three columns: middle is twice as wide */
  grid-template-rows: auto 200px 1fr; /* Three rows: auto height, fixed 200px, remaining space */
  gap: 20px; /* Space between grid cells */
}

Another powerful feature is repeat() for repetitive patterns and minmax() for flexible sizing within bounds.

.gallery {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
  grid-gap: 15px;
}

The repeat(auto-fit, minmax(250px, 1fr)) pattern is a cornerstone for CSS Grid Responsive Layouts, creating as many 250px wide columns as possible, stretching them to fill available space, and wrapping when necessary.

Using Grid Template Areas for Semantic Layouts

For highly readable and maintainable layouts, grid-template-areas is a game-changer. You define named areas visually.

.page-layout {
  display: grid;
  grid-template-columns: 1fr 3fr 1fr;
  grid-template-rows: auto 1fr auto;
  grid-template-areas:
    "header header header"
    "nav    main   aside"
    "footer footer footer";
  gap: 10px;
}

Placing and Aligning Items within Your CSS Grid Responsive Layouts

Once your grid structure is defined, placing items is straightforward. You can use line-based placement or area-based placement.

Line-Based Placement

.item-a {
  grid-column: 1 / 3; /* Starts at column line 1, ends at column line 3 (spans 2 columns) */
  grid-row: 2;
}

.item-b {
  grid-column: 3 / span 1; /* Starts at column line 3, spans 1 column */
  grid-row: 1 / span 2; /* Starts at row line 1, spans 2 rows */
}

Area-Based Placement (with `grid-template-areas`)

This is much cleaner when you've defined grid-template-areas:

.header { grid-area: header; }
.nav    { grid-area: nav;    }
.main   { grid-area: main;   }
.aside  { grid-area: aside;  }
.footer { grid-area: footer; }

Alignment Properties

CSS Grid also provides powerful alignment properties for items within their cells or areas:

justify-items (horizontal alignment for all items in the grid container)
align-items (vertical alignment for all items in the grid container)
place-items (shorthand for align-items and justify-items)
justify-self, align-self, place-self (for individual grid items)

Building Truly CSS Grid Responsive Layouts

The real power of CSS Grid for responsive design comes from combining its flexible units and area definitions with media queries.

Let's refine our page-layout example to be responsive:

<div class="page-layout">
  <header>Header</header>
  <nav>Navigation</nav>
  <main>Main Content</main>
  <aside>Sidebar</aside>
  <footer>Footer</footer>
</div>

.page-layout {
  display: grid;
  grid-template-columns: 1fr; /* Single column on small screens */
  grid-template-rows: auto;
  grid-template-areas:
    "header"
    "nav"
    "main"
    "aside"
    "footer";
  gap: 10px;
  min-height: 100vh; /* Ensure it takes full viewport height */
}

@media (min-width: 768px) {
  .page-layout {
    grid-template-columns: 1fr 3fr;
    grid-template-areas:
      "header header"
      "nav    main"
      "nav    aside"
      "footer footer";
  }
}

@media (min-width: 1024px) {
  .page-layout {
    grid-template-columns: 1fr 3fr 1fr;
    grid-template-areas:
      "header header header"
      "nav    main   aside"
      "footer footer footer";
  }
}

/* Basic styling for visibility */
.page-layout > * {
  background-color: #e0e0e0;
  padding: 20px;
  border-radius: 5px;
  text-align: center;
}
header { background-color: #a7d9b7; }
nav    { background-color: #a7c0d9; }
main   { background-color: #d9a7a7; }
aside  { background-color: #d9cfa7; }
footer { background-color: #b7a7d9; }

This example demonstrates how effortlessly you can redefine your entire layout at different breakpoints using grid-template-areas and media queries, making CSS Grid Responsive Layouts a joy to implement.

Key Takeaways for Mastering CSS Grid

CSS Grid is a 2D layout system, perfect for overall page structure.
Use display: grid; on the container.
grid-template-columns and grid-template-rows define your track structure, with fr, repeat(), and minmax() being essential for flexibility.
grid-template-areas provides a highly semantic way to define and manage complex layouts.
Combine Grid with media queries to effortlessly create CSS Grid Responsive Layouts that adapt to any screen size.
auto-fit/auto-fill with minmax() is your go-to for dynamically sized, wrapping grids.

What are Your Favorite CSS Grid Tricks?

CSS Grid is a game-changer for front-end development. By mastering its concepts, you can build incredibly robust and flexible layouts with less code and more clarity. Experiment with these properties and see how they transform your workflow.

What are your go-to strategies for building CSS Grid Responsive Layouts? Share your favorite tips, tricks, or challenges in the comments below! If you found this guide helpful, consider sharing it with your network and following me for more in-depth web development tutorials.

Happy Gridding!

Automating Contract Signing and Payments in WordPress Using DocuSign + Stripe

Shahibur Rahman — Thu, 06 Nov 2025 10:00:57 +0000

If you want clients to sign a contract and pay right away inside your WordPress workflow, this setup shows exactly how to achieve a seamless WordPress DocuSign Stripe integration. This guide outlines how a custom plugin connects DocuSign for e-signatures and Stripe for payments. When the client signs, they're instantly redirected to a secure checkout page – no manual steps, no chasing invoices.

The integration is built around two core classes:

Plugin_DocuSign_Contract – e-signature engine
Plugin_Stripe_Processor – payment handler

Plugin Architecture Overview

The structure follows the WordPress Plugin Boilerplate for clear separation between admin, public, and core logic, essential for robust WordPress DocuSign Stripe integration.

my-wp-plugin/
├── my-wp-plugin.php
├── includes/
│ ├── class-main.php
│ ├── class-loader.php
│ ├── class-activator.php
│ └── class-deactivator.php
├── admin/
│ ├── class-admin.php
│ └── partials/
├── public/
│ └── class-public.php
├── assets/
│ ├── css/
│ ├── js/
│ └── images/
├── languages/
└── uninstall.php

The DocuSign and Stripe integration lives inside includes/, handled by the two main classes.

How DocuSign → Stripe Works: The Automated Flow

This integration orchestrates a seamless hand-off between signing and payment. Here's a high-level overview of the process for automating contract signing and payments:

Plugin generates a DocuSign envelope: It prepares JWT authentication, builds the envelope with both client and admin signers, and temporarily stores relevant data (like envelope ID) in WordPress transients.
Client signs: The client uses an embedded signing experience via DocuSign's Recipient View, completing the signature process within DocuSign's UI.
DocuSign redirects back: Upon completion, DocuSign redirects the client back to a specified WordPress URL, passing crucial parameters.
Plugin retrieves stored data: Your plugin retrieves the previously stored envelope data from transients.
Plugin creates a Stripe Checkout Session: It dynamically generates a real-time product and price for the service, returning a unique Checkout URL.
Client completes payment: The client is redirected to the secure Stripe Checkout page to finalize the payment.
Plugin verifies payment: After successful payment, the plugin verifies the transaction status and triggers any necessary post-payment actions (e.g., updating contract status, sending confirmations).

Stripe Integration (Payment Engine)

This section details the Stripe integration for handling payments within your WordPress plugin.

1. Initialization

public function __construct($plugin_slug) {
    $this->plugin_slug = $plugin_slug;
    $this->load_stripe_library();
    $this->initialize_stripe();
}

This method loads the Stripe PHP SDK and sets keys based on test/live mode.

2. Loading the Stripe Library

private function load_stripe_library() {
    $stripe_lib_path = MY_PLUGIN_PATH . 'vendor/stripe/stripe-php/init.php';
    if (file_exists($stripe_lib_path)) {
        require_once $stripe_lib_path;
    }
}

3. Initializing Stripe Mode

private function initialize_stripe() {
    $this->stripe_mode = get_option('stripe_mode', 'test');
    $this->stripe_secret_key = $this->stripe_mode === 'live'
        ? get_option('stripe_live_secret_key')
        : get_option('stripe_test_secret_key');
    \Stripe\Stripe::setApiKey($this->stripe_secret_key);
}

4. Creating a Checkout Session

$session = \Stripe\Checkout\Session::create([
    'payment_method_types' => ['card'],
    'line_items' => [[
        'price_data' => [
            'currency' => $currency,
            'product_data' => ['name' => "Service Agreement - $company_name"],
            'unit_amount' => $amount_cents,
        ],
        'quantity' => 1,
    ]],
    'mode' => 'payment',
    'success_url' => home_url('/payment-success/'),
    'cancel_url' => home_url('/payment-cancelled/')
]);

The client is then redirected to $session->url.

DocuSign Integration (Contract Engine)

This part handles authentication, envelope creation, embedded signing, and the crucial redirect to Stripe for the full WordPress DocuSign Stripe integration.

1. Required DocuSign Credentials

Here's a list of the constants and their descriptions you'll need for DocuSign integration:

DOCUSIGN_INTEGRATION_KEY: Your app's Client ID.
DOCUSIGN_USER_ID: The API user's GUID.
DOCUSIGN_ACCOUNT_ID: Your DocuSign account ID.
DOCUSIGN_AUTH_SERVER: The OAuth URL (e.g., account-d.docusign.com for demo, account.docusign.com for live).
DOCUSIGN_API_BASE_PATH: The API base URL (e.g., https://demo.docusign.net/restapi for demo).
DOCUSIGN_PRIVATE_KEY: The RSA private key generated for your app.
DOCUSIGN_IMPERSONATED_USER_GUID: Typically the same as DOCUSIGN_USER_ID.

2. Getting Your Credentials

To obtain these, you'll need to:

Create a DocuSign developer account (if you don't have one).
Add an app in your developer account settings and generate an Integration Key (Client ID).
Create an RSA keypair for JWT authentication.
Copy your User ID and Account ID from your account settings.
Add your plugin's redirect URL to your DocuSign app settings.

3. Authenticating Using JWT

The plugin creates a signed JSON Web Token (JWT) and exchanges it for an access token with DocuSign:

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
assertion=<signed-jwt>

DocuSign then returns a bearer token, which is used for all subsequent API calls.

4. Creating and Sending the Envelope

The plugin dynamically builds a PDF envelope with both client and admin signers, then sends it via the DocuSign API:

POST /accounts/{ACCOUNT_ID}/envelopes

This API call returns an envelopeId, which is essential for tracking and managing the signing process.

5. Generating the Signing URL

For embedded signing, where the client signs within your WordPress workflow (or an iframe), you'll generate a recipient view URL:

POST /envelopes/{envelopeId}/views/recipient

DocuSign responds with a unique signing URL that you can open directly in a new window or embed.

6. Handling Completion → Starting Payment

Once the client completes signing, DocuSign redirects them back to your specified WordPress URL, typically including the envelopeId in the query parameters.

At this point, the plugin:

Retrieves any stored data associated with the envelopeId.
Calls the create_checkout_session() method from the Stripe integration.
Redirects the client directly to the Stripe Checkout page.

This ensures the client sees the payment page instantly after signing, making for a seamless transition.

7. Verifying Payment

After the client completes the payment on Stripe, you can verify its status using the Stripe API:

$session = \Stripe\Checkout\Session::retrieve($session_id);
if ($session->payment_status === 'paid') {
    // Update contract status, send confirmation emails, grant access, etc.
}

End-to-End Flow Recap

Let's quickly summarize the entire automated process for WordPress contract automation:

Admin sends contract: An action within WordPress triggers the DocuSign envelope generation.
Plugin authenticates via JWT: Securely connects to DocuSign.
DocuSign sends envelope: The client receives the contract.
Client signs: Electronically signs the document within an embedded view.
Redirects to WordPress: DocuSign hands control back to your plugin.
Stripe Checkout starts: The client is immediately taken to the payment page.
Payment verified: Upon successful payment, your system updates records and triggers post-payment actions.

This entire sequence is fully automated from start to finish.

Why This Matters

Implementing this WordPress DocuSign Stripe integration offers significant advantages:

Smooth client experience: Clients can sign and pay in one continuous, guided flow, reducing friction.
Secure handling of signatures + payments: Leverage the robust security of DocuSign and Stripe.
Clear tracking: All contract and payment data is linked, providing a transparent audit trail.
Ideal for various use cases: Perfect for agencies onboarding new clients, freelancers securing projects, or SaaS businesses automating service agreement sign-ups.

Pro Tips

When building out your integration, keep these best practices in mind:

Use DocuSign Sandbox (demo.docusign.net): Always test in the demo environment before going live.
Use Stripe Test Mode (pk_test, sk_test): Similarly, use Stripe's test keys to avoid real charges during development.
Sanitize all input: Protect your application from malicious data.
Store envelope data in transients: WordPress transients are excellent for temporary storage of envelopeId and other session-specific data.
Swap demo URLs with production URLs when going live: Ensure all API endpoints and redirect URLs point to the correct production environments.

Source Code

d5b94396feba3 / wp-docusign-stripe

WordPress DocuSign & Stripe Integration Plugin

A WordPress plugin that seamlessly integrates DocuSign electronic signatures with Stripe payment processing. This plugin automates the contract signing and payment workflow, allowing clients to sign agreements via DocuSign and immediately proceed to secure payment processing through Stripe.

Built With

This plugin is built using the WP Plugin Boilerplate - a modern, object-oriented WordPress plugin boilerplate following WordPress coding standards. The boilerplate provides a clean, maintainable structure with separation of concerns, proper security measures, and WordPress best practices.

Stripe SDK

This plugin uses the official Stripe PHP SDK for payment processing. The Stripe SDK is loaded via Composer and provides secure, reliable access to Stripe's payment processing APIs. The SDK handles all Stripe API communications, including:

Product and Price creation
Checkout Session management
Payment verification
Error handling and API response parsing

Overview

This plugin provides a complete solution for businesses that need to:

Send…

View on GitHub

d5b94396feba3 / WP-Plugin-Boilerplate

A modern, object-oriented WordPress plugin boilerplate following WordPress coding standards. Features a generic structure where you only need to change ONE FILE to create a completely new plugin.

WP Plugin Boilerplate

A modern, object-oriented WordPress plugin boilerplate following WordPress coding standards. Features a generic structure where you only need to change ONE FILE to create a completely new plugin.

🚀 Features

One-File Setup (True Dynamic Naming): Change only the main plugin file's header to rename the plugin, slug, version, menu items, and file handles across the entire codebase.

Object-Oriented Architecture: Clean, maintainable code structure.

WordPress Standards: Follows WordPress coding standards and best practices.

Security Ready: Built-in security measures and data sanitization.

Internationalization: Ready for translations with proper text domains.

Admin & Public Separation: Organized separation of backend and frontend functionality.

Hook Management: Centralized WordPress hook system.

Asset Management: Proper CSS/JS enqueuing for admin and public.

📁 Plugin Structure

my-wp-plugin/
├── 📄 my-wp-plugin.php                 # Main plugin file (ONLY FILE TO EDIT HEADER)
├── 📄 index.php
├── 📁 includes/                        # Core

…

View on GitHub

Final Thoughts

Combining DocuSign with Stripe inside your own custom WordPress plugin creates a fast, automated pipeline for contracts and payments. Clients can sign and pay in minutes, and everything stays under your control – no external SaaS required. This powerful WordPress DocuSign Stripe integration empowers you to streamline your business operations and provide a top-tier experience for your clients.

What are your thoughts on automating contract and payment workflows? Share your experiences or questions in the comments below! If you found this guide helpful, consider following me for more technical content.

🎉 Building an Interactive 3D Flipping Coin with Three.js: Complete Guide

Shahibur Rahman — Thu, 02 Oct 2025 15:54:22 +0000

In this comprehensive tutorial, we'll build an interactive 3D Flipping commemorative coin using Three.js that features smooth animations, particle effects, and engaging user interactions - all without external animation libraries.

Live Demo

🎯 What We're Building

By the end of this tutorial, you’ll have:

3D Coin with Dual Sides: Front and back faces with custom designs
Interactive Flip Animation: Smooth 180-degree flip on click -** Parallax Effects**: Mouse movement creates 3D depth illusion
Particle System: Animated particles floating around the coin
Dynamic Counting Animation: Number counter that increments automatically
Responsive Design: Works on desktop and mobile devices
Custom Shaders: GPU-accelerated particle rendering

I’ll walk you through everything step by step — HTML, CSS, JavaScript, and Three.js specifics — so you can not only replicate this but also customize it for your own ideas.

🚀 Step 1: Setting up the HTML

We start with a barebones container for the coin and a loading screen. Nothing special — just the entry point where Three.js will inject its canvas.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>3D Interactive Commemorative Coin</title>

    <!-- Three.js Core -->
    <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>

    <!-- Three.js Addons -->
    <script src="https://threejs.org/examples/js/loaders/FontLoader.js"></script>
    <script src="https://threejs.org/examples/js/geometries/TextGeometry.js"></script>

    <!-- Fonts -->
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;900&display=swap" rel="stylesheet">
</head>
<body>
    <div id="coin-container">
        <div id="canvas-container"></div>
        <div id="loading">Loading 3D Coin...</div>
    </div>

    <script src="scripts/interactive-coin.js"></script>
</body>
</html>

🎨 Step 2: Adding Styles with CSS

We’ll use CSS variables so it’s trivial to reskin the coin (gold, silver, neon, etc.) later.

:root {
    /* Color System */
    --bg-gradient-start: #173A7A;
    --coin-gradient-start: #173A7A;
    --coin-gradient-end: #66B7E1;
    --coin-edge-color: #6c7aa1;
    --text-color-light: #ffffff;
    --text-color-dark: #173A7A;

    /* Animation */
    --flip-duration: 2.8s;
    --ripple-color: rgba(56, 189, 248, 0.6);
}

* {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}

body {
    background: linear-gradient(45deg, var(--bg-gradient-start), var(--bg-gradient-end));
    font-family: 'Inter', sans-serif;
    overflow: hidden;
    display: flex;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
}

#coin-container {
    position: relative;
    width: 100vw;
    height: 100vh;
    display: flex;
    justify-content: center;
    align-items: center;
}

#canvas-container {
    width: 100vw;
    max-width: 380px;
    aspect-ratio: 1 / 1;
    cursor: pointer;
    position: relative;
}

/* Click Ripple Effect */
.click-ripple {
    position: absolute;
    width: 100px;
    height: 100px;
    border-radius: 50%;
    background: radial-gradient(circle, var(--ripple-color) 0%, transparent 70%);
    transform: translate(-50%, -50%) scale(0);
    opacity: 0;
    pointer-events: none;
    animation: ripple 0.8s forwards;
}

@keyframes ripple {
    0% {
        transform: translate(-50%, -50%) scale(0);
        opacity: 0.8;
    }
    100% {
        transform: translate(-50%, -50%) scale(4);
        opacity: 0;
    }
}

✅ Pro tip: keeping the palette in variables means you can re-theme the coin without ever touching the JS.

We also add a click ripple effect entirely in CSS — no extra GPU load, but it gives clicks/taps a nice tactile response.

🧩 Step 3: Core JavaScript Class

We wrap everything in a class InteractiveCoin. This avoids global chaos and makes the code extensible.

class InteractiveCoin {
    constructor() {
        // Three.js Core Components
        this.scene = null;
        this.camera = null;
        this.renderer = null;

        // Coin Components
        this.coin = null;
        this.edgeMesh = null;

        // Animation State
        this.isFlipping = false;
        this.isAnimating = false;
        this.targetRotationX = 0;
        this.targetRotationY = 0;

        // Particle System
        this.particles = null;
        this.particlesData = [];

        // Interactive Elements
        this.stars = [];
        this.countTextMesh = null;
        this.currentCount = 1;
        this.targetCount = 20;

        // DOM Elements
        this.container = document.getElementById('canvas-container');

        this.init();
    }
}

✅ Think of this as a mini “engine” that controls state, scene graph, and user input.

💡 Step 4: Setting up the Scene

Every Three.js project starts with scene, camera, and renderer. The difference here is in lighting — metals need multiple light passes to look convincing.

class InteractiveCoin {
    // ... constructor ...

    init() {
        this.loadAssets().then(() => {
            this.createScene();
            this.createCamera();
            this.createRenderer();
            this.createLighting();
            this.createCoin();
            this.createParticles();
            this.setupEventListeners();

            // Hide loading screen
            setTimeout(() => {
                document.getElementById('loading').style.display = 'none';
            }, 100);

            this.animate();
        });
    }

    createScene() {
        this.scene = new THREE.Scene();
        this.scene.background = null; // Transparent background
    }

    createCamera() {
        const fov = 45;
        const aspect = this.container.clientWidth / this.container.clientHeight;
        this.camera = new THREE.PerspectiveCamera(fov, aspect, 0.1, 1000);
        this.updateCameraPosition();
    }

    createRenderer() {
        this.renderer = new THREE.WebGLRenderer({ 
            antialias: true,
            alpha: true // Enable transparency
        });
        this.renderer.setSize(this.container.clientWidth, this.container.clientHeight);
        this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
        this.container.appendChild(this.renderer.domElement);
    }

    createLighting() {
        // Ambient light for overall illumination
        const ambientLight = new THREE.AmbientLight(0xffffff, 0.6);
        this.scene.add(ambientLight);

        // Directional light for shadows and highlights
        const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8);
        directionalLight.position.set(3, 3, 3);
        this.scene.add(directionalLight);

        // Fill light to reduce harsh shadows
        const fillLight = new THREE.DirectionalLight(0xffffff, 0.3);
        fillLight.position.set(-3, -3, 2);
        this.scene.add(fillLight);
    }
}

🪙 Step 5: Building the Coin

Now we get to the fun part — the coin itself. Think of it like assembling LEGO, but in 3D and with metal that actually shines.

We break the coin into three main parts:

Faces – Front and back, each with dynamic textures.
Edge – The metallic rim that makes it look real.
Decorative elements – Stars, arrows, text — all the little flourishes that make your coin pop.

createCoin() {
    const coinGroup = new THREE.Group();

    const coinRadius = 1.0;
    const coinThickness = 0.16;
    const faceZOffset = coinThickness / 2;

    // Create both faces
    this.createCoinFaceContent(coinGroup, faceZOffset, false);  // Front
    this.createCoinFaceContent(coinGroup, -faceZOffset, true);  // Back

    // Create coin edge
    this.edgeMesh = this.createCoinEdge(coinRadius, coinThickness);
    coinGroup.add(this.edgeMesh);

    this.coin = coinGroup;
    this.coin.rotation.x = Math.PI / 2; // Stand upright
    this.scene.add(this.coin);
}

The edge itself is a simple cylinder with a nice metal material. We rotate it so it wraps around the coin properly:

createCoinEdge(radius, thickness) {
    const edgeGeometry = new THREE.CylinderGeometry(radius, radius, thickness, 64, 1, true);
    const edgeMaterial = new THREE.MeshPhongMaterial({
        color: this.simpleEdgeColor,
        side: THREE.FrontSide,
        shininess: 30,
    });

    const edgeMesh = new THREE.Mesh(edgeGeometry, edgeMaterial);
    edgeMesh.rotation.x = Math.PI / 2;
    return edgeMesh;
}

✅ Pro tip: By separating faces and edges into a Group, you can rotate, flip, or animate the whole coin without worrying about individual pieces. Plus, reusing this structure makes adding particles, stars, or text a breeze.

Dynamic Face Texture Generation

createFaceTexture() {
    const canvasSize = 512;
    const canvas = document.createElement('canvas');
    canvas.width = canvasSize;
    canvas.height = canvasSize;
    const context = canvas.getContext('2d');

    // Create gradient background
    const gradient = context.createLinearGradient(0, 0, 0, canvasSize);
    gradient.addColorStop(0, this.computedStyle('--coin-gradient-start'));
    gradient.addColorStop(1, this.computedStyle('--coin-gradient-end'));
    context.fillStyle = gradient;
    context.fillRect(0, 0, canvas.width, canvas.height);

    // Add decorative elements (arrows in this case)
    this.drawArrowShape(context, canvasSize);

    return new THREE.CanvasTexture(canvas);
}

Arrow Shape Generation

drawArrowShape(context, canvasSize) {
    const s = canvasSize / 380; // Scale factor

    // Draw left arrow
    context.save();
    context.translate(46 * s, 262 * s);
    context.rotate(-18 * (Math.PI / 180));
    context.translate(-42 * s, -262 * s);

    context.beginPath();
    context.moveTo(5 * s, 229 * s);
    context.lineTo(42 * s, 271 * s);
    context.lineTo(93 * s, 252 * s);
    context.closePath();
    context.fillStyle = this.computedStyle('--text-color-dark');
    context.fill();
    context.restore();

    // Draw right arrow (mirrored)
    context.save();
    context.translate(canvasSize, 0);
    context.scale(-1, 1);
    // ... same drawing code for mirrored arrow
    context.restore();
}

✍️ Step 6: 3D Text Implementation

Two kinds of text give the coin depth:

Central text → beveled, feels engraved.
Curved text → wraps around the rim.

Both use TextGeometry and a loaded font.

createCentralText(text, x, yOffset, zOffset, color, size, fontObject) {
    if (!fontObject) {
        console.warn("Font not loaded. Skipping text creation for:", text);
        return null;
    }

    const textColor = new THREE.Color(color);
    const height = size * 0.15;
    const bevelThickness = size * 0.03;

    const textGeometry = new THREE.TextGeometry(text, {
        font: fontObject,
        size: size,
        height: height,
        curveSegments: 8,
        bevelEnabled: true,
        bevelThickness: bevelThickness,
        bevelSize: size * 0.02,
        bevelSegments: 3
    });

    // Center the geometry
    textGeometry.computeBoundingBox();
    textGeometry.center();

    const material = new THREE.MeshPhongMaterial({
        color: textColor,
        specular: 0xffffff,
        shininess: 60,
        flatShading: false
    });

    const textMesh = new THREE.Mesh(textGeometry, material);
    textMesh.position.set(x, yOffset, zOffset);

    return textMesh;
}

Curved Text Around Coin Perimeter

generateCurvedTextMesh(parentGroup, textString, radius, startAngle, endAngle, zOffset, color, fontObject, textWorldHeight) {
    if (!fontObject) return;

    const textColor = new THREE.Color(color);
    const textGroup = new THREE.Group();
    const sizeFactor = 0.25;

    let accumulatedAngle = 0;
    let lastCharHalfWidth = 0;

    for (let i = 0; i < textString.length; i++) {
        const char = textString[i];

        if (char === ' ') {
            // Handle spaces with angular spacing
            const spaceWidth = (textWorldHeight * 0.05);
            const angularChange = (lastCharHalfWidth + spaceWidth) / radius;
            accumulatedAngle += angularChange;
            lastCharHalfWidth = spaceWidth;
            continue;
        }

        const textGeometry = new THREE.TextGeometry(char, {
            font: fontObject,
            size: textWorldHeight * sizeFactor,
            height: textWorldHeight * 0.08,
            bevelEnabled: true,
            bevelThickness: textWorldHeight * 0.015,
        });

        textGeometry.computeBoundingBox();
        const charWidth = textGeometry.boundingBox.max.x - textGeometry.boundingBox.min.x;
        const charHalfWidth = charWidth / 2;

        // Calculate position along curve
        const totalWidthNeeded = (lastCharHalfWidth + charHalfWidth) * 1.2;
        const angularChange = totalWidthNeeded / radius;
        accumulatedAngle += angularChange;

        const charAngle = startAngle - accumulatedAngle;

        const material = new THREE.MeshPhongMaterial({ color: textColor });
        textGeometry.center();

        const charMesh = new THREE.Mesh(textGeometry, material);

        // Position character on circular path
        charMesh.position.x = radius * Math.cos(charAngle);
        charMesh.position.y = radius * Math.sin(charAngle);
        charMesh.rotation.z = charAngle - Math.PI / 2; // Tangent to circle

        textGroup.add(charMesh);
        lastCharHalfWidth = charHalfWidth;
    }

    parentGroup.add(textGroup);
}

✅ By computing bounding boxes + centering, you avoid awkward alignment issues.

⭐ Step 7: Extruded Stars

We generate stars with Shape + ExtrudeGeometry.
The bevel + emissive glow makes them pop when the coin rotates.

create3DStar(color, size) {
    const starShape = new THREE.Shape();
    const spikes = 5;
    const outerRadius = size * 0.5;
    const innerRadius = size * 0.2;

    // Create star points
    for (let i = 0; i < spikes * 2; i++) {
        const radius = i % 2 === 0 ? outerRadius : innerRadius;
        const angle = (i * Math.PI) / spikes - Math.PI / 2;
        const x = Math.cos(angle) * radius;
        const y = Math.sin(angle) * radius;

        if (i === 0) {
            starShape.moveTo(x, y);
        } else {
            starShape.lineTo(x, y);
        }
    }
    starShape.closePath();

    // Extrude to create 3D depth
    const extrudeDepth = size * 0.15;
    const bevelThickness = size * 0.03;

    const extrudeSettings = {
        depth: extrudeDepth,
        bevelEnabled: true,
        bevelThickness: bevelThickness,
        bevelSize: size * 0.02,
        bevelSegments: 3
    };

    const geometry = new THREE.ExtrudeGeometry(starShape, extrudeSettings);
    geometry.translate(0, 0, -extrudeDepth / 2); // Center the geometry

    const material = new THREE.MeshPhongMaterial({
        color: color,
        emissive: color,
        emissiveIntensity: 0.3,
        specular: 0xffffff,
        shininess: 60,
    });

    const starMesh = new THREE.Mesh(geometry, material);
    starMesh.userData.totalDepth = extrudeDepth + bevelThickness;

    return starMesh;
}

✅ They also serve as a subtle light indicator — showing reflections as the camera moves.

🌌 Step 8: Particle System with Shaders

Flat meshes would kill performance, so instead we go shader-based with Points.

Each particle drifts/fades based on lifetime.
Ring distribution → looks like dust/glow orbiting the coin.
Lightweight enough for mobile.

✅ Bonus: GLSL shaders let us animate thousands of points without bottlenecks.

createParticles() {
    const particleCount = 50;
    const particlesGeometry = new THREE.BufferGeometry();

    // Initialize buffers
    const positions = new Float32Array(particleCount * 3);
    const sizes = new Float32Array(particleCount);
    const colors = new Float32Array(particleCount * 3);

    for (let i = 0; i < particleCount; i++) {
        const i3 = i * 3;
        const radius = 1.1 + Math.random() * 0.2;
        const angle = Math.random() * Math.PI * 2;

        // Position particles in a ring around the coin
        positions[i3] = Math.cos(angle) * radius;
        positions[i3 + 1] = Math.sin(angle) * radius;
        positions[i3 + 2] = (Math.random() - 0.5) * 0.1;

        sizes[i] = 0.01 + Math.random() * 0.03;

        // White particles
        colors[i3] = 1.0;
        colors[i3 + 1] = 1.0;
        colors[i3 + 2] = 1.0;

        // Store particle animation data
        this.particlesData.push({
            initialX: positions[i3],
            initialY: positions[i3 + 1],
            initialZ: positions[i3 + 2],
            currentY: positions[i3 + 1],
            velocity: 0.005 + Math.random() * 0.005,
            rotationSpeed: (Math.random() - 0.5) * 0.05,
            life: Math.random() * 3,
            maxLife: 3 + Math.random() * 2
        });
    }

    // Set geometry attributes
    particlesGeometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
    particlesGeometry.setAttribute('size', new THREE.BufferAttribute(sizes, 1));
    particlesGeometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));

    // Custom shader material for particles
    const particleMaterial = new THREE.ShaderMaterial({
        uniforms: {
            pointTexture: { 
                value: new THREE.TextureLoader().load(
                    'https://threejs.org/examples/textures/sprites/disc.png'
                ) 
            }
        },
        vertexShader: `
            attribute float size;
            attribute vec3 color;
            varying vec3 vColor;

            void main() {
                vColor = color;
                vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
                gl_PointSize = size * (300.0 / -mvPosition.z);
                gl_Position = projectionMatrix * mvPosition;
            }
        `,
        fragmentShader: `
            uniform sampler2D pointTexture;
            varying vec3 vColor;

            void main() {
                gl_FragColor = vec4(vColor, vColor.r) * texture2D(pointTexture, gl_PointCoord);
            }
        `,
        transparent: true,
        blending: THREE.AdditiveBlending,
        depthWrite: false,
    });

    this.particles = new THREE.Points(particlesGeometry, particleMaterial);
    this.particles.rotation.x = Math.PI / 2;
    this.scene.add(this.particles);
}

🖱 Step 9: Interactivity

Now we make the coin come alive. This is what turns a static 3D object into something playful and tactile.

We handle:

Parallax tilt when the user moves the mouse or finger.
“Breathing” scale on hover.
180° flip on click or tap.
Click ripple — purely visual, no extra GPU stress.

setupEventListeners() {
    const canvas = this.renderer.domElement;

    // Mouse movement for parallax effect
    const onPointerMove = (event) => {
        if (this.isAnimating) return;

        const rect = canvas.getBoundingClientRect();
        let clientX, clientY;

        if (event.touches) {
            clientX = event.touches[0].clientX;
            clientY = event.touches[0].clientY;
        } else {
            clientX = event.clientX;
            clientY = event.clientY;
        }

        // Convert to normalized device coordinates (-1 to +1)
        const x = ((clientX - rect.left) / rect.width) * 2 - 1;
        const y = -((clientY - rect.top) / rect.height) * 2 + 1;

        // Update target rotation for smooth interpolation
        this.targetRotationY = x * 0.3;
        this.targetRotationX = y * 0.3;
    };

    // Hover effects
    const onPointerEnter = () => {
        if (this.isAnimating) return;
        this.targetCoinScale = 1.05;
        this.targetEmissiveIntensity = 0.5;
    };

    const onPointerLeave = () => {
        if (this.isAnimating) return;
        this.targetCoinScale = 1;
        this.targetEmissiveIntensity = 0;
        this.targetRotationX = 0;
        this.targetRotationY = 0;
    };

    // Click to flip
    const onPointerClick = (event) => {
        if (this.isAnimating) return;
        this.createClickRipple(event);
        this.flipCoin();
    };

    // Register event listeners
    canvas.addEventListener('mousemove', onPointerMove);
    canvas.addEventListener('mouseenter', onPointerEnter);
    canvas.addEventListener('mouseleave', onPointerLeave);
    canvas.addEventListener('click', onPointerClick);

    // Touch events for mobile
    canvas.addEventListener('touchmove', onPointerMove, { passive: true });
    canvas.addEventListener('touchstart', onPointerEnter, { passive: true });
    canvas.addEventListener('touchend', onPointerLeave, { passive: true });

    window.addEventListener('resize', () => this.onWindowResize());
}

Ripple Effect on Click
We make a tiny ripple where you click — no JS-heavy animation, just CSS + DOM:

createClickRipple(event) {
    const ripple = document.createElement('div');
    ripple.className = 'click-ripple';

    const rect = this.container.getBoundingClientRect();
    let clientX, clientY;

    if (event.touches) {
        clientX = event.touches[0].clientX;
        clientY = event.touches[0].clientY;
    } else {
        clientX = event.clientX;
        clientY = event.clientY;
    }

    ripple.style.left = `${clientX - rect.left}px`;
    ripple.style.top = `${clientY - rect.top}px`;

    this.container.appendChild(ripple);

    // Cleanup after animation
    setTimeout(() => {
        if (ripple.parentNode) {
            ripple.parentNode.removeChild(ripple);
        }
    }, 800);
}

Flip Animation with Easing
Clicking flips the coin 180°, with smooth cubic easing:

flipCoin() {
    if (this.isFlipping) return;

    this.isFlipping = true;
    this.isAnimating = true;

    this.flipStartTime = performance.now();
    this.flipStartRotationY = this.coin.rotation.y;
    const rotationAmount = Math.PI; // 180 degrees
    this.flipEndRotationY = this.coin.rotation.y + rotationAmount;

    // Reset visual effects during flip
    this.targetEmissiveIntensity = 0;
}

Inside the animation loop, we interpolate rotation using cubic easing:

if (this.isFlipping) {
    const elapsedTime = performance.now() - this.flipStartTime;
    const progress = Math.min(elapsedTime / this.flipDuration, 1);

    // Cubic easing function for smooth animation
    const easedProgress = progress < 0.5
        ? 4 * progress * progress * progress
        : 1 - Math.pow(-2 * progress + 2, 3) / 2;

    this.coin.rotation.y = this.flipStartRotationY + 
        (this.flipEndRotationY - this.flipStartRotationY) * easedProgress;

    if (progress >= 1) {
        this.isFlipping = false;
        this.isAnimating = false;
        this.isFlipped = !this.isFlipped;
        this.coin.rotation.y %= (Math.PI * 2); // Normalize rotation
    }
}

✅ Pro tip: Separating the animation logic (flip, scale, parallax) from input events makes the coin feel super responsive and avoids conflicts between hover and click actions.

🎞 Step 10: Animation Loop

The animate() method is the heartbeat of the coin. It handles:

Breathing scale pulses
Smooth parallax rotation
Star pulsing
Particle drift/lifecycle
Flip animation

Everything updates per frame with requestAnimationFrame, keeping GPU load minimal.

animate() {
    requestAnimationFrame(() => this.animate());

    // Breathing animation (subtle scale pulsing)
    this.breathingTimer += 0.02;
    const breathingScale = 1 + Math.sin(this.breathingTimer) * 0.03;

    if (!this.isFlipping) {
        // Smooth interpolation for hover scale
        this.currentCoinScale += (this.targetCoinScale - this.currentCoinScale) * 0.1;
        this.coin.scale.setScalar(this.currentCoinScale * breathingScale);

        // Smooth interpolation for rotation (parallax effect)
        this.coin.rotation.x += (this.targetRotationX - this.coin.rotation.x) * 0.1;
        this.coin.rotation.y += (this.targetRotationY - this.coin.rotation.y) * 0.1;
    } else {
        this.coin.scale.setScalar(breathingScale);
    }

    // Animate stars with pulsing effect
    this.animateStars();

    // Update particle system
    this.animateParticles();

    this.renderer.render(this.scene, this.camera);
}

Star Animation

Stars subtly pulse in color and glow to add realism:

animateStars() {
    const WHITE = new THREE.Color(0xFFFFFF);
    const GOLD = new THREE.Color('#ffd700');

    this.stars.forEach(starMesh => {
        if (starMesh.userData.pulseDelay > 0) {
            starMesh.userData.pulseDelay -= 0.016;
            return;
        }

        starMesh.userData.pulseTimer += 0.01;
        const pulseFactor = (Math.sin(starMesh.userData.pulseTimer) + 1) / 2;

        // Interpolate between white and gold
        starMesh.material.color.lerpColors(WHITE, GOLD, pulseFactor);
        starMesh.material.emissive.lerpColors(WHITE, GOLD, pulseFactor);
        starMesh.material.emissiveIntensity = 0.3 + pulseFactor * 0.7;
    });
}

Particle Animation

Particles float around the coin, fading in/out for a soft orbiting effect:

animateParticles() {
    if (!this.particles) return;

    const positions = this.particles.geometry.attributes.position.array;
    const colors = this.particles.geometry.attributes.color.array;

    for (let i = 0; i < this.particlesData.length; i++) {
        const p = this.particlesData[i];
        const i3 = i * 3;

        p.life += 0.016; // ~60fps

        // Reset particles that have completed their lifecycle
        if (p.life > p.maxLife) {
            p.life = 0;
            const radius = 1.1 + Math.random() * 0.2;
            const angle = Math.random() * Math.PI * 2;
            p.initialX = Math.cos(angle) * radius;
            p.initialY = Math.sin(angle) * radius;
            p.currentY = p.initialY;
        }

        // Update particle positions
        positions[i3] = p.initialX;
        p.currentY = p.initialY + (p.life / p.maxLife) * 0.3; // Rise upward
        positions[i3 + 1] = p.currentY;
        positions[i3 + 2] = p.initialZ + Math.sin(p.life * p.rotationSpeed) * 0.05;

        // Fade out based on life
        const opacity = 1 - (p.life / p.maxLife);
        colors[i3] = opacity;
        colors[i3 + 1] = opacity;
        colors[i3 + 2] = opacity;
    }

    // Mark buffers for update
    this.particles.geometry.attributes.position.needsUpdate = true;
    this.particles.geometry.attributes.color.needsUpdate = true;
}

✅ Why this setup works:

Separates logic for stars, particles, coin rotation, and scale, avoiding interference.
Smooth interpolation (lerp) for hover and parallax keeps the coin responsive.
Efficient buffer updates and requestAnimationFrame ensures high performance, even on mobile.
Centralizes all visual updates in a single loop for maintainability.

🔢 Step 11: Counting Animation

The idea:

The center text increments smoothly.
Each number is a 3D text mesh, updated dynamically.
Memory cleanup is crucial because old meshes are removed every step.

Creating the Inner Content

createInnerContent(parentGroup, isBack) {
    const innerGroup = new THREE.Group();

    // ... create inner circle and border ...

    let initialText;
    let shouldStartAnimation = false;

    if (isBack) {
        initialText = this.targetCount.toString();
    } else {
        initialText = '1';
        shouldStartAnimation = true;
    }

    const centralTextMesh = this.createCentralText(
        initialText, 0, 0.21, 0.05, 
        this.computedStyle('--text-color-dark'), 0.42, this.primary_font
    );

    if (centralTextMesh) {
        if (shouldStartAnimation) {
            this.countTextMesh = centralTextMesh;
        }
        innerGroup.add(centralTextMesh);
    }

    if (shouldStartAnimation) {
        this.startCountAnimation(innerGroup);
    }

    parentGroup.add(innerGroup);
}

✅ The isBack flag allows you to set a static number on the back face, while the front face animates.

Starting the Animation

startCountAnimation(parentGroup) {
    if (!this.primary_font) return;

    this.currentCount = 1;
    const animationDuration = 3000; // 3 seconds
    const totalIncrements = this.targetCount - this.currentCount;
    const intervalTime = animationDuration / totalIncrements;

    this.countIntervalId = setInterval(() => {
        if (this.currentCount < this.targetCount) {
            this.currentCount++;
            this.updateCountTextMesh(parentGroup);
        } else {
            clearInterval(this.countIntervalId);
        }
    }, intervalTime);
}

Computes interval time based on total increments.
Smoothly updates each number until the target is reached.

Updating the Text Mesh

updateCountTextMesh(parentGroup) {
    if (!this.countTextMesh) return;

    // Remove old text mesh
    parentGroup.remove(this.countTextMesh);
    this.countTextMesh.geometry.dispose();
    this.countTextMesh.material.dispose();

    // Create new text mesh with updated number
    const newTextMesh = this.createCentralText(
        this.currentCount.toString(), 0, 0.21, 0.05,
        this.computedStyle('--text-color-dark'), 0.42, this.primary_font
    );

    if (newTextMesh) {
        this.countTextMesh = newTextMesh;
        parentGroup.add(this.countTextMesh);
    }
}

✅ Properly disposes geometry and material to prevent memory leaks, which is essential for smooth animation.

💡 Key Points

Dynamic mesh creation allows 3D styling, bevels, and lighting on the number.
Memory management is critical — always dispose old meshes.
Works seamlessly with the flip animation from Step 9 and the animation loop from Step 10.

📱 Step 12: Responsive Design

The main goals:

Update camera aspect ratio whenever the window resizes.
Resize the renderer to match the container.
Adjust camera distance so the coin fills ~90% of the viewport without clipping.

Handling Window Resize

onWindowResize() {
    // Update camera aspect ratio
    this.camera.aspect = this.container.clientWidth / this.container.clientHeight;
    this.camera.updateProjectionMatrix();

    // Update renderer size
    this.renderer.setSize(this.container.clientWidth, this.container.clientHeight);

    // Adjust camera position for new aspect ratio
    this.updateCameraPosition();
}

clientWidth and clientHeight ensure the renderer fits the container.
updateProjectionMatrix() recalculates the camera’s perspective.
Calls updateCameraPosition() to scale the coin correctly.

Updating Camera Distance

updateCameraPosition() {
    const coinWorldDiameter = 2.0;       // Coin size in world units
    const targetCoinCoverage = 0.9;      // Fill ~90% of the viewport

    const fovRad = this.camera.fov * Math.PI / 180;

    let distance;
    if (this.camera.aspect >= 1) {
        // Landscape orientation
        distance = coinWorldDiameter / (targetCoinCoverage * 2 * Math.tan(fovRad / 2));
    } else {
        // Portrait orientation
        const hfovRad = 2 * Math.atan(Math.tan(fovRad / 2) * this.camera.aspect);
        distance = coinWorldDiameter / (targetCoinCoverage * 2 * Math.tan(hfovRad / 2));
    }

    this.camera.position.z = distance * 1.05; // Slightly further for padding
    this.camera.lookAt(0, 0, 0);              // Always center the coin
}

Calculates camera distance based on coin size and viewport.
Adjusts for landscape vs. portrait aspect ratios.
Multiplying by 1.05 gives a tiny buffer so the coin isn’t touching screen edges.

✅ Key Points

Works on all screen sizes, including mobile and tablets.
Coin scales automatically without distortion.
Keeps the camera centered and properly framed for the best visual balance.
Plays nicely with parallax, flip, and particle animations.

📱 Browser Compatibility

This implementation works in all modern browsers that support:

WebGL
ES6 Classes
CSS Variables
Promises

For older browser support, add polyfills for:

Promise
Object.assign
requestAnimationFrame

🚀 Performance Optimization Tips (Extra)

Geometry Reuse: Reuse geometries where possible
Material Sharing: Share materials between similar objects
Buffer Updates: Only update buffer attributes when necessary
Object Pooling: Reuse particle objects instead of recreating
Level of Detail: Use simpler geometries for distant objects
Texture Compression: Compress textures and use appropriate formats

🔧 Troubleshooting Common Issues (Extra)

Font Loading Problems


loadAssets() {
    return new Promise((resolve) => {
        const fontLoader = new THREE.FontLoader();

        fontLoader.load(primaryFontUrl, (font) => {
            this.primary_font = font;
            resolve();
        }, 
        undefined, 
        (error) => {
            console.warn("Primary font failed, using fallback:", error);
            // Implement fallback font loading
        });
    });
}

Memory Leaks

Always clean up when removing objects:

updateCountTextMesh(parentGroup) {
    // Proper cleanup
    parentGroup.remove(this.countTextMesh);
    this.countTextMesh.geometry.dispose();
    this.countTextMesh.material.dispose();
    this.countTextMesh = null;

    // ... create new mesh
}

Mobile Performance

createRenderer() {
    this.renderer = new THREE.WebGLRenderer({ 
        antialias: false, // Disable on mobile for performance
        alpha: true,
        powerPreference: 'high-performance'
    });

    // Limit pixel ratio on mobile
    const maxPixelRatio = window.devicePixelRatio > 1 ? 1.5 : 1;
    this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, maxPixelRatio));
}

💡 Key Takeaways

Three.js Fundamentals: Mastering scenes, cameras, renderers, and geometries
Performance Optimization: Efficient buffer management and object pooling
User Experience: Smooth animations and responsive interactions
Custom Shaders: GPU-accelerated effects for complex visuals
Cross-platform: Responsive design that works on all devices

🎯 Demo & full source

👉 Interactive demo on CodePen:
https://codepen.io/Shahibur-Rahman/pen/myVryeK

👉 Full source code on GitHub:
https://github.com/d5b94396feba3/3D-Interactive-Coin-ThreeJS

🎉 Wrapping Up

And that’s our interactive 3D flipping coin! 🪙✨

This implementation provides a solid foundation for creating interactive 3D experiences that you can adapt for various use cases like product showcases, educational tools, or interactive awards.

I’d love to see how you adapt it — if you build your own version, share it in the comments or drop a link. 🚀

Build a 3D Flipping Coin with HTML, CSS & JavaScript — deep dive

Shahibur Rahman — Mon, 29 Sep 2025 19:19:01 +0000

I built an interactive 3D coin component that flips on click, has curved SVG text and a stacked-edge illusion that gives depth. This article explains everything — the core 3D system, how the coin edge is built, SVG curved text fitting, and the click/flip timing — with clear, copy-able snippets so you (or any reader) can recreate it.

Live demo (interactive):

Project overview (what lives where)

HTML: semantic container .scene, .coin, .coin-face for front/back; SVGs for curved text; .inner-content for central circle.
CSS: CSS variables for colors and timing, perspective, transform-style: preserve-3d, backface-visibility, small animations (star pulse, ripple), responsive tweaks.
JS: helpers that:
- programmatically create the visual coin edge (buildCoinEdges),
- fit SVG curved text to the arc (fitTextToArc),
- create particles (decorative),
- handle click ripple + flip with careful timing and state control.

Minimal HTML skeleton (core structure)

<div id="scene" class="scene" role="img" aria-label="Interactive 3D Commemorative Coin">
  <div id="coin" class="coin">
    <div class="coin-face coin-front"> ... front ... </div>
    <div class="coin-face coin-back">  ... back  ... </div>
  </div>
</div>

.scene gives a local perspective (distance to the viewer).

.coin is a 3D object (children keep their 3D transforms).

.coin-face are circles, absolutely positioned, with backface-visibility: hidden so the back of each face is invisible when rotated away.

♿ Accessibility: role + aria-label

We add ARIA attributes so assistive tech treats the coin as an image-like element. That way, a screen reader won’t just read out a bunch of <div>s and <svg> paths.

<div id="scene"
     class="scene"
     role="img"
     aria-label="Interactive 3D Commemorative Coin">
  ...
</div>

role="img" tells screen readers this is a visual graphic.
aria-label gives a human-readable description.
For production, you can localize or customize this description.

Key CSS pieces — the 3D foundation

:root { --flip-duration: 2.8s; }

body { perspective: 1200px; }   /* global depth context */
.scene { perspective: 1000px; } /* local depth for coin area */

.coin {
  transform-style: preserve-3d;
  transition: transform var(--flip-duration) ease-in-out;
}
.coin.is-flipped {
  transform: rotateY(180deg) !important;
}

.coin-face {
  position: absolute;
  width: 100%;
  height: 100%;
  border-radius: 50%;
  backface-visibility: hidden;
  transform-style: preserve-3d;
}

Why these matter

perspective provides depth; lower values make the element appear more foreshortened.
transform-style: preserve-3d keeps children transformed in 3D space (instead of flattening them).
backface-visibility: hidden prevents mirrored text from showing when a face rotates away.
The .is-flipped class toggles a rotateY(180deg) on the .coin to flip it (CSS transition animates the flip).

Deep dive: core building blocks

1) 3D transform system

This tiny set of CSS + DOM rules is the backbone. Without correct perspective, transform-style, and backface-visibility, you won't get a convincing coin.

body { perspective: 1200px } — sets the viewer-camera distance; larger → weaker perspective.
.scene { perspective: 1000px } — sets perspective for the coin area specifically.
.coin performs rotations. When you rotateY(180deg) the whole coin, front/back switch.

Common gotcha: If backface-visibility is omitted, the backside of a face can be visible mirrored when rotated.

2) Coin edge illusion: buildCoinEdges() (why it matters)

A coin is thin, but visually convincing if you programmatically place many thin layers (.coin-edge) along Z. The project fakes thickness by creating many concentric rings each translated by small translateZ offsets.

Key function (full):

function buildCoinEdges(coinSelector, edgeCount = 60, step = 1.2) {
  const coinElement = document.querySelector(coinSelector);
  if (!coinElement) return;

  // remove old edges
  coinElement.querySelectorAll('.coin-edge').forEach(edge => edge.remove());

  for (let i = 0; i < edgeCount; i++) {
    const edge = document.createElement('div');
    edge.classList.add('coin-edge');

    // alternate gradient for visual texture
    if (i % 3 === 0) {
      edge.style.background = 'linear-gradient(90deg, #777 0%, #555 50%, #777 100%)';
    } else if (i % 3 === 1) {
      edge.style.background = 'linear-gradient(90deg, #666 0%, #444 50%, #666 100%)';
    } else {
      edge.style.background = 'linear-gradient(90deg, #777 0%, #555 50%, #777 100%)';
    }

    edge.style.boxShadow = 'inset 0 0 8px rgba(0,0,0,0.7)';
    edge.style.border = '1px solid #444';

    const offset = (i - edgeCount / 2) * step;
    edge.style.transform = `translateZ(${offset}px)`;

    coinElement.appendChild(edge);
  }

  // push front/back faces forward so they sit outside the edge stack
  const maxOffset = (edgeCount / 2) * step;
  const front = coinElement.querySelector('.coin-front');
  const back = coinElement.querySelector('.coin-back');

  if (front) front.style.transform = `rotateY(0deg) translateZ(${maxOffset}px)`;
  if (back) back.style.transform = `rotateY(180deg) translateZ(${maxOffset}px)`;
}

Why translateZ?

Each .coin-edge is the same size as the coin but moved slightly on Z. Stacking many creates the visual ridged edge.

Numeric example

If edgeCount = 24 and step = 1.2:

edgeCount / 2 = 24 / 2 = 12.
maxOffset = 12 * 1.2 = 14.4 (units are px in the style string). So front/back faces are translated translateZ(14.4px) to sit just outside the center of the stack.

Pitfalls

Too many edges → performance hit. Use 16–36 for a good tradeoff.
Using fractional translateZ is fine; browsers accept decimal px.

3) SVG curved text + fitTextToArc() (line-by-line)

Curved text is achieved using an SVG and . To make the text fit the curve regardless of viewport changes, compute the path length and set textLength + lengthAdjust.

Key function:

function fitTextToArc(pathElement, textPathElement){
  if (!pathElement || !textPathElement) return;
  const pathLen = pathElement.getTotalLength();
  const padding = 5; // small breathing room
  const available = pathLen + padding;
  textPathElement.setAttribute('lengthAdjust','spacingAndGlyphs');
  textPathElement.setAttribute('textLength', available.toFixed(1));
}

How it works

pathElement.getTotalLength() returns the path arc length in px.
textLength tells the browser how much space the text should occupy along the path.
lengthAdjust="spacingAndGlyphs" allows the browser to scale spacing/glyphs so the string fits visually along that length.

Do this on:

window.load (initial layout)
window.resize (when layout changes)

Pitfall: If you have duplicate SVG ids (e.g., same badgeGradient or path id on front/back), you may get unpredictable rendering. Give unique ids for each <svg> in the document.

4) Click ripple + flip: state & timing

The click handler needs to:

visually show a ripple centered on the click point,
toggle the flip class,
disable hover tilt while flip animation runs, and
re-enable it once the flip is complete.

Core snippet:

scene.addEventListener('click', function(e) {
  // create ripple
  const clickEffect = document.createElement('div');
  clickEffect.classList.add('click-effect');

  const rect = scene.getBoundingClientRect();
  const x = e.clientX - rect.left;
  const y = e.clientY - rect.top;

  clickEffect.style.left = `${x}px`;
  clickEffect.style.top = `${y}px`;

  scene.appendChild(clickEffect);
  setTimeout(() => clickEffect.style.animation = 'clickRipple 0.8s forwards', 10);
  setTimeout(() => scene.removeChild(clickEffect), 800);

  // flip logic
  const flipDuration = parseFloat(getComputedStyle(document.documentElement)
                       .getPropertyValue('--flip-duration'));
  // If --flip-duration: 2.8s => parseFloat(...) = 2.8
  // multiply by 1000 => 2800 ms

  coin.style.transform = '';          // clear any hover transform
  coin.classList.toggle('is-flipped'); // trigger flip animation

  isHovering = false;
  setTimeout(() => { isHovering = true; }, flipDuration * 1000);
});

✨ Particles (decorative extras)

Particles add subtle depth and motion. They aren’t required for the coin effect, but they enhance the polish.

function spawnParticles(container, count = 20) {
  for (let i = 0; i < count; i++) {
    const p = document.createElement('div');
    p.classList.add('particle');
    p.style.left = Math.random() * 100 + '%';
    p.style.top = Math.random() * 100 + '%';
    container.appendChild(p);

    // fade out & remove
    setTimeout(() => p.remove(), 4000 + Math.random() * 2000);
  }
}

// Example usage: run every few seconds
setInterval(() => spawnParticles(document.getElementById('scene')), 3000);

And in CSS:

.particle {
  position: absolute;
  width: 6px;
  height: 6px;
  border-radius: 50%;
  background: radial-gradient(circle, #fff 0%, transparent 70%);
  opacity: 0.7;
  animation: float 4s linear forwards;
}

@keyframes float {
  from { transform: translateY(0) scale(1); opacity: 0.7; }
  to   { transform: translateY(-60px) scale(0.4); opacity: 0; }
}

snippets & layout hints

CSS variables (control look & timing from one place)

:root {
  --flip-duration: 2.8s;
  --coin-gradient-start: #173A7A;
  --coin-gradient-end: #66B7E1;
  --ripple-color: rgba(56, 189, 248, 0.6);
}

SVG curved text (example):

<svg viewBox="0 0 380 380">
  <defs>
    <path id="circle-top-front" d="M 28,190 A 162,162 0 0,1 352,190" />
  </defs>
  <text class="curved-text-top">
    <textPath id="topTextPathFront" href="#circle-top-front" startOffset="50%">
      20 YEARS ORLANDO & SURROUNDING CITIES
    </textPath>
  </text>
</svg>

countUp (brief):

function countUp(el, target, duration) {
  const startTime = performance.now();
  function update(now) {
    const elapsed = now - startTime;
    const progress = Math.min(elapsed / duration, 1);
    const current = Math.floor(progress * target);
    el.textContent = current;
    if (progress < 1) requestAnimationFrame(update);
    else el.textContent = target;
  }
  requestAnimationFrame(update);
}

📱 Responsive tweaks

On small screens, the coin should shrink so it doesn’t overflow. A quick media query keeps it centered and contained:

    @media (max-width: 768px) {
        .scene {
            width: 85vw;
            max-width: 320px;
        }

        .curved-text-top {
            font-size: 32px !important;
            letter-spacing: 3px !important;
        }

        .curved-stars-bottom {
            font-size: 20px !important;
            letter-spacing: 6px !important;
        }

        .twenty {
            font-size: 4.5rem !important;
            margin-top: -20px !important;
            margin-bottom: -15px !important;
        }

        .years {
            font-size: 2rem !important;
            margin-bottom: -5px !important;
            margin-top: -10px !important;
        }

        .location {
            font-size: 0.9rem !important;
        }

        .inner-content-wrapper {
            width: 180px !important;
            height: 180px !important;
        }

        .inner-content {
            width: 190px !important;
            height: 190px !important;
        }

        .badge-container {
            width: 90% !important;
        }
    }

This ensures the coin scales gracefully without breaking curved text.

Demo & full source

👉 Interactive demo on CodePen:
https://codepen.io/Shahibur-Rahman/pen/zxrqpGz

👉 Full source code on GitHub:
https://github.com/d5b94396feba3/3D-Flipping-Interactive-Coin

Final thoughts

This project shows how a handful of CSS properties (perspective, transform-style, backface-visibility) plus small JS utilities (edge stacking, text fitting, hover mapping) can produce a polished interactive component.

Start with the 3D foundation (perspective + flip), add edge stacking for realism, then layer on curved text and hover/click polish.

It’s surprisingly little code for a very convincing effect.

Forem: Shahibur Rahman

Demystifying WordPress Plugin License Activation: A Step-by-Step Client-Server Guide

The Core of WordPress Plugin License Activation: Client-Server Harmony

Part 1: The Server-Side Foundation - Webhooks & Database Management

Securely Receiving Webhooks with LicenseHubWebhookReceiver

Storing License Data with LicenseHubDataManager

Part 2: The Client-Side Implementation - Activating Your WordPress Plugin

Checking License Status with PluginLicenseClient

Part 3: The Server-Side Validation API - The Heart of WordPress Plugin License Activation

Handling Validation Requests with LicenseHubAPIHandler

License and Domain Validation Logic

The Complete WordPress Plugin License Activation Flow Summarized

Key Takeaways for Robust WordPress Plugin License Activation

What are your thoughts?

Beyond Basic Chatbots: Revolutionizing WordPress with an Advanced AI Plugin for 24/7 Sales & Support

The New Era of 24/7 Customer Engagement with an AI WordPress Plugin

Building an Intelligent Knowledge Base: Smart Content Sync in Action

Empowering eCommerce: Advanced WooCommerce AI Commerce Capabilities

Global Reach and Future-Proof Flexibility with Your WordPress AI Plugin

Continuous Improvement and Actionable Insights

Getting Started: Launching Your AI Sales & Support Agent

Key Takeaways for Your Business

Transform Your WordPress Site Today

IntelliAgent AI - Turn Your WordPress Site Into a 24/7 Sales & Support PowerhouseIntelliAgent AI - AI Sales & Support Agent for WordPress & WooCommerce

Deep Dive: Ensuring WordPress Plugin Quality with Plugin Check (PCP)

Why Comprehensive WordPress Plugin Quality Checks Matter

Utilizing Plugin Check (PCP) for WordPress Plugin Quality Assurance

WP Admin User Interface

WP-CLI for Automated WordPress Plugin Checks

Understanding PCP's Issue Categories and Resolution for WordPress Plugin Quality

Internationalization Issues

Security Concerns

Performance Optimizations

Accessibility Best Practices

The Plugin Namer Tool

Key Takeaways for Enhancing WordPress Plugin Quality

Mastering WordPress Internationalization (i18n): A Beginner's Guide to Global Plugins

Why WordPress Internationalization is Crucial for Your Plugin

1. The Plugin Header: Your i18n Blueprint

2. Standard Language Folder Structure

3. Loading Translations the WordPress Standard Way

4. Translating Strings in Your Code

5. Generating the .pot File

Option A: Using WP-CLI (Recommended for Developers)

Option B: Using Poedit (GUI Tool)

Key Takeaways for WordPress Internationalization

What are your thoughts or questions on WordPress i18n? Share your experiences in the comments below!

Mastering WordPress Plugin Best Practices: Security, i18n, and Performance for Beginners

Why Robust WordPress Plugin Best Practices Matter

Internationalization (i18n): Speaking Every Language

Implementing Basic Translation

Advanced Translation with Placeholders and HTML

Pluralization for Dynamic Messages

Localizing JavaScript Strings

Security & Escaping: Protecting Against Malice

Escaping Output: Don't Trust Anything!

Sanitizing Input: Clean Data is Safe Data

Preventing XSS in JavaScript

Nonce Verification for AJAX Calls

Database Interaction & SQL Security

Prepared Queries with $wpdb->prepare()

Indexing for Performance

Existence Checks for Robustness

Accessibility & User Experience

Image Alt Tags

Localized Dates

Robustness & Error Prevention

class_exists for Sub-Models

Header Security

Key Takeaways for Mastering WordPress Plugin Best Practices

Mastering LLM Integrations in WordPress: A Plugin Boilerplate Deep Dive

d5b94396feba3 / llms-apis-wp-boilerplate-plugin

A collection of LLM (Large Language Model) API integration classes for WordPress plugins. Provides unified integration with multiple LLM providers including OpenAI, Google Gemini, and xAI Grok.

LLM APIs WordPress Plugin Component

📦 What This Is

🚀 Features

The Plugin Boilerplate Foundation for LLM Integrations

The Central Brain: AICA_Plugin_LLM_Processor

Constructor (__construct)

Getting an LLM Response (get_llm_response)

Securely Receiving Webhooks with `LicenseHubWebhookReceiver`

Storing License Data with `LicenseHubDataManager`

Checking License Status with `PluginLicenseClient`

Handling Validation Requests with `LicenseHubAPIHandler`

5. Generating the `.pot` File

Prepared Queries with `$wpdb->prepare()`

`class_exists` for Sub-Models

The Central Brain: `AICA_Plugin_LLM_Processor`

Constructor (`__construct`)

Getting an LLM Response (`get_llm_response`)

Chat Summarization (`get_chat_summary`)

Automated System Prompt Generation (`generate_automated_system_prompt`)

1. Gemini Integration (`AICA_Plugin_LLM_Gemini`)

`llm_api_v2` and `prepare_attachments`

`upload_to_gemini`

`request_gemini`

2. Grok Integration (`AICA_Plugin_LLM_Grok`)

`llm_api_v2` and `prepare_attachments`

`ensure_grok_file`

`request_grok`

3. OpenAI Integration (`AICA_Plugin_LLM_OpenAI`)

`llm_api_v2` and `prepare_attachments`

`ensure_openai_file`

`format_conversation_items`

`request_openai`

The JavaScript Engine: `syncAdminPreview()` Function for Dynamic Updates

Step 1: Gathering Your Settings with `syncAdminPreview()`

1. The Admin Controller (`class-admin.php`)

2. The Database Manager (`class-db-manager.php`)

3. The Admin User Interface (`admin-settings.php` & `knowledge-base.js`)

Deep Dive: The `AICA_Plugin_SimpleHTMLDOM` for Content Scraping

Integrating the `simple_html_dom` Library

How `scrape_page` Works

Area-Based Placement (with `grid-template-areas`)