WooCommerce Code Reference

Segmenter
in package

Date & time interval and numeric range handling class for Reporting API.

Table of Contents

$all_segment_ids  : array<string|int, mixed>|bool
Array of all segment ids.
$query_args  : array<string|int, mixed>
Query arguments supplied by the user for data store.
$report_columns  : array<string|int, mixed>
SQL definition for each column.
$segment_labels  : array<string|int, mixed>
Array of all segment labels.
__construct()  : mixed
Constructor.
add_intervals_segments()  : mixed
Adds an array of segments to data->intervals object.
get_totals_segments()  : array<string|int, mixed>
Returns an array of segments for totals part of REST response.
assign_segments_to_intervals()  : mixed
Assign segments to time intervals by updating original $intervals array.
fill_in_missing_interval_segments()  : mixed
Adds missing segments to intervals, modifies $data.
fill_in_missing_segments()  : array<string|int, mixed>
Adds zeroes for segments not present in the data selection.
get_all_segments()  : array<string|int, mixed>
Return all segment ids for given segmentby query parameter.
get_order_related_intervals_segments()  : array<string|int, mixed>
Calculate segments for intervals query where the segmenting property is bound to order (e.g. coupon or customer type).
get_order_related_segments()  : array<string|int, mixed>
Calculate segments for segmenting property bound to order (e.g. coupon or customer type).
get_order_related_totals_segments()  : array<string|int, mixed>
Calculate segments for totals query where the segmenting property is bound to order (e.g. coupon or customer type).
get_product_related_intervals_segments()  : array<string|int, mixed>
Calculate segments for intervals where the segmenting property is bound to product (e.g. category, product_id, variation_id).
get_product_related_segments()  : array<string|int, mixed>
Calculate segments for segmenting property bound to product (e.g. category, product_id, variation_id).
get_product_related_totals_segments()  : array<string|int, mixed>
Calculate segments for totals where the segmenting property is bound to product (e.g. category, product_id, variation_id).
get_segment_labels()  : array<string|int, mixed>
Return all segment labels for given segmentby query parameter.
get_segments()  : array<string|int, mixed>
Return array of segments formatted for REST response.
merge_segment_intervals_results()  : array<string|int, mixed>
Merges segmented results for intervals response part.
merge_segment_totals_results()  : array<string|int, mixed>
Merges segmented results for totals response part.
prepare_selections()  : string
Filters definitions for SELECT clauses based on query_args and joins them into one string usable in SELECT clause.
reformat_intervals_segments()  : array<string|int, mixed>
Update row-level db result for segments in 'intervals' section to the format used for output.
reformat_totals_segments()  : array<string|int, mixed>
Update row-level db result for segments in 'totals' section to the format used for output.
set_all_segments()  : void
Fetches all segment ids from db and stores it for later use.
segment_cmp()  : string
Compares two report data objects by pre-defined object property and ASC/DESC ordering.

Properties

Methods

__construct()

Constructor.

public __construct(array<string|int, mixed> $query_args, array<string|int, mixed> $report_columns) : mixed
Parameters
$query_args : array<string|int, mixed>

Query arguments supplied by the user for data store.

$report_columns : array<string|int, mixed>

Report columns lookup from data store.

Return values
mixed —

add_intervals_segments()

Adds an array of segments to data->intervals object.

public add_intervals_segments(stdClass &$data, array<string|int, mixed> $intervals_query, string $table_name) : mixed
Parameters
$data : stdClass

Data object representing the REST response.

$intervals_query : array<string|int, mixed>

Intervals SQL query parameters.

$table_name : string

Name of the SQL table that is the main order stats table.

Return values
mixed —

get_totals_segments()

Returns an array of segments for totals part of REST response.

public get_totals_segments(array<string|int, mixed> $query_params, string $table_name) : array<string|int, mixed>
Parameters
$query_params : array<string|int, mixed>

Totals SQL query parameters.

$table_name : string

Name of the SQL table that is the main order stats table.

Return values
array<string|int, mixed> —

assign_segments_to_intervals()

Assign segments to time intervals by updating original $intervals array.

protected assign_segments_to_intervals(array<string|int, mixed> &$intervals, array<string|int, mixed> $intervals_segments) : mixed
Parameters
$intervals : array<string|int, mixed>

Result array from intervals SQL query.

$intervals_segments : array<string|int, mixed>

Result array from interval segments SQL query.

Return values
mixed —

fill_in_missing_interval_segments()

Adds missing segments to intervals, modifies $data.

protected fill_in_missing_interval_segments(stdClass &$data) : mixed
Parameters
$data : stdClass

Response data.

Return values
mixed —

fill_in_missing_segments()

Adds zeroes for segments not present in the data selection.

protected fill_in_missing_segments(array<string|int, mixed> $segments) : array<string|int, mixed>
Parameters
$segments : array<string|int, mixed>

Array of segments from the database for given data points.

Return values
array<string|int, mixed> —

get_all_segments()

Return all segment ids for given segmentby query parameter.

protected get_all_segments() : array<string|int, mixed>
Return values
array<string|int, mixed> —

get_order_related_intervals_segments()

Calculate segments for intervals query where the segmenting property is bound to order (e.g. coupon or customer type).

protected get_order_related_intervals_segments(string $segmenting_select, string $segmenting_from, string $segmenting_where, string $segmenting_groupby, string $table_name, array<string|int, mixed> $intervals_query) : array<string|int, mixed>
Parameters
$segmenting_select : string

SELECT part of segmenting SQL query.

$segmenting_from : string

FROM part of segmenting SQL query.

$segmenting_where : string

WHERE part of segmenting SQL query.

$segmenting_groupby : string

GROUP BY part of segmenting SQL query.

$table_name : string

Name of SQL table which is the stats table for orders.

$intervals_query : array<string|int, mixed>

Array of SQL clauses for intervals query.

Return values
array<string|int, mixed> —

get_order_related_segments()

Calculate segments for segmenting property bound to order (e.g. coupon or customer type).

protected get_order_related_segments(string $type, string $segmenting_select, string $segmenting_from, string $segmenting_where, string $segmenting_groupby, string $table_name, array<string|int, mixed> $query_params) : array<string|int, mixed>
Parameters
$type : string

Type of segments to return--'totals' or 'intervals'.

$segmenting_select : string

SELECT part of segmenting SQL query.

$segmenting_from : string

FROM part of segmenting SQL query.

$segmenting_where : string

WHERE part of segmenting SQL query.

$segmenting_groupby : string

GROUP BY part of segmenting SQL query.

$table_name : string

Name of SQL table which is the stats table for orders.

$query_params : array<string|int, mixed>

Array of SQL clauses for intervals/totals query.

Return values
array<string|int, mixed> —

get_order_related_totals_segments()

Calculate segments for totals query where the segmenting property is bound to order (e.g. coupon or customer type).

protected get_order_related_totals_segments(string $segmenting_select, string $segmenting_from, string $segmenting_where, string $segmenting_groupby, string $table_name, array<string|int, mixed> $totals_query) : array<string|int, mixed>
Parameters
$segmenting_select : string

SELECT part of segmenting SQL query.

$segmenting_from : string

FROM part of segmenting SQL query.

$segmenting_where : string

WHERE part of segmenting SQL query.

$segmenting_groupby : string

GROUP BY part of segmenting SQL query.

$table_name : string

Name of SQL table which is the stats table for orders.

$totals_query : array<string|int, mixed>

Array of SQL clauses for intervals query.

Return values
array<string|int, mixed> —

get_product_related_intervals_segments()

Calculate segments for intervals where the segmenting property is bound to product (e.g. category, product_id, variation_id).

protected get_product_related_intervals_segments(array<string|int, mixed> $segmenting_selections, string $segmenting_from, string $segmenting_where, string $segmenting_groupby, string $segmenting_dimension_name, string $table_name, array<string|int, mixed> $intervals_query, string $unique_orders_table) : array<string|int, mixed>
Parameters
$segmenting_selections : array<string|int, mixed>

SELECT part of segmenting SQL query--one for 'product_level' and one for 'order_level'.

$segmenting_from : string

FROM part of segmenting SQL query.

$segmenting_where : string

WHERE part of segmenting SQL query.

$segmenting_groupby : string

GROUP BY part of segmenting SQL query.

$segmenting_dimension_name : string

Name of the segmenting dimension.

$table_name : string

Name of SQL table which is the stats table for orders.

$intervals_query : array<string|int, mixed>

Array of SQL clauses for intervals query.

$unique_orders_table : string

Name of temporary SQL table that holds unique orders.

Return values
array<string|int, mixed> —

get_product_related_segments()

Calculate segments for segmenting property bound to product (e.g. category, product_id, variation_id).

protected get_product_related_segments(string $type, array<string|int, mixed> $segmenting_selections, string $segmenting_from, string $segmenting_where, string $segmenting_groupby, string $segmenting_dimension_name, string $table_name, array<string|int, mixed> $query_params, string $unique_orders_table) : array<string|int, mixed>
Parameters
$type : string

Type of segments to return--'totals' or 'intervals'.

$segmenting_selections : array<string|int, mixed>

SELECT part of segmenting SQL query--one for 'product_level' and one for 'order_level'.

$segmenting_from : string

FROM part of segmenting SQL query.

$segmenting_where : string

WHERE part of segmenting SQL query.

$segmenting_groupby : string

GROUP BY part of segmenting SQL query.

$segmenting_dimension_name : string

Name of the segmenting dimension.

$table_name : string

Name of SQL table which is the stats table for orders.

$query_params : array<string|int, mixed>

Array of SQL clauses for intervals/totals query.

$unique_orders_table : string

Name of temporary SQL table that holds unique orders.

Return values
array<string|int, mixed> —

get_product_related_totals_segments()

Calculate segments for totals where the segmenting property is bound to product (e.g. category, product_id, variation_id).

protected get_product_related_totals_segments(array<string|int, mixed> $segmenting_selections, string $segmenting_from, string $segmenting_where, string $segmenting_groupby, string $segmenting_dimension_name, string $table_name, array<string|int, mixed> $totals_query, string $unique_orders_table) : array<string|int, mixed>
Parameters
$segmenting_selections : array<string|int, mixed>

SELECT part of segmenting SQL query--one for 'product_level' and one for 'order_level'.

$segmenting_from : string

FROM part of segmenting SQL query.

$segmenting_where : string

WHERE part of segmenting SQL query.

$segmenting_groupby : string

GROUP BY part of segmenting SQL query.

$segmenting_dimension_name : string

Name of the segmenting dimension.

$table_name : string

Name of SQL table which is the stats table for orders.

$totals_query : array<string|int, mixed>

Array of SQL clauses for totals query.

$unique_orders_table : string

Name of temporary SQL table that holds unique orders.

Return values
array<string|int, mixed> —

get_segment_labels()

Return all segment labels for given segmentby query parameter.

protected get_segment_labels() : array<string|int, mixed>
Return values
array<string|int, mixed> —

get_segments()

Return array of segments formatted for REST response.

protected get_segments(string $type, array<string|int, mixed> $query_params, string $table_name) : array<string|int, mixed>
Parameters
$type : string

Type of segments to return--'totals' or 'intervals'.

$query_params : array<string|int, mixed>

SQL query parameter array.

$table_name : string

Name of main SQL table for the data store (used as basis for JOINS).

Return values
array<string|int, mixed> —

merge_segment_intervals_results()

Merges segmented results for intervals response part.

protected merge_segment_intervals_results(string $segment_dimension, array<string|int, mixed> $result1, array<string|int, mixed> $result2) : array<string|int, mixed>

E.g. $r1 = array( 0 => array( 'product_id' => 3, 'time_interval' => '2018-12' 'net_amount' => 15, ), ); $r2 = array( 0 => array( 'product_id' => 3, 'time_interval' => '2018-12' 'avg_order_value' => 25, ), );

$merged = array( '2018-12' => array( 'segments' => array( 3 => array( 'segment_id' => 3, 'subtotals' => array( 'net_amount' => 15, 'avg_order_value' => 25, ), ), ), ), );

Parameters
$segment_dimension : string

Name of the segment dimension=key in the result arrays used to match records from result sets.

$result1 : array<string|int, mixed>

Array 1 of segmented figures.

$result2 : array<string|int, mixed>

Array 2 of segmented figures.

Return values
array<string|int, mixed> —

merge_segment_totals_results()

Merges segmented results for totals response part.

protected merge_segment_totals_results(string $segment_dimension, array<string|int, mixed> $result1, array<string|int, mixed> $result2) : array<string|int, mixed>

E.g. $r1 = array( 0 => array( 'product_id' => 3, 'net_amount' => 15, ), ); $r2 = array( 0 => array( 'product_id' => 3, 'avg_order_value' => 25, ), );

$merged = array( 3 => array( 'segment_id' => 3, 'subtotals' => array( 'net_amount' => 15, 'avg_order_value' => 25, ) ), );

Parameters
$segment_dimension : string

Name of the segment dimension=key in the result arrays used to match records from result sets.

$result1 : array<string|int, mixed>

Array 1 of segmented figures.

$result2 : array<string|int, mixed>

Array 2 of segmented figures.

Return values
array<string|int, mixed> —

prepare_selections()

Filters definitions for SELECT clauses based on query_args and joins them into one string usable in SELECT clause.

protected prepare_selections(array<string|int, mixed> $columns_mapping) : string
Parameters
$columns_mapping : array<string|int, mixed>

Column name -> SQL statememt mapping.

Return values
string — to be used in SELECT clause statements.

reformat_intervals_segments()

Update row-level db result for segments in 'intervals' section to the format used for output.

protected reformat_intervals_segments(array<string|int, mixed> $segments_db_result, string $segment_dimension) : array<string|int, mixed>
Parameters
$segments_db_result : array<string|int, mixed>

Results from the SQL db query for segmenting.

$segment_dimension : string

Name of column used for grouping the result.

Return values
array<string|int, mixed> — Reformatted array.

reformat_totals_segments()

Update row-level db result for segments in 'totals' section to the format used for output.

protected reformat_totals_segments(array<string|int, mixed> $segments_db_result, string $segment_dimension) : array<string|int, mixed>
Parameters
$segments_db_result : array<string|int, mixed>

Results from the SQL db query for segmenting.

$segment_dimension : string

Name of column used for grouping the result.

Return values
array<string|int, mixed> — Reformatted array.

set_all_segments()

Fetches all segment ids from db and stores it for later use.

protected set_all_segments() : void
Return values
void —

segment_cmp()

Compares two report data objects by pre-defined object property and ASC/DESC ordering.

private segment_cmp(stdClass $a, stdClass $b) : string
Parameters
$a : stdClass

Object a.

$b : stdClass

Object b.

Return values
string —