Creating A Custom Data Source

Creating a Custom Data Source

This guide walks you through creating a custom data source step-by-step. The process is simple thanks to the base class that handles all registration boilerplate.

Step 1: Create Your Class File

Create a new PHP file for your custom data source. For this example, we’ll create a file called My_Custom_Data_Source.php in your theme’s functions.php directory or your custom plugin.

<?php
/**
 * My Custom Data Source
 *
 * @package My Theme/Plugin
 * @since 1.0.0
 */
defined( 'ABSPATH' ) || exit;

class My_Custom_Data_Source extends WPD_Alpha_Insights_Data_Source_Base {

    // Step 2: Set your entity name
    protected $entity_name = 'my_custom_data';

    // Step 3: Implement fetch_data()
    public function fetch_data( $filters, $data_warehouse = null ) {
        // Your implementation here
    }

    // Step 4: Implement get_data_mapping()
    public function get_data_mapping() {
        // Your implementation here
    }
}

// Step 5: Instantiate to register
new My_Custom_Data_Source();

Step 2: Set the Entity Name

The entity name is the ONLY property you need to set. It serves as a unique identifier for your data source.

protected $entity_name = 'my_custom_data';

Requirements:

Must be unique (not used by built-in entities or other custom sources)
Should be lowercase
Use underscores instead of spaces
Should be descriptive (e.g., ‘inventory_tracking’, ‘third_party_analytics’, ‘custom_subscriptions’)

Built-in entity names to avoid:

orders, customers, products, coupons, taxes, refunds
subscriptions, expenses, store_profit
facebook_campaigns, google_campaigns, analytics

Step 3: Implement fetch_data()

The fetch_data() method is where you fetch and return your data. This method receives filters and the data warehouse instance.

public function fetch_data( $filters, $data_warehouse = null ) {
    $start_time = microtime( true );
    
    // Validate data warehouse is available
    if ( ! $data_warehouse || ! method_exists( $data_warehouse, 'get_data_by_date_range_container' ) ) {
        return array(
            'totals' => array(),
            'categorized_data' => array(),
            'data_table' => array(),
            'data_by_date' => array(),
            'total_db_records' => 0,
            'execution_time' => microtime( true ) - $start_time,
        );
    }
    
    // Get date range container for proper date alignment
    $date_range_container = $data_warehouse->get_data_by_date_range_container();
    
    // Extract date filters
    $date_from = isset( $filters['date_from'] ) ? $filters['date_from'] : date( 'Y-m-d', strtotime( '-30 days' ) );
    $date_to = isset( $filters['date_to'] ) ? $filters['date_to'] : date( 'Y-m-d' );
    
    // Fetch your data here (database queries, API calls, etc.)
    // ...
    
    // Return data structure
    return array(
        'totals' => array(
            'my_total_metric' => 1234.56,
        ),
        'data_by_date' => array(
            'my_metric_by_date' => $date_range_container, // Initialize with container
        ),
        'total_db_records' => 100,
        'execution_time' => microtime( true ) - $start_time,
    );
}

See The fetch_data() Method documentation for detailed information about parameters and return structure.

Step 4: Implement get_data_mapping()

The get_data_mapping() method defines how React displays and formats your data. This tells the frontend which metrics are available and how to display them.

public function get_data_mapping() {
    return array(
        'totals' => array(
            'label' => 'My Custom Data',
            'icon' => 'analytics',
            'totals' => array(
                'my_total_metric' => array(
                    'label' => 'My Total Metric',
                    'type' => 'currency',
                    'format' => 'currency',
                    'description' => 'Total value of my custom metric',
                ),
            ),
        ),
        'data_by_date' => array(
            'my_metric_by_date' => array(
                'label' => 'My Metric Over Time',
                'type' => 'currency',
                'format' => 'currency',
                'description' => 'My metric value over time',
                'chart_calculation' => 'sum',
            ),
        ),
    );
}

See The get_data_mapping() Method documentation for detailed structure requirements.

Step 5: Instantiate Your Class

Simply instantiate your class to register it. The base class constructor automatically handles registration via WordPress filters.

// At the end of your file, or in functions.php if you included it
new My_Custom_Data_Source();

Complete Example

Here’s a minimal working example:

<?php
/**
 * Minimal Custom Data Source Example
 */
defined( 'ABSPATH' ) || exit;

class Simple_Custom_Data_Source extends WPD_Alpha_Insights_Data_Source_Base {
    
    protected $entity_name = 'simple_custom';
    
    public function fetch_data( $filters, $data_warehouse = null ) {
        $start_time = microtime( true );
        
        if ( ! $data_warehouse ) {
            return array(
                'totals' => array(),
                'data_by_date' => array(),
                'total_db_records' => 0,
                'execution_time' => microtime( true ) - $start_time,
            );
        }
        
        $date_range_container = $data_warehouse->get_data_by_date_range_container();
        
        return array(
            'totals' => array(
                'simple_total' => 500.00,
            ),
            'data_by_date' => array(
                'simple_by_date' => $date_range_container,
            ),
            'total_db_records' => 1,
            'execution_time' => microtime( true ) - $start_time,
        );
    }
    
    public function get_data_mapping() {
        return array(
            'totals' => array(
                'label' => 'Simple Custom Data',
                'icon' => 'analytics',
                'totals' => array(
                    'simple_total' => array(
                        'label' => 'Simple Total',
                        'type' => 'currency',
                        'format' => 'currency',
                        'description' => 'A simple custom metric',
                    ),
                ),
            ),
            'data_by_date' => array(
                'simple_by_date' => array(
                    'label' => 'Simple Over Time',
                    'type' => 'currency',
                    'format' => 'currency',
                    'chart_calculation' => 'sum',
                ),
            ),
        );
    }
}

new Simple_Custom_Data_Source();

Loading Your File

If your file is not in the auto-loaded extensions folder, you need to include it. Common approaches:

Option 1: Include in functions.php

// In your theme's functions.php
require_once get_template_directory() . '/includes/my-custom-data-source.php';

Option 2: Include in a Plugin

// In your plugin's main file
require_once plugin_dir_path( __FILE__ ) . 'includes/my-custom-data-source.php';

Option 3: Use WordPress Hook

// In functions.php
add_action( 'plugins_loaded', function() {
    require_once get_template_directory() . '/includes/my-custom-data-source.php';
});

Verifying Your Data Source

After creating and loading your custom data source:

Create or edit a report in Alpha Insights
Add a widget (Metric Card, Chart, etc.)
In the widget configuration, you should see your entity name in the data source selector
Your metrics should appear in the metric selector dropdowns

Next Steps

Review The fetch_data() Method for detailed data structure requirements
Review The get_data_mapping() Method for mapping configuration details
Check out Data Warehouse API Reference for available helper methods
See Examples for real-world implementation patterns

Creating A Custom Data Source

Alpha Insights Documentation

Docs Navigation