## 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:

1. Extend `WPDAI_Custom_Data_Source_Base` (not the interface directly)
2. Set the `$entity_names` property – an array of unique identifier(s). Single entity: `array( 'my_entity' )`. Multi-entity: `array( 'orders', 'products', 'customers' )`.
3. 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()`.
4. 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.

### Related Documentation

- Creating a Custom Data Source – Step-by-step guide
- The fetch_data() Method – Parameters, return structure, and best practices
- The get_data_mapping() Method – Optional React mapping
- Data Warehouse API Reference – Helper methods (get_filter, get_date_from, get_date_to, get_data, etc.)
- Examples – Real-world implementation examples