## 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()