Custom Data Sources Overview

Custom Data Sources

Alpha Insights allows you to extend the reporting system with custom data sources that integrate seamlessly with the React dashboard. This powerful feature lets you add your own metrics, charts, and data tables to reports using the same infrastructure as built-in data sources like orders, products, and expenses.

Overview

Custom data sources allow you to:

Fetch data from custom database tables, external APIs, or third-party services
Display custom metrics in metric cards and metric lists
Create time-series charts from your custom data
Build categorized charts (pie, doughnut, bar) from grouped data
Display custom data in data table widgets
Leverage automatic date range alignment and filtering
Access the full data warehouse API for cross-entity data access

How It Works

The custom data source system uses a WordPress filter-based registration pattern. You create a PHP class that extends WPDAI_Custom_Data_Source_Base, set the $entity_names property (array), implement fetch_data(), and instantiate the class. The base class automatically:

Registers your data source via the wpd_alpha_insights_register_data_sources filter
Implements get_entity_name() and get_entity_names() from $entity_names (do not override)
Provides a default get_data_mapping() that returns an empty array (override only if you need React mapping)

The plugin then:

Makes your entity name(s) available in widget selectors
Fetches your data only when needed (lazy loading)
Merges your data mappings into the React frontend when you provide them
Handles date range alignment via the data warehouse

Quick Start

The minimal implementation requires:

Extend WPDAI_Custom_Data_Source_Base (not the interface directly)
Set the $entity_names property – an array of unique identifier(s). Single entity: array( 'my_entity' ). Multi-entity: array( 'orders', 'products', 'customers' ).
Implement fetch_data( WPDAI_Data_Warehouse $data_warehouse ) – single parameter; get filters via $data_warehouse->get_filter(), dates via get_date_from() / get_date_to().
Instantiate your class – e.g. new My_Custom_Data_Source(); – to register it.

Optional: Override get_data_mapping() to define how React displays your data (default is empty array; built-in entities may use core mappings).

Do not override __construct(), register_data_source(), get_entity_name(), or get_entity_names(). The base class handles registration and entity names from $entity_names.

File Location

Place your custom data source classes where they can be loaded:

Theme: Your active theme’s functions.php or a file included from it
Custom plugin: Your own plugin’s PHP files (e.g. loaded on plugins_loaded)

Ensure the Alpha Insights base class and interface are loaded before your class (they are loaded by the main plugin). If you use a very early hook, load your file after the plugin is loaded.

Data Structure

Your fetch_data() return value must match the data warehouse structure. For a single-entity source, return one structure. For a multi-entity source, return an array keyed by entity name, each value a single-entity structure. All keys are optional but must match the format if provided:

array(
    'totals'              => array(
        'metric_key' => 123.45,
    ),
    'categorized_data'    => array(
        'category_key' => array(
            'label' => 'Category Name',
            'metric_key' => 100,
        ),
    ),
    'data_table'          => array(
        'table_key' => array(
            array( 'column1' => 'value1', 'column2' => 'value2' ),
        ),
    ),
    'data_by_date'        => array(
        'metric_key' => array(
            '2024-01-01' => 50,
            '2024-01-02' => 75,
        ),
    ),
    'total_db_records'    => 100,
)
// execution_time and memory_usage are added automatically by the warehouse

Use $data_warehouse->get_data_by_date_range_container() to initialize data_by_date keys for proper date alignment.