Theme Architecture

Pro feature

BuddyX Pro uses a modern, component-based architecture with PSR-4 autoloading for organized, maintainable code.

Overview

The theme follows object-oriented principles with a modular component system. Each feature is encapsulated in its own component that implements the Component_Interface.

Key Features:

PSR-4 autoloading with fallback
Component-based architecture
Template tag system
Namespace: BuddyxPro\BuddyxPro
Minimum requirements: WordPress 6.5+, PHP 8.0+ (BUDDYXPRO_MINIMUM_WP_VERSION / BUDDYXPRO_MINIMUM_PHP_VERSION in functions.php)

Directory Structure

buddyx-pro/
├── assets/               # CSS, JS, images, fonts
│   ├── css/
│   ├── js/
│   ├── images/
│   └── svg/
├── external/             # Optional third-party shim files (legacy, kept empty in 5.1.0+)
├── inc/                  # Theme components (PSR-4 autoloaded)
│   ├── compatibility/    # Plugin integrations
│   │   ├── buddypress/
│   │   ├── woocommerce/
│   │   ├── learndash/
│   │   ├── fluentcart/
│   │   └── ...
│   ├── Customizer/       # WP_Customize bootstrap component
│   ├── Customizer_Framework/  # First-party field API (Field, Panel, Section, Output_Builder)
│   ├── Customizer_Settings/   # Per-section field definitions
│   ├── Tokens/           # --bx-* CSS custom-property emitter
│   ├── Color_Mode_Toggle/# Dark / light toggle
│   ├── Styles/           # CSS enqueue manifest + inline CSS
│   ├── Helpers/          # Procedural helper files (Login_Forms, Dark_Mode, ...)
│   ├── widgets/          # Custom widgets
│   ├── Component_Interface.php
│   ├── Theme.php         # Main theme class
│   ├── Template_Tags.php # Template tag system
│   └── functions.php     # Entry point function
├── template-parts/       # Reusable template parts
├── vendor/               # Composer autoloader
├── functions.php         # Theme initialization
└── style.css             # Theme stylesheet

Core Architecture

Entry Point (functions.php)

// Setup autoloader (Composer or custom fallback)
if ( file_exists( get_template_directory() . '/vendor/autoload.php' ) ) {
    require get_template_directory() . '/vendor/autoload.php';
} else {
    spl_autoload_register( '_buddyxpro_autoload' );
}

// Load entry point function
require get_template_directory() . '/inc/functions.php';

// Initialize theme
call_user_func( 'BuddyxPro\BuddyxPro\buddyxpro' );

Component Interface

All theme components must implement Component_Interface:

namespace BuddyxPro\BuddyxPro;

interface Component_Interface {
    /**
     * Gets the unique identifier for the theme component.
     *
     * @return string Component slug.
     */
    public function get_slug(): string;

    /**
     * Adds the action and filter hooks to integrate with WordPress.
     */
    public function initialize();
}

Main Theme Class (Theme.php)

The Theme class orchestrates all components:

namespace BuddyxPro\BuddyxPro;

class Theme {
    protected $components = array();
    protected \BuddyxPro\BuddyxPro\Template_Tags $template_tags;

    public function __construct( array $components = array() ) {
        // Register components
        foreach ( $components as $component ) {
            $this->components[ $component->get_slug() ] = $component;
        }
    }

    public function initialize() {
        // Initialize all components
        array_walk( $this->components, function( $component ) {
            $component->initialize();
        });
    }
}

Default Components

Theme::get_default_components() (inc/Theme.php) registers these components, in this order:

Localization - Text domain and translations
Migration - Version-to-version data migrations
Base_Support - Core WordPress theme features
Editor - Block editor support
Accessibility - ARIA labels, skip links, theme-color AJAX
Image_Sizes - Custom image sizes
AMP - AMP support
PWA - Progressive Web App support
Comments - Comment markup and callbacks
Nav_Menus - Menu locations
Sidebars - Widget areas
Custom_Background - Custom background support
Custom_Header - Custom header support
Custom_Logo - Custom logo support
Post_Thumbnails - Featured image support
Customizer - WP_Customize bootstrap
Fonts - Font registration and Google Fonts
Styles - Stylesheet enqueue manifest
Scripts - JavaScript enqueue manifest
Excerpts - Excerpt handling
Options - Theme option helpers
Blocks - Gutenberg block support
Block_Patterns - Block pattern registration
Customizer_Settings - Per-section customizer field definitions
Starter_Content - Starter content
Tokens - Emits --bx-color-* / --bx-radius-* custom properties on <html> from color / dimension theme mods
Color_Mode_Toggle - Dark / light color-mode toggle
Page_Settings - Per-page settings meta box
Welcome - Theme welcome / onboarding screen
Plugin_Installer - Recommended-plugin installer

Conditional component:

// Jetpack integration (only when Jetpack is active).
if ( defined( 'JETPACK__VERSION' ) ) {
    $components[] = new Jetpack\Component();
}

Customizer_Framework is not a registered component. It is a first-party static-class library (Field, Panel, Section, Output_Builder) that replaced Kirki in 5.1.0; the Customizer_Settings component consumes it. There is no Dynamic_Style component or inc/Dynamic_Style/ directory - dynamic CSS is produced by Tokens/Component.php (custom properties), Customizer_Framework/Output_Builder.php (per-field output rules), and Styles/Component.php (inline CSS at wp_head).

Plugin integrations (BuddyPress, WooCommerce, LearnDash, Dokan, FluentCart, bbPress, BuddyNext, etc.) are not components - they are procedural files loaded conditionally from functions.php (see "Plugin Integration Pattern" below).

PSR-4 Autoloading

File-to-Class Mapping

Class namespace maps directly to file path:

Namespace: BuddyxPro\BuddyxPro\Customizer\Component
File:      inc/Customizer/Component.php

Namespace: BuddyxPro\BuddyxPro\Tokens\Component
File:      inc/Tokens/Component.php

Custom Autoloader (Fallback)

If Composer is unavailable:

function _buddyxpro_autoload( $class_name ) {
    $namespace = 'BuddyxPro\BuddyxPro';

    if ( 0 !== strpos( $class_name, $namespace . '\\' ) ) {
        return false;
    }

    // Convert namespace to file path
    $parts = explode( '\\', substr( $class_name, strlen( $namespace . '\\' ) ) );
    $path = get_template_directory() . '/inc';

    foreach ( $parts as $part ) {
        $path .= '/' . $part;
    }
    $path .= '.php';

    if ( file_exists( $path ) ) {
        require_once $path;
        return true;
    }

    return false;
}
spl_autoload_register( '_buddyxpro_autoload' );

Template Tag System

Accessing Template Tags

Template tags are accessible via the buddyxpro() function:

// In template files
buddyxpro()->display_header();
buddyxpro()->posted_on();
buddyxpro()->get_version();

Template_Tags Class

The Template_Tags class provides magic method access:

class Template_Tags {
    protected $template_tags = array();

    public function __call( string $method, array $args ) {
        if ( ! isset( $this->template_tags[ $method ] ) ) {
            throw new BadMethodCallException(
                sprintf( 'The template tag %s does not exist.', $method )
            );
        }

        return call_user_func_array(
            $this->template_tags[ $method ]['callback'],
            $args
        );
    }
}

Registering Template Tags

Components implement Templating_Component_Interface:

namespace BuddyxPro\BuddyxPro\MyComponent;

use BuddyxPro\BuddyxPro\Component_Interface;
use BuddyxPro\BuddyxPro\Templating_Component_Interface;

class Component implements Component_Interface, Templating_Component_Interface {

    public function template_tags(): array {
        return array(
            'my_custom_tag' => array( $this, 'render_custom_tag' ),
        );
    }

    public function render_custom_tag() {
        // Template tag logic
    }
}

Plugin Integration Pattern

Plugin integrations are isolated in inc/compatibility/:

Directory Structure

inc/compatibility/
├── buddypress/
│   ├── buddypress-functions.php
│   └── README.md
├── woocommerce/
│   ├── woocommerce-functions.php
│   └── README.md
├── fluentcart/
│   ├── fluentcart-functions.php
│   ├── HOOKS-REFERENCE.md
│   └── README.md
└── learndash/
    ├── learndash-functions.php
    └── README.md

Conditional Loading

In functions.php:

// Load WooCommerce functions
if ( class_exists( 'WooCommerce' ) ) {
    require get_template_directory() . '/inc/compatibility/woocommerce/woocommerce-functions.php';
}

// Load FluentCart functions
if ( defined( 'FLUENTCART_PLUGIN_FILE_PATH' ) ) {
    require get_template_directory() . '/inc/compatibility/fluentcart/fluentcart-functions.php';
}

// Load LearnDash functions
if ( class_exists( 'SFWD_LMS' ) ) {
    require get_template_directory() . '/inc/compatibility/learndash/learndash-functions.php';
}

Integration Class Pattern

class BuddyXPro_FluentCart_Support {
    private static $instance = null;

    public static function get_instance() {
        if ( null === self::$instance ) {
            self::$instance = new self();
        }
        return self::$instance;
    }

    private function __construct() {
        $this->init_hooks();
    }

    private function init_hooks() {
        // Add hooks for plugin integration
        add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_styles' ) );
        add_filter( 'body_class', array( $this, 'add_body_classes' ) );
    }
}

// Initialize
BuddyXPro_FluentCart_Support::get_instance();

Customizer Architecture

Customizer Framework (5.1.0+)

BuddyX Pro 5.1.0 replaced the external Kirki dependency with a first-party Customizer Framework that lives at inc/Customizer_Framework/. The public API matches Kirki's add_*() calls 1:1 so existing field declarations continue to work; the framework owns sanitisation, output, and the preview JS.

// No bootstrap require - the framework is autoloaded as a Component.
use BuddyxPro\BuddyxPro\Customizer_Framework\Field;

Adding Customizer Options

// Panel (registered via WP_Customize_Manager directly - the framework
// only owns sections + fields).
add_action( 'customize_register', function ( $wp_customize ) {
    $wp_customize->add_panel( 'my_panel', array(
        'title'    => __( 'My Panel', 'buddyxpro' ),
        'priority' => 10,
    ) );

    $wp_customize->add_section( 'my_section', array(
        'title' => __( 'My Section', 'buddyxpro' ),
        'panel' => 'my_panel',
    ) );
} );

// Field - framework picks the right control + sanitizer based on `type`.
\BuddyxPro\BuddyxPro\Customizer_Framework\Field::add( 'switch',
    array(
        'settings' => 'my_option',
        'label'    => __( 'Enable Feature', 'buddyxpro' ),
        'section'  => 'my_section',
        'default'  => 'off',
        'choices'  => array(
            'on'  => __( 'Yes', 'buddyxpro' ),
            'off' => __( 'No', 'buddyxpro' ),
        ),
    )
);

Supported field types

color, switch, radio_image, radio_buttonset, select, slider, dimension, typography, background, image, cropped_image, text, textarea, repeater, sortable, custom. See inc/Customizer_Framework/Field.php::$field_types for the canonical map.

Auto-resolved transport

When a field includes an output array (one or more { element, property, units } rules), the framework auto-resolves its transport to postMessage and wires customizer-preview.js to apply the new CSS rule live in the iframe. Set 'transport' => 'refresh' explicitly only when a setting genuinely needs a full reload.

Tokens system

Colour and dimension settings flow through inc/Tokens/Component.php, which writes one set of --bx-color-* / --bx-radius-* CSS custom properties on <html> plus a thin compat layer of legacy aliases (--color-theme-body, --global-border-radius, etc.). New CSS should consume the --bx-* token; aliases exist only for back-compat with pre-5.1.0 selectors. normalize_dimension() defaults bare numbers to px so customizer sliders that don't emit a unit still produce valid CSS.

Output_Builder

inc/Customizer_Framework/Output_Builder.php walks every field with an output rule and emits one combined inline CSS block at wp_head. Typography arrays expand into multi-declaration blocks; backgrounds expand into the 6-key background shorthand; scalar values use the field's _type to pick a default CSS property.

Dynamic Style Generation

Dynamic CSS in 5.1.x is produced by three cooperating pieces - there is no single "Dynamic_Style" component:

inc/Tokens/Component.php maps color / dimension theme mods onto canonical --bx-color-* and --bx-radius-* custom properties (plus legacy aliases) and prints them on <html> at wp_head. Light and dark modes emit separate token blocks.
inc/Customizer_Framework/Output_Builder.php walks every customizer field that declares an output rule and emits one combined inline CSS block.
inc/Styles/Component.php enqueues the CSS manifest and adds any remaining inline CSS (via load_custom_styles() on wp_head).

Child themes should consume the --bx-* tokens rather than regenerating CSS. See the Customization Guide.

Widget Registration

Custom Widgets

Widgets are in inc/widgets/:

// Load widgets
require get_template_directory() . '/inc/widgets/login-widget.php';
require get_template_directory() . '/inc/widgets/bp-profile-completion-widget.php';

Bundled widget classes

Class	File
`BP_BUDDYX_BP_Login_Widget`	`inc/widgets/login-widget.php`
`BP_BuddyxPro_Profile_Completion_Widget`	`inc/widgets/bp-profile-completion-widget.php`
`LD_Course_Features_Widget`	`inc/widgets/ld-featured-course-widget.php`
`BuddyxPro_WCV_Widget_Vendor_Profile`	`inc/widgets/class-vendor-profile-widget.php` (extends `WC_Widget`)

class BP_BUDDYX_BP_Login_Widget extends WP_Widget {

    public function __construct() {
        parent::__construct(
            'buddyx_login_widget',
            __( 'BuddyX Login', 'buddyxpro' ),
            array( 'description' => __( 'Login form widget', 'buddyxpro' ) )
        );
    }

    public function widget( $args, $instance ) {
        // Widget output
    }
}

// The login widget registers itself on widgets_init.
function buddyx_register_bp_login_widget() {
    register_widget( 'BP_BUDDYX_BP_Login_Widget' );
}
add_action( 'widgets_init', 'buddyx_register_bp_login_widget' );

Helper Functions

Modular Helpers (inc/Helpers/)

// Login and registration popups
require_once get_template_directory() . '/inc/Helpers/Login_Forms.php';

// BuddyPress activity enhancements
require_once get_template_directory() . '/inc/Helpers/Activity_Functions.php';

// Side panel functionality
require_once get_template_directory() . '/inc/Helpers/Side_Panel.php';

// Dark mode toggle
require_once get_template_directory() . '/inc/Helpers/Dark_Mode.php';

Utility Functions (inc/extra.php)

Core template functions:

// Content wrapper hooks
add_action( 'buddyx_before_content', 'buddyx_content_top' );
add_action( 'buddyx_after_content', 'buddyx_content_bottom' );

// Sub header
add_action( 'buddyx_sub_header', 'buddyx_sub_header' );

// Header menu-icon actions area (search / cart). This in turn fires the
// buddyx_header_actions hook - there is no buddyx_header hook.
buddyx_site_menu_icon();

Version Management

Theme Version

// Get theme version
$version = wp_get_theme( get_template() )->get( 'Version' );

// Via template tags
buddyxpro()->get_version();

Asset Versioning

// Development: file modification time
// Production: theme version
buddyxpro()->get_asset_version( $filepath );

Best Practices

Do

Use PSR-4 autoloading for new classes
Implement Component_Interface for new components
Use template tag system for reusable functions
Add plugin integrations to inc/compatibility/
Use BuddyxPro\BuddyxPro\Customizer_Framework\Field::add() for customizer options (no third-party dependency in 5.1.0+)
Prefix all functions with buddyx_ or buddyxpro_
Use namespace BuddyxPro\BuddyxPro for classes

Don't

Modify core theme files directly
Add business logic to templates
Use global variables without prefixing
Skip component initialization
Bypass the autoloader
Hardcode plugin paths

Theme Architecture

Overview

Directory Structure

Core Architecture

Entry Point (functions.php)

Component Interface

Main Theme Class (Theme.php)

Default Components

PSR-4 Autoloading

File-to-Class Mapping

Custom Autoloader (Fallback)

Template Tag System

Accessing Template Tags

Template_Tags Class

Registering Template Tags

Plugin Integration Pattern

Directory Structure

Conditional Loading

Integration Class Pattern

Customizer Architecture

Customizer Framework (5.1.0+)

Adding Customizer Options

Supported field types

Auto-resolved transport

Tokens system

Output_Builder

Dynamic Style Generation

Widget Registration

Custom Widgets

Bundled widget classes

Helper Functions

Modular Helpers (inc/Helpers/)

Utility Functions (inc/extra.php)

Version Management

Theme Version

Asset Versioning

Best Practices

Do

Don't

Related Documentation