Architecture Overview

A technical look at how BoxCart is structured, from the directory layout and boot sequence through to the class hierarchy, JavaScript layer, session handling, and security model.

Plugin Structure

BoxCart follows a conventional WordPress plugin layout with classes organised by responsibility into subdirectories under includes/.

boxcart/
├── boxcart.php              Main plugin file
├── includes/
│   ├── class-boxcart.php    Main plugin class
│   ├── admin/               Admin-facing classes (and admin/views/ partials)
│   ├── frontend/            Frontend-facing classes (and frontend/views/ partials)
│   ├── core/                Core business logic
│   ├── emails/              HTML + plain-text email templates
│   └── api/                 AJAX & REST API handlers
├── assets/
│   ├── css/                 Stylesheets
│   ├── js/                  JavaScript
│   └── fonts/               Self-hosted fonts
└── languages/               i18n files

Each directory has a clear purpose:

• includes/core/: Data models, database helpers, payment logic, email, CSV import/export, and other business logic that is shared between admin and frontend.
• includes/admin/: Admin screens, menus, settings, and admin-only view templates (inside admin/views/).
• includes/frontend/: Frontend shortcodes, basket, checkout, account, sidecart, and frontend view templates (inside frontend/views/).
• includes/api/: The central AJAX handler class that registers all wp_ajax_ and wp_ajax_nopriv_ actions.
• assets/: CSS, JavaScript, images, and self-hosted font files. Both source and minified (.min.js, .min.css) versions are shipped.
• includes/emails/: HTML and plain-text email templates rendered by BoxCart_Email, plus shared email-header.php and email-footer.php partials.
• languages/: Translation files (.pot).

Boot Flow

When WordPress loads the plugin, the following sequence runs inside boxcart.php and class-boxcart.php:

1. Constants defined

   BOXCART_VERSION, BOXCART_PLUGIN_FILE, BOXCART_PLUGIN_DIR, BOXCART_PLUGIN_URL, and BOXCART_PLUGIN_BASENAME are set at the top of boxcart.php.

2. Autoloader registered

   spl_autoload_register( 'boxcart_autoloader' ) is called immediately so that any BoxCart_* class can be resolved on demand.

3. Activation / deactivation hooks

   register_activation_hook triggers BoxCart_Activator::activate() which creates database tables, sets defaults, schedules cron events, and creates the boxcart_customer role. register_deactivation_hook triggers BoxCart_Deactivator::deactivate() which clears cron events.

4. plugins_loaded hook

   The boxcart() function is hooked to plugins_loaded. It creates (or returns) a singleton instance of the main BoxCart class.

5. BoxCart::__construct()

   The constructor runs the following initialisation chain:

   1. load_dependencies(): Requires all core, admin, or frontend class files.
   2. maybe_update_database(): Checks whether the DB schema needs updating.
   3. set_locale(): Hooks load_plugin_textdomain() to the init action.
   4. init_core(): Instantiates post types, taxonomies, email, webhook, and ensures the customer role exists.
   5. init_cron(): Registers cron hook callbacks.
   6. init_customer_restrictions(): Sets up admin-bar hiding and wp-admin redirect for customers.
   7. init_admin() or init_frontend(): Loads the appropriate interface classes based on is_admin(). Frontend also initialises session-based notices.
   8. init_ajax(): Instantiates BoxCart_Ajax.
   9. init_blocks(): Instantiates BoxCart_Blocks for Gutenberg block registration.

// boxcart.php - entry point
add_action( 'plugins_loaded', 'boxcart' );

function boxcart() {
    static $instance = null;
    if ( null === $instance ) {
        require_once BOXCART_PLUGIN_DIR . 'includes/class-boxcart.php';
        $instance = new BoxCart();
    }
    return $instance;
}

Autoloader

BoxCart uses a custom spl_autoload_register callback that maps every class with the BoxCart_ prefix to its corresponding file. The prefix is stripped, converted to lowercase, and underscores are replaced with hyphens to build the filename.

The autoloader searches eight directories in order (the last three exist only in the Pro build):

1. includes/
2. includes/admin/
3. includes/frontend/
4. includes/core/
5. includes/api/
6. includes/premium/core/
7. includes/premium/admin/
8. includes/premium/frontend/

function boxcart_autoloader( $class_name ) {
    // Only load classes with our prefix.
    if ( 0 !== strpos( $class_name, 'BoxCart' ) ) {
        return;
    }

    $class_name = str_replace( 'BoxCart_', '', $class_name );
    $class_name = strtolower( $class_name );
    $class_name = str_replace( '_', '-', $class_name );

    $locations = array(
        BOXCART_PLUGIN_DIR . 'includes/class-boxcart-' . $class_name . '.php',
        BOXCART_PLUGIN_DIR . 'includes/admin/class-boxcart-' . $class_name . '.php',
        BOXCART_PLUGIN_DIR . 'includes/frontend/class-boxcart-' . $class_name . '.php',
        BOXCART_PLUGIN_DIR . 'includes/core/class-boxcart-' . $class_name . '.php',
        BOXCART_PLUGIN_DIR . 'includes/api/class-boxcart-' . $class_name . '.php',
        BOXCART_PLUGIN_DIR . 'includes/premium/core/class-boxcart-' . $class_name . '.php',
        BOXCART_PLUGIN_DIR . 'includes/premium/admin/class-boxcart-' . $class_name . '.php',
        BOXCART_PLUGIN_DIR . 'includes/premium/frontend/class-boxcart-' . $class_name . '.php',
    );

    foreach ( $locations as $file ) {
        if ( file_exists( $file ) ) {
            require_once $file;
            return;
        }
    }
}
spl_autoload_register( 'boxcart_autoloader' );

Class Reference

The table below lists the major classes organised by directory. Each class follows the BoxCart_ naming convention and maps to a file via the autoloader.

Core Classes includes/core/

Admin Classes includes/admin/

Frontend Classes includes/frontend/

API Classes includes/api/

Database Tables

BoxCart creates custom database tables on activation, all prefixed with {$wpdb->prefix}boxcart_: 9 in the Free build and 12 with Pro. They fall into four groups: locations, orders, baskets, and products. See Database Schema for the full column-by-column reference.

JavaScript Architecture

BoxCart ships separate JavaScript files for each major feature area rather than a single monolithic bundle. This keeps page payloads small, only the scripts needed for the current page are enqueued.

Frontend Scripts

Admin Scripts

Data Passing

Frontend scripts receive server-side data through wp_localize_script(). The core frontend script (handle boxcart-frontend) is localised with a global JavaScript object named boxcartData containing the AJAX URL, nonce, currency and pricing settings, and translatable strings. Its keys are camelCase, for example boxcartData.ajaxUrl and boxcartData.nonce.

wp_localize_script( 'boxcart-frontend', 'boxcartData', array(
    'ajaxUrl'        => admin_url( 'admin-ajax.php' ),
    'nonce'          => wp_create_nonce( 'boxcart_ajax_nonce' ),
    'currencySymbol' => $currency_symbol,
    // ... additional settings and i18n strings
) );

Build Process

Source files are minified via npm run build using terser (JavaScript) and clean-css-cli (CSS). Both source and .min.js / .min.css files are shipped so that SCRIPT_DEBUG can toggle between them.

Session Handling

BoxCart uses its own database-backed session system rather than PHP native sessions. This avoids conflicts with object caching, load balancers, and other plugins.

When a customer has an existing basket tied to their user_id, the session ID is updated to match the current cookie. Expired baskets are cleaned up automatically by a cron job (see Cron Jobs below).

// Session initialisation (simplified)
public function init_session() {
    $this->session_id = $this->get_session_id();
}

public function get_session_id() {
    if ( ! empty( $this->session_id ) ) {
        return $this->session_id;
    }

    if ( isset( $_COOKIE[ self::COOKIE_NAME ] ) ) {
        $this->session_id = sanitize_text_field( wp_unslash( $_COOKIE[ self::COOKIE_NAME ] ) );
    } else {
        $this->session_id = wp_generate_password( 32, false );
        setcookie( self::COOKIE_NAME, $this->session_id, time() + self::COOKIE_EXPIRATION, '/' );
    }

    return $this->session_id;
}

Email Queue

BoxCart never sends emails synchronously during an HTTP request. Instead, every email is queued and dispatched in the background so that checkout and status changes remain fast.

1. Queue

   When an event fires (e.g. boxcart_order_created), BoxCart_Email schedules a single cron event via wp_schedule_single_event() and immediately calls spawn_cron() to trigger processing.

2. Process

   The boxcart_send_queued_email cron hook fires BoxCart_Email::process_queued_email(), which renders the HTML template, applies filters, and sends the email via wp_mail().

3. Templates

   HTML templates live in includes/emails/ and support placeholder tokens like {customer_name}, {order_number}, and {collection_date}. Templates include inline CSS and support admin-configurable branding (logo, colours, footer text).

Cron Jobs

BoxCart registers the following scheduled tasks through the WordPress cron system:

Cron events are registered during plugin activation by BoxCart_Activator and cleared on deactivation by BoxCart_Deactivator.

Security

BoxCart follows WordPress security best practices across all entry points.

Nonce Verification

Every AJAX request is verified with check_ajax_referer( 'boxcart_ajax_nonce', 'nonce', false ). Admin settings forms use a separate boxcart_admin_nonce. Nonces are generated via wp_create_nonce() and passed to JavaScript through wp_localize_script().

Capability Checks

Admin-only AJAX actions verify current_user_can( 'manage_options' ) before executing. Customer-only actions check that the user is logged in. The custom boxcart_customer role has only the read capability, preventing access to wp-admin screens.

Input Sanitisation

Output Escaping

All output uses esc_html(), esc_attr(), and wp_kses() as appropriate to prevent XSS.

Prepared SQL Statements

Every database query uses $wpdb->prepare() with parameterised placeholders. No raw user input is ever interpolated into SQL.

CSRF Protection

All state-changing requests (AJAX and form submissions) require a valid nonce. The Stripe webhook endpoint uses HMAC-SHA256 signature verification instead of nonces.

Rate Limiting