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
│   ├── frontend/            Frontend-facing classes
│   ├── core/                Core business logic
│   └── api/                 AJAX & REST API handlers
├── assets/
│   ├── css/                 Stylesheets
│   ├── js/                  JavaScript
│   └── fonts/               Self-hosted fonts
├── templates/               Template files
└── 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.
• templates/ — Override-able email templates.
• 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 five directories in order:

1. includes/
2. includes/admin/
3. includes/frontend/
4. includes/core/
5. includes/api/

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',
    );

    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/

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

All scripts receive server-side data through wp_localize_script(). This injects a global JavaScript object (typically boxcart_params) containing AJAX URLs, nonces, settings, and translatable strings.

wp_localize_script( 'boxcart-products', 'boxcart_params', array(
    'ajax_url' => admin_url( 'admin-ajax.php' ),
    'nonce'    => wp_create_nonce( 'boxcart_ajax_nonce' ),
    'currency' => BoxCart_Helpers::get_currency_settings(),
    // ... 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 logged-in user has an existing basket tied to their user_id, the session ID is updated to match the current cookie. For guest users, the basket row is looked up by session_id. 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