Segmenter
extends 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_segment_selections_order_level() : array<string|int, mixed>
- Returns column => query mapping to be used for order-related product-level segmenting query (e.g. orders_count when segmented by category).
- get_segment_selections_product_level() : array<string|int, mixed>
- Returns column => query mapping to be used for product-related product-level segmenting query (e.g. coupon discount amount for product X when segmenting by product id or category).
- 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.
- segment_selections_orders() : array<string|int, mixed>
- Returns column => query mapping to be used for order-level segmenting query (e.g. discount amount when segmented by coupons).
- 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
$all_segment_ids
Array of all segment ids.
protected
array<string|int, mixed>|bool
$all_segment_ids
= false
$query_args
Query arguments supplied by the user for data store.
protected
array<string|int, mixed>
$query_args
= ''
$report_columns
SQL definition for each column.
protected
array<string|int, mixed>
$report_columns
= array()
$segment_labels
Array of all segment labels.
protected
array<string|int, mixed>
$segment_labels
= array()
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_segment_selections_order_level()
Returns column => query mapping to be used for order-related product-level segmenting query (e.g. orders_count when segmented by category).
protected
get_segment_selections_order_level(string $coupons_lookup_table) : array<string|int, mixed>
Parameters
- $coupons_lookup_table : string
-
Name of SQL table containing the order-level segmenting info.
Return values
array<string|int, mixed> — Column => SELECT query mapping.get_segment_selections_product_level()
Returns column => query mapping to be used for product-related product-level segmenting query (e.g. coupon discount amount for product X when segmenting by product id or category).
protected
get_segment_selections_product_level(string $products_table) : array<string|int, mixed>
Parameters
- $products_table : string
-
Name of SQL table containing the product-level segmenting info.
Return values
array<string|int, mixed> — Column => SELECT query mapping.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).
Tags
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.segment_selections_orders()
Returns column => query mapping to be used for order-level segmenting query (e.g. discount amount when segmented by coupons).
protected
segment_selections_orders(string $coupons_lookup_table[, array<string|int, mixed> $overrides = array() ]) : array<string|int, mixed>
Parameters
- $coupons_lookup_table : string
-
Name of SQL table containing the order-level info.
- $overrides : array<string|int, mixed> = array()
-
Array of overrides for default column calculations.
Return values
array<string|int, mixed> — Column => SELECT query mapping.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.