Data Warehouse API Reference

The WPDAI_Data_Warehouse instance is passed to your fetch_data() method and provides access to helper methods and other entity data. This allows you to leverage shared functionality and access data from other sources.

Accessing the Data Warehouse

The data warehouse is the only parameter to fetch_data(). Filters (including date range) are not passed separately; use the warehouse methods to get them:

public function fetch_data( WPDAI_Data_Warehouse $data_warehouse ) {
    // Get dates and filters from the warehouse
    $date_from = $data_warehouse->get_date_from();
    $date_to = $data_warehouse->get_date_to();
    $date_container = $data_warehouse->get_data_by_date_range_container();
}

Date Range Methods

get_data_by_date_range_container()

Purpose: Get an empty array with dates as keys for the current date range. This is the most important method for proper date alignment.

Returns: Array with date keys and 0 values

Example:

$date_range_container = $data_warehouse->get_data_by_date_range_container();
// Returns: array( '2024-01-01' => 0, '2024-01-02' => 0, ... )

// Initialize your metric
$data_by_date['my_metric'] = $date_range_container;

// Then populate with your data
foreach ( array_keys( $date_range_container ) as $date_key ) {
    $data_by_date['my_metric'][ $date_key ] = /* your value */;
}

Why use this:

• Ensures all dates are present (no missing dates in charts)
• Matches date format and range used by other data sources
• Respects date grouping (day, month, quarter, year)
• Prevents chart rendering issues

get_data_by_date_containers()

Purpose: Get all date containers including metadata.

Returns: Array with date containers and metadata:

array(
    'n_days_period' => 30,
    'date_format' => 'Y-m-d',
    'date_from' => '2024-01-01',
    'date_to' => '2024-01-31',
    'date_range_container' => array( /* dates */ ),
    'calculations_by_day' => array( /* Mon-Sun */ ),
    'calculations_by_time' => array( /* 12am-11pm */ )
)

Example:

$containers = $data_warehouse->get_data_by_date_containers();
$date_format = $containers['date_format'];
$n_days = $containers['n_days_period'];

get_date_from( $format = 'Y-m-d' )

Purpose: Get the start date from the filter.

Parameters:

• $format (string): PHP date format string (default: 'Y-m-d')

Returns: String formatted date

Example:

$date_from = $data_warehouse->get_date_from(); // '2024-01-01'
$date_from_unix = $data_warehouse->get_date_from( 'U' ); // Unix timestamp

get_date_to( $format = 'Y-m-d' )

Purpose: Get the end date from the filter.

Parameters:

• $format (string): PHP date format string (default: 'Y-m-d')

Returns: String formatted date

Example:

$date_to = $data_warehouse->get_date_to(); // '2024-01-31'
$date_to_unix = $data_warehouse->get_date_to( 'U' ); // Unix timestamp

get_n_days_range()

Purpose: Calculate the number of days in the date range.

Returns: Integer number of days

Example:

$days = $data_warehouse->get_n_days_range(); // 30

Filter Methods

get_filter( $key = null, $default = null )

Purpose: Retrieve a filter value or all filters.

Parameters:

• $key (string|null): Specific filter key, or null to get all filters
• $default (mixed|null): Default value if key doesn't exist

Returns: Mixed (filter value, array of all filters, or default)

Example:

// Get specific filter
$date_format_display = $data_warehouse->get_filter( 'date_format_display', 'day' );

// Get all filters
$all_filters = $data_warehouse->get_filter();

// Get custom filter (may not exist)
$custom_filter = $data_warehouse->get_filter( 'my_custom_filter', 'default_value' );

Data Access Methods

get_data( $data_type = false, $data_key = false )

Purpose: Access data from other entities that have already been fetched.

Parameters:

• $data_type (string|false): Entity name (e.g., 'orders', 'products', 'customers')
• $data_key (string|false): Specific key within the data type (e.g., 'totals', 'data_by_date')

Returns: Array of data, or false if not found

Available entities:

• orders - WooCommerce orders data
• customers - Customer metrics
• products - Product performance
• coupons - Coupon usage
• taxes - Tax data
• refunds - Refund metrics
• subscriptions - WooCommerce Subscriptions data
• expenses - Store expenses
• store_profit - Store profit calculations
• facebook_campaigns - Facebook Ads campaign data
• google_campaigns - Google Ads campaign data
• analytics - Website analytics

Example:

// Get all orders data
$orders_data = $data_warehouse->get_data( 'orders' );

// Get orders totals only
$orders_totals = $data_warehouse->get_data( 'orders', 'totals' );

// Get orders data by date
$orders_by_date = $data_warehouse->get_data( 'orders', 'data_by_date' );

// Access specific metric
$total_revenue = $orders_totals['total_order_revenue_ex_tax'] ?? 0;

Note: Data from other entities is only available if those entities have already been fetched by the report. Check if data exists before using it:

$orders_totals = $data_warehouse->get_data( 'orders', 'totals' );
if ( $orders_totals && isset( $orders_totals['total_order_revenue_ex_tax'] ) ) {
    $revenue = $orders_totals['total_order_revenue_ex_tax'];
}

Utility Methods

get_store_currency()

Purpose: Get the store's currency code from WooCommerce settings.

Returns: String currency code (e.g., 'USD', 'GBP', 'EUR')

Example:

$currency = $data_warehouse->get_store_currency(); // 'USD'

get_data_table_limit( $entity = null )

Purpose: Get the data table limit for pagination. Useful when building data_table data.

Parameters:

• $entity (string|null): Entity name for entity-specific limits

Returns: Integer limit (default: 500)

Example:

$limit = $data_warehouse->get_data_table_limit(); // 500

// Use when querying database
global $wpdb;
$results = $wpdb->get_results( $wpdb->prepare(
    "SELECT * FROM {$wpdb->prefix}my_table LIMIT %d",
    $data_warehouse->get_data_table_limit()
) );

get_execution_time()

Purpose: Get execution time for all data fetching operations.

Returns: Array with execution time per data type and total

Example:

$execution_times = $data_warehouse->get_execution_time();
// Returns: array(
//     'orders' => 0.5,
//     'products' => 0.3,
//     'total' => 0.8
// )

get_total_db_records()

Purpose: Get total number of database records fetched across all data types.

Returns: Integer count

Example:

$total_records = $data_warehouse->get_total_db_records(); // 1500

get_errors()

Purpose: Get all errors that occurred during data fetching.

Returns: Array of error messages

Example:

$errors = $data_warehouse->get_errors();
if ( ! empty( $errors ) ) {
    // Handle errors
    foreach ( $errors as $error ) {
        error_log( 'Data warehouse error: ' . $error );
    }
}

Best Practices

1. Always Validate the Data Warehouse

if ( ! $data_warehouse || ! method_exists( $data_warehouse, 'get_data_by_date_range_container' ) ) {
    return array( /* empty structure */ );
}

2. Use Date Range Container for Time-Series Data

$date_range_container = $data_warehouse->get_data_by_date_range_container();
$data_by_date['my_metric'] = $date_range_container;
// Then populate with your data

3. Check if Other Entity Data Exists Before Using

$orders_totals = $data_warehouse->get_data( 'orders', 'totals' );
if ( $orders_totals && isset( $orders_totals['total_order_revenue_ex_tax'] ) ) {
    // Use the data
    $revenue = $orders_totals['total_order_revenue_ex_tax'];
}

4. Use Date Methods for Date Range

// Good: Use data warehouse methods
$date_from = $data_warehouse->get_date_from();
$date_to = $data_warehouse->get_date_to();
$date_format = $data_warehouse->get_filter( 'date_format_display', 'day' );

Complete Example

public function fetch_data( WPDAI_Data_Warehouse $data_warehouse ) {
    // Get date range using data warehouse methods
    $date_from = $data_warehouse->get_date_from();
    $date_to = $data_warehouse->get_date_to();
    $days_range = $data_warehouse->get_n_days_range();
    
    // Get date range container for proper alignment
    $date_range_container = $data_warehouse->get_data_by_date_range_container();
    
    // Optionally access other entity data
    $orders_totals = $data_warehouse->get_data( 'orders', 'totals' );
    $store_currency = $data_warehouse->get_store_currency();
    
    // Fetch your data...
    // ...
    
    // Build data_by_date using the container
    $data_by_date = array(
        'my_metric_by_date' => $date_range_container,
    );
    
    // Populate with your data
    foreach ( array_keys( $date_range_container ) as $date_key ) {
        $data_by_date['my_metric_by_date'][ $date_key ] = /* your value */;
    }
    
    return array(
        'totals' => array( /* ... */ ),
        'data_by_date' => $data_by_date,
        'total_db_records' => 100,
    );
}

Related Documentation

• WPDAI_Data_Warehouse Class Reference - Full class documentation (see classes folder)
• The fetch_data() Method - Using the data warehouse in fetch_data()