QueryBuilder
in package
QueryBuilder class.
Responsible for constructing and modifying product queries.
Table of Contents
- $attributes_filter_query_args : array<string|int, mixed>
- All the query args related to the filter by attributes block.
- $collection_handler_store : array<string|int, mixed>
- Collection handler store.
- $custom_order_opts : array<string|int, mixed>
- Orderby options not natively supported by WordPress REST API
- $valid_query_vars : array<string|int, mixed>
- All query args from WP_Query.
- __construct() : mixed
- Constructor.
- add_price_range_filter_posts_clauses() : mixed
- Add the `posts_clauses` filter to the main query.
- add_price_sorting_posts_clauses() : array<string|int, mixed>
- Add the `posts_clauses` filter to add price-based sorting
- add_sales_sorting_posts_clauses() : array<string|int, mixed>
- Add the `posts_clauses` filter to add sales-based sorting
- get_custom_order_opts() : array<string|int, mixed>
- Get custom order options.
- get_final_frontend_query() : mixed
- Get the final query arguments for the frontend.
- get_final_query_args() : mixed
- Get final query args based on provided values
- get_preview_query_args() : mixed
- Get query args for preview mode. These query args will be used with WP_Query to fetch the products.
- get_price_range_query_args() : array<string|int, mixed>
- Get query arguments for price range filter.
- set_attributes_filter_query_args() : mixed
- Set attributes filter query args.
- set_collection_handler() : mixed
- Set collection handler.
- set_collection_handler_store() : mixed
- Set the collection handler store.
- adjust_price_filter_for_tax_class() : float
- Adjusts a price filter based on a tax class and whether or not the amount includes or excludes taxes.
- append_product_sorting_table_join() : string
- Join wc_product_meta_lookup to posts if not already joined.
- get_price_filter_query_for_displayed_taxes() : string
- Get query for price filters when dealing with displayed taxes.
- array_merge_recursive_replace_non_array_properties() : mixed
- Merge two array recursively but replace the non-array values instead of merging them. The merging strategy:
- get_custom_orderby_query() : array<string|int, mixed>
- Return query params to support custom sort values
- get_date_query() : array<string|int, mixed>
- Constructs a date query for product filtering based on a specified time frame.
- get_featured_query() : array<string|int, mixed>
- Generates a tax query to filter products based on their "featured" status.
- get_filter_by_attributes_query() : array<string|int, mixed>
- Return a query that filters products by attributes.
- get_filter_by_attributes_query_vars() : array<string|int, mixed>
- Get all the query args related to the filter by attributes block.
- get_filter_by_price_query() : array<string|int, mixed>
- Return a query that filters products by price.
- get_filter_by_rating_query() : array<string|int, mixed>
- Return a query that filters products by rating.
- get_filter_by_stock_status_query() : array<string|int, mixed>
- Return a query that filters products by stock status.
- get_filter_by_taxonomies_query() : array<string|int, mixed>
- Return a query to filter products by taxonomies (product categories, product tags, etc.)
- get_handpicked_query() : array<string|int, mixed>
- Generates a post__in query to filter products to the set of provided IDs.
- get_on_sale_products_query() : array<string|int, mixed>
- Return a query for on sale products.
- get_product_attributes_query() : array<string|int, mixed>
- Return the `tax_query` for the requested attributes
- get_product_visibility_query() : array<string|int, mixed>
- Return a query for product visibility depending on their stock status.
- get_queries_by_applied_filters() : array<string|int, mixed>
- Return queries that are generated by query args.
- get_stock_status_query() : array<string|int, mixed>
- Return a query for products depending on their stock status.
- get_valid_query_vars() : array<string|int, mixed>
- Return or initialize $valid_query_vars.
- merge_post__in() : array<string|int, int>
- Merge all of the 'post__in' values and return an array containing only values that are present in all arrays.
- merge_queries() : array<string|int, mixed>
- Merge in the first parameter the keys "post_in", "meta_query" and "tax_query" of the second parameter.
- merge_tax_queries() : array<string|int, mixed>
- Merge tax_queries from various queries.
- should_adjust_price_range_for_taxes() : bool
- Determines if price filters need adjustment based on the tax display settings.
Properties
$attributes_filter_query_args
All the query args related to the filter by attributes block.
protected
array<string|int, mixed>
$attributes_filter_query_args
= array()
$collection_handler_store
Collection handler store.
protected
array<string|int, mixed>
$collection_handler_store
= array()
$custom_order_opts
Orderby options not natively supported by WordPress REST API
protected
array<string|int, mixed>
$custom_order_opts
= array('popularity', 'rating', 'post__in', 'price', 'sales', 'menu_order', 'random')
$valid_query_vars
All query args from WP_Query.
protected
array<string|int, mixed>
$valid_query_vars
Methods
__construct()
Constructor.
public
__construct() : mixed
Return values
mixed —add_price_range_filter_posts_clauses()
Add the `posts_clauses` filter to the main query.
public
add_price_range_filter_posts_clauses(array<string|int, mixed> $clauses, WP_Query $query) : mixed
Parameters
- $clauses : array<string|int, mixed>
-
The query clauses.
- $query : WP_Query
-
The WP_Query instance.
Return values
mixed —add_price_sorting_posts_clauses()
Add the `posts_clauses` filter to add price-based sorting
public
add_price_sorting_posts_clauses(array<string|int, mixed> $clauses, WP_Query $query) : array<string|int, mixed>
Parameters
- $clauses : array<string|int, mixed>
-
The list of clauses for the query.
- $query : WP_Query
-
The WP_Query instance.
Return values
array<string|int, mixed> — Modified list of clauses.add_sales_sorting_posts_clauses()
Add the `posts_clauses` filter to add sales-based sorting
public
add_sales_sorting_posts_clauses(array<string|int, mixed> $clauses, WP_Query $query) : array<string|int, mixed>
Parameters
- $clauses : array<string|int, mixed>
-
The list of clauses for the query.
- $query : WP_Query
-
The WP_Query instance.
Return values
array<string|int, mixed> — Modified list of clauses.get_custom_order_opts()
Get custom order options.
public
get_custom_order_opts() : array<string|int, mixed>
Return values
array<string|int, mixed> —get_final_frontend_query()
Get the final query arguments for the frontend.
public
get_final_frontend_query(array<string|int, mixed> $collection_args, array<string|int, mixed> $query[, int $page = 1 ][, bool $is_exclude_applied_filters = false ]) : mixed
Parameters
- $collection_args : array<string|int, mixed>
-
Any special arguments that should change the behavior of the query.
- $query : array<string|int, mixed>
-
The query arguments.
- $page : int = 1
-
The page number.
- $is_exclude_applied_filters : bool = false
-
Whether to exclude the applied filters or not.
Return values
mixed —get_final_query_args()
Get final query args based on provided values
public
get_final_query_args(array<string|int, mixed> $collection_args, array<string|int, mixed> $common_query_values, array<string|int, mixed> $query[, bool $is_exclude_applied_filters = false ]) : mixed
Parameters
- $collection_args : array<string|int, mixed>
-
Any special arguments that should change the behavior of the query.
- $common_query_values : array<string|int, mixed>
-
Common query values.
- $query : array<string|int, mixed>
-
Query from block context.
- $is_exclude_applied_filters : bool = false
-
Whether to exclude the applied filters or not.
Return values
mixed —get_preview_query_args()
Get query args for preview mode. These query args will be used with WP_Query to fetch the products.
public
get_preview_query_args(array<string|int, mixed> $collection_args, array<string|int, mixed> $args, WP_REST_Request $request) : mixed
Parameters
- $collection_args : array<string|int, mixed>
-
Any collection-specific arguments.
- $args : array<string|int, mixed>
-
Query args.
- $request : WP_REST_Request
-
Request.
Return values
mixed —get_price_range_query_args()
Get query arguments for price range filter.
public
get_price_range_query_args(array<string|int, mixed> $price_range) : array<string|int, mixed>
We are adding these extra query arguments to be used in posts_clauses
because there are 2 special edge cases we wanna handle for Price range filter:
Case 1: Prices excluding tax are displayed including tax
Case 2: Prices including tax are displayed excluding tax
Both of these cases require us to modify SQL query to get the correct results.
See add_price_range_filter_posts_clauses function in this file for more details.
Parameters
- $price_range : array<string|int, mixed>
-
Price range with min and max values.
Return values
array<string|int, mixed> — Query arguments.set_attributes_filter_query_args()
Set attributes filter query args.
public
set_attributes_filter_query_args(array<string|int, mixed> $args) : mixed
Parameters
- $args : array<string|int, mixed>
-
The attributes filter query arguments.
Return values
mixed —set_collection_handler()
Set collection handler.
public
set_collection_handler(string $collection_name, array<string|int, mixed> $handlers) : mixed
Parameters
- $collection_name : string
-
The name of the custom collection.
- $handlers : array<string|int, mixed>
-
Collection handlers.
Return values
mixed —set_collection_handler_store()
Set the collection handler store.
public
set_collection_handler_store(array<string|int, mixed> $collection_handler_store) : mixed
Parameters
- $collection_handler_store : array<string|int, mixed>
-
The collection handler store containing registered collection handlers.
Return values
mixed —adjust_price_filter_for_tax_class()
Adjusts a price filter based on a tax class and whether or not the amount includes or excludes taxes.
protected
adjust_price_filter_for_tax_class(float $price_filter, string $tax_class) : float
This calculation logic is based on wc_get_price_excluding_tax and wc_get_price_including_tax in core.
Parameters
- $price_filter : float
-
Price filter amount as entered.
- $tax_class : string
-
Tax class for adjustment.
Return values
float —append_product_sorting_table_join()
Join wc_product_meta_lookup to posts if not already joined.
protected
append_product_sorting_table_join(string $sql) : string
Parameters
- $sql : string
-
SQL join.
Return values
string —get_price_filter_query_for_displayed_taxes()
Get query for price filters when dealing with displayed taxes.
protected
get_price_filter_query_for_displayed_taxes(float $price_filter[, string $column = 'min_price' ][, string $operator = '>=' ]) : string
Parameters
- $price_filter : float
-
Price filter to apply.
- $column : string = 'min_price'
-
Price being filtered (min or max).
- $operator : string = '>='
-
Comparison operator for column.
Return values
string — Constructed query.array_merge_recursive_replace_non_array_properties()
Merge two array recursively but replace the non-array values instead of merging them. The merging strategy:
private
array_merge_recursive_replace_non_array_properties(array<string|int, mixed> $base, array<string|int, mixed> $new_array) : mixed
-
If keys from merge array doesn't exist in the base array, create them.
-
For array items with numeric keys, we merge them as normal.
-
For array items with string keys:
-
If the value isn't array, we'll use the value coming from the merge array. $base = ['orderby' => 'date'] $new_array = ['orderby' => 'meta_value_num'] Result: ['orderby' => 'meta_value_num']
-
If the value is array, we'll use recursion to merge each key. $base = ['meta_query' => [ [ 'key' => '_stock_status', 'compare' => 'IN' 'value' => ['instock', 'onbackorder'] ] ]] $new_array = ['meta_query' => [ [ 'relation' => 'AND', [...<max_price_query>], [...<min_price_query>], ] ]] Result: ['meta_query' => [ [ 'key' => '_stock_status', 'compare' => 'IN' 'value' => ['instock', 'onbackorder'] ], [ 'relation' => 'AND', [...<max_price_query>], [...<min_price_query>], ] ]]
$base = ['post__in' => [1, 2, 3, 4, 5]] $new_array = ['post__in' => [3, 4, 5, 6, 7]] Result: ['post__in' => [1, 2, 3, 4, 5, 3, 4, 5, 6, 7]]
-
Parameters
- $base : array<string|int, mixed>
-
First array.
- $new_array : array<string|int, mixed>
-
Second array.
Return values
mixed —get_custom_orderby_query()
Return query params to support custom sort values
private
get_custom_orderby_query(string $orderby) : array<string|int, mixed>
Parameters
- $orderby : string
-
Sort order option.
Return values
array<string|int, mixed> —get_date_query()
Constructs a date query for product filtering based on a specified time frame.
private
get_date_query(array<string|int, mixed> $time_frame) : array<string|int, mixed>
Parameters
- $time_frame : array<string|int, mixed>
-
{ Associative array with 'operator' (in or not-in) and 'value' (date string).
@type string $operator Determines the inclusion or exclusion of the date range. @type string $value The date around which the range is applied.}
Return values
array<string|int, mixed> — Date query array; empty if parameters are invalid.get_featured_query()
Generates a tax query to filter products based on their "featured" status.
private
get_featured_query(bool $featured) : array<string|int, mixed>
If the $featured parameter is true, the function will return a tax query
that filters products to only those marked as featured.
If $featured is false, an empty array is returned, meaning no filtering will be applied.
Parameters
- $featured : bool
-
A flag indicating whether to filter products based on featured status.
Return values
array<string|int, mixed> — A tax query for fetching featured products if `$featured` is true; otherwise, an empty array.get_filter_by_attributes_query()
Return a query that filters products by attributes.
private
get_filter_by_attributes_query() : array<string|int, mixed>
Return values
array<string|int, mixed> —get_filter_by_attributes_query_vars()
Get all the query args related to the filter by attributes block.
private
get_filter_by_attributes_query_vars() : array<string|int, mixed>
Return values
array<string|int, mixed> — [color] => Array ( [filter] => filter_color [query_type] => query_type_color ) [size] => Array ( [filter] => filter_size [query_type] => query_type_size ) )get_filter_by_price_query()
Return a query that filters products by price.
private
get_filter_by_price_query() : array<string|int, mixed>
Return values
array<string|int, mixed> —get_filter_by_rating_query()
Return a query that filters products by rating.
private
get_filter_by_rating_query() : array<string|int, mixed>
Return values
array<string|int, mixed> —get_filter_by_stock_status_query()
Return a query that filters products by stock status.
private
get_filter_by_stock_status_query() : array<string|int, mixed>
Return values
array<string|int, mixed> —get_filter_by_taxonomies_query()
Return a query to filter products by taxonomies (product categories, product tags, etc.)
private
get_filter_by_taxonomies_query(array<string|int, mixed> $tax_query) : array<string|int, mixed>
For example: User could provide "Product Categories" using "Filters" ToolsPanel available in Inspector Controls. We use this function to extract its query from $tax_query.
For example, this is how the query for product categories will look like in $tax_query array: Array ( [taxonomy] => product_cat [terms] => Array ( [0] => 36 ) )
For product tags, taxonomy would be "product_tag"
Parameters
- $tax_query : array<string|int, mixed>
-
Query to filter products by taxonomies.
Return values
array<string|int, mixed> — Query to filter products by taxonomies.get_handpicked_query()
Generates a post__in query to filter products to the set of provided IDs.
private
get_handpicked_query(array<string|int, int>|false $handpicked_products) : array<string|int, mixed>
Parameters
- $handpicked_products : array<string|int, int>|false
-
The products to filter.
Return values
array<string|int, mixed> — The post__in query.get_on_sale_products_query()
Return a query for on sale products.
private
get_on_sale_products_query(bool $is_on_sale) : array<string|int, mixed>
Parameters
- $is_on_sale : bool
-
Whether to query for on sale products.
Return values
array<string|int, mixed> —get_product_attributes_query()
Return the `tax_query` for the requested attributes
private
get_product_attributes_query([array<string|int, mixed> $attributes = array() ]) : array<string|int, mixed>
Parameters
- $attributes : array<string|int, mixed> = array()
-
Attributes and their terms.
Return values
array<string|int, mixed> —get_product_visibility_query()
Return a query for product visibility depending on their stock status.
private
get_product_visibility_query(array<string|int, mixed> $stock_query, array<string|int, mixed> $stock_status) : array<string|int, mixed>
Parameters
- $stock_query : array<string|int, mixed>
-
Stock status query.
- $stock_status : array<string|int, mixed>
-
Selected stock status.
Return values
array<string|int, mixed> — Tax query for product visibility.get_queries_by_applied_filters()
Return queries that are generated by query args.
private
get_queries_by_applied_filters() : array<string|int, mixed>
Return values
array<string|int, mixed> —get_stock_status_query()
Return a query for products depending on their stock status.
private
get_stock_status_query(array<string|int, mixed> $stock_statuses) : array<string|int, mixed>
Parameters
- $stock_statuses : array<string|int, mixed>
-
An array of acceptable stock statuses.
Return values
array<string|int, mixed> —get_valid_query_vars()
Return or initialize $valid_query_vars.
private
get_valid_query_vars() : array<string|int, mixed>
Return values
array<string|int, mixed> —merge_post__in()
Merge all of the 'post__in' values and return an array containing only values that are present in all arrays.
private
merge_post__in(array<string|int, array<string|int, int>> ...$post__in) : array<string|int, int>
Parameters
- $post__in : array<string|int, array<string|int, int>>
-
The 'post__in' values to be merged.
Return values
array<string|int, int> — The merged 'post__in' values.merge_queries()
Merge in the first parameter the keys "post_in", "meta_query" and "tax_query" of the second parameter.
private
merge_queries(array<string|int, array<string|int, mixed>> ...$queries) : array<string|int, mixed>
Parameters
- $queries : array<string|int, array<string|int, mixed>>
-
Query arrays to be merged.
Return values
array<string|int, mixed> —merge_tax_queries()
Merge tax_queries from various queries.
private
merge_tax_queries(array<string|int, mixed> ...$queries) : array<string|int, mixed>
Parameters
- $queries : array<string|int, mixed>
-
Query arrays to be merged.
Return values
array<string|int, mixed> —should_adjust_price_range_for_taxes()
Determines if price filters need adjustment based on the tax display settings.
private
should_adjust_price_range_for_taxes() : bool
This function checks if there's a discrepancy between how prices are stored in the database and how they are displayed to the user, specifically with respect to tax inclusion or exclusion. It returns true if an adjustment is needed, indicating that the price filters should account for this discrepancy to display accurate prices.