Free_Products extends Type implements Actionable, Applicable Uses Discount_With_Required_Qty, Discount_With_Calculated_Subtotal

Free products discount type.

Give away one or more products, e.g. buy-one-get-one-free, or buy 3 for the price of 2. The cheapest qualifying product will always be used as the free product.

Tags
author

Barn2 Plugins support@barn2.com

license

GPL-3.0

copyright

Barn2 Media Ltd

Interfaces, Classes and Traits

Actionable
Interface for discount types that have cart actions.
Applicable
Indicates that a discount type needs to be verified as applicable to the cart as a whole.

Table of Contents

ORDER  = 3
$discount  : Discount
The discount object.
$processing_order  : bool
Whether the discount type is processing a WooCommerce order.
$total_discounted_products  : int
The total number of discounted products in the cart|order.
$total_order_discount  : float
The total discount that needs to be applied to the order.
cart_meets_products_selection_and_quantity()  : bool
Check whether the cart meets the minimum required quantity for the discount to apply.
decrease_total_discounted_products()  : self
Decrease the total number of discounted products in the cart|order.
decrease_total_order_discount()  : self
Decrease the total discount that needs to be applied to the order.
generate_virtual_coupon_for_order()  : void
Generate a virtual coupon for the order.
get_application_method()  : string
Get the application method for the discount.
get_cart_quantity_of_relevant_products()  : int
Return the total quantity of relevant products in the cart.
get_default_settings_values()  : array<string|int, mixed>
Get the default settings values for this discount type.
get_discount()  : Discount
Get the discount object.
get_elegible_products()  : array<string|int, mixed>
Get the products elegible for the discount.
get_free_qty()  : int
Retrieve the minimum required quantity for the discount to apply.
get_min_required_qty()  : int
Retrieve the minimum required quantity for the discount to apply.
get_name()  : string
Get the name for this discount type.
get_order_quantity_of_relevant_products()  : int
Return the total quantity of relevant products in the order.
get_settings()  : array<string|int, mixed>
Get the settings for this discount type.
get_slug()  : string
Get the slug for this discount type.
get_tooltip()  : string
Get the tooltip for this discount type.
get_total_discounted_products()  : int
Return the total number of discounted products in the cart|order.
get_total_order_discount()  : float
Return the total discount that needs to be applied to the order.
increase_total_discounted_products()  : self
Increase the total number of discounted products in the cart|order.
increase_total_order_discount()  : self
Increase the total discount that needs to be applied to the order.
is_applicable_to_cart()  : bool
Determine if the discount is applicable to the cart as a whole.
is_applicable_to_order()  : bool
Determine if the discount is applicable to the order as a whole.
is_based_on_cart_quantity()  : bool
Determine whether the discount should be calculated based on the cart quantity.
is_based_on_line_item_quantity()  : bool
Determine whether the discount should be calculated based on the line item quantity.
is_processing_order()  : bool
Return whether the discount type is being applied to a WooCommerce order.
make()  : static
Make a new discount type.
order_meets_products_selection_and_quantity()  : bool
Check whether the order meets the minimum required quantity for the discount to apply.
reset_total_discounted_products()  : self
Reset the total number of discounted products in the cart|order.
reset_total_order_discount()  : self
Reset the total discount that needs to be applied to the order.
run_cart_actions()  : void
Run the cart actions for the discount type.
run_order_actions()  : void
Run the order actions for the discount type.
set_discount()  : self
Set the discount object.
set_proccesing_order()  : self
Flag whether the discount type is being applied to a WooCommerce order.
set_total_discounted_products()  : self
Set the total number of discounted products in the cart|order.
set_total_order_discount()  : self
Set the total discount that needs to be applied to the order.
calculate_number_of_items_to_buy_with_discount()  : int
Calculate the number of items to buy with discount for a given total quantity based on the number of items needed for one discount loop.
cart_has_product_with_required_qty()  : bool
Check if the cart has a product with the required quantity.
discount_cheapest_in_cart_order()  : void
Discount the products based on the subtotal of the relevant products.
discount_products_cart_basis()  : void
Discount the additional products based on the cart quantity.
discount_products_line_item_basis()  : void
Discount the products based on the line item quantity.
get_cart_subtotal()  : float
Get the appropriate subtotal used to determine the dynamic discount amount generated by the fixed price.
get_order_subtotal()  : float
Get the appropriate subtotal used to determine the dynamic discount amount generated by the fixed price.
order_has_product_with_required_qty()  : bool
Check if the order has a product with the required quantity.

Constants

Properties

$processing_order

Whether the discount type is processing a WooCommerce order.

protected bool $processing_order = false

This is used so that we prevent applying discounts at a order line level due to the multitude of issues in how taxes are calculated in WooCommerce.

$total_discounted_products

The total number of discounted products in the cart|order.

protected int $total_discounted_products = 0

This is used to track the number of discounted products in the cart|order but not all types will use this.

Not all discount types need to track the number of discounted products.

$total_order_discount

The total discount that needs to be applied to the order.

protected float $total_order_discount = 0

Methods

cart_meets_products_selection_and_quantity()

Check whether the cart meets the minimum required quantity for the discount to apply.

public cart_meets_products_selection_and_quantity(WC_Cart $cart, Discount $discount) : bool
  • If the discount is applicable to all products, the cart must contain the minimum required quantity of any product.
  • If the discount is applicable to specific products, the cart must contain the minimum required quantity of any of the selected products.
  • If the discount is applicable to specific categories, the cart must contain the minimum required quantity of any product in the selected categories.
Parameters
$cart : WC_Cart
$discount : Discount
Return values
bool —

decrease_total_discounted_products()

Decrease the total number of discounted products in the cart|order.

public decrease_total_discounted_products(int $amount) : self
Parameters
$amount : int

The amount to decrease the total number of discounted products by.

Return values
self —

The discount type.

decrease_total_order_discount()

Decrease the total discount that needs to be applied to the order.

public decrease_total_order_discount(float $amount) : self
Parameters
$amount : float

The amount to decrease the total discount by.

Return values
self —

The discount type.

generate_virtual_coupon_for_order()

Generate a virtual coupon for the order.

public generate_virtual_coupon_for_order(WC_Order $order) : void

This is used to apply the discount to the order and is not a real coupon.

This is mainly used during the creating of manual orders.

Parameters
$order : WC_Order

The order object.

Return values
void —

get_application_method()

Get the application method for the discount.

public get_application_method() : string
Return values
string —

The application method.

get_cart_quantity_of_relevant_products()

Return the total quantity of relevant products in the cart.

public get_cart_quantity_of_relevant_products(WC_Cart $cart) : int
Parameters
$cart : WC_Cart

The cart object.

Return values
int —

get_default_settings_values()

Get the default settings values for this discount type.

public static get_default_settings_values() : array<string|int, mixed>
Tags
inheritdoc
Return values
array<string|int, mixed> —

get_elegible_products()

Get the products elegible for the discount.

public get_elegible_products(array<string|int, mixed> $products[, bool $is_order = false ]) : array<string|int, mixed>

These are line items that have a quantity of $total_qty or higher.

Parameters
$products : array<string|int, mixed>

The products.

$is_order : bool = false

Whether the products are order items.

Return values
array<string|int, mixed> —

The elegible products.

get_free_qty()

Retrieve the minimum required quantity for the discount to apply.

public get_free_qty() : int
Return values
int —

get_min_required_qty()

Retrieve the minimum required quantity for the discount to apply.

public get_min_required_qty() : int
Return values
int —

get_name()

Get the name for this discount type.

public static get_name() : string
Tags
inheritdoc
Return values
string —

get_order_quantity_of_relevant_products()

Return the total quantity of relevant products in the order.

public get_order_quantity_of_relevant_products(WC_Order $order) : int
Parameters
$order : WC_Order

The order object.

Return values
int —

get_settings()

Get the settings for this discount type.

public static get_settings() : array<string|int, mixed>
Tags
inheritdoc
Return values
array<string|int, mixed> —

get_slug()

Get the slug for this discount type.

public static get_slug() : string
Tags
inheritdoc
Return values
string —

get_tooltip()

Get the tooltip for this discount type.

public static get_tooltip() : string
Tags
inheritdoc
Return values
string —

get_total_discounted_products()

Return the total number of discounted products in the cart|order.

public get_total_discounted_products() : int
Return values
int —

get_total_order_discount()

Return the total discount that needs to be applied to the order.

public get_total_order_discount() : float
Return values
float —

increase_total_discounted_products()

Increase the total number of discounted products in the cart|order.

public increase_total_discounted_products(int $amount) : self
Parameters
$amount : int

The amount to increase the total number of discounted products by.

Return values
self —

The discount type.

increase_total_order_discount()

Increase the total discount that needs to be applied to the order.

public increase_total_order_discount(float $amount) : self
Parameters
$amount : float

The amount to increase the total discount by.

Return values
self —

The discount type.

is_applicable_to_cart()

Determine if the discount is applicable to the cart as a whole.

public is_applicable_to_cart(WC_Cart $cart) : bool
Parameters
$cart : WC_Cart

The cart object.

Tags
inheritdoc
Return values
bool —

True if the discount is applicable to the cart as a whole.

is_applicable_to_order()

Determine if the discount is applicable to the order as a whole.

public is_applicable_to_order(WC_Order $order) : bool
Parameters
$order : WC_Order

The order object.

Tags
inheritdoc
Return values
bool —

True if the discount is applicable to the order as a whole.

is_based_on_cart_quantity()

Determine whether the discount should be calculated based on the cart quantity.

public is_based_on_cart_quantity() : bool
Return values
bool —

is_based_on_line_item_quantity()

Determine whether the discount should be calculated based on the line item quantity.

public is_based_on_line_item_quantity() : bool
Return values
bool —

is_processing_order()

Return whether the discount type is being applied to a WooCommerce order.

public is_processing_order() : bool
Return values
bool —

make()

Make a new discount type.

public static make(Discount $discount) : static
Parameters
$discount : Discount

The discount object.

Return values
static —

The new discount type.

order_meets_products_selection_and_quantity()

Check whether the order meets the minimum required quantity for the discount to apply.

public order_meets_products_selection_and_quantity(WC_Order $order, Discount $discount) : bool
  • If the discount is applicable to all products, the order must contain the minimum required quantity of any product.
  • If the discount is applicable to specific products, the order must contain the minimum required quantity of any of the selected products.
  • If the discount is applicable to specific categories, the order must contain the minimum required quantity of any product in the selected categories.
Parameters
$order : WC_Order
$discount : Discount
Return values
bool —

reset_total_discounted_products()

Reset the total number of discounted products in the cart|order.

public reset_total_discounted_products() : self
Return values
self —

The discount type.

reset_total_order_discount()

Reset the total discount that needs to be applied to the order.

public reset_total_order_discount() : self
Return values
self —

The discount type.

run_cart_actions()

Run the cart actions for the discount type.

public run_cart_actions(WC_Cart &$cart) : void
Parameters
$cart : WC_Cart
Tags
inheritdoc
Return values
void —

run_order_actions()

Run the order actions for the discount type.

public run_order_actions(WC_Order &$order) : void
Parameters
$order : WC_Order
Tags
inheritdoc
Return values
void —

set_discount()

Set the discount object.

public set_discount(Discount $discount) : self
Parameters
$discount : Discount

The discount object.

Return values
self —

set_proccesing_order()

Flag whether the discount type is being applied to a WooCommerce order.

public set_proccesing_order(bool $processing_order) : self
Parameters
$processing_order : bool

Whether the discount type is processing a WooCommerce order.

Return values
self —

The discount type.

set_total_discounted_products()

Set the total number of discounted products in the cart|order.

public set_total_discounted_products(int $total_discounted_products) : self
Parameters
$total_discounted_products : int

The total number of discounted products in the cart|order.

Return values
self —

The discount type.

set_total_order_discount()

Set the total discount that needs to be applied to the order.

public set_total_order_discount(float $total_order_discount) : self
Parameters
$total_order_discount : float

The total discount that needs to be applied to the order.

Return values
self —

The discount type.

calculate_number_of_items_to_buy_with_discount()

Calculate the number of items to buy with discount for a given total quantity based on the number of items needed for one discount loop.

private calculate_number_of_items_to_buy_with_discount(int $total_quantity, int $full_price_quantity, int $free_quantity[, bool $is_line_item_based = false ]) : int
Parameters
$total_quantity : int

The total quantity of the product in the cart.

$full_price_quantity : int

The number of items to buy at full price.

$free_quantity : int

The number of items to buy with discount.

$is_line_item_based : bool = false

Whether the discount is based on the line item quantity.

Return values
int —

Discount loops.

cart_has_product_with_required_qty()

Check if the cart has a product with the required quantity.

private cart_has_product_with_required_qty(array<string|int, mixed> $products[, bool|int $custom_additional_qty = false ][, bool $skip_additional_qty = false ]) : bool
Parameters
$products : array<string|int, mixed>

Array of products in the cart.

$custom_additional_qty : bool|int = false

Whether to use the custom additional quantity or not.

$skip_additional_qty : bool = false

Whether to skip the additional quantity or not.

Return values
bool —

True if the cart has a product with the required quantity, false otherwise.

discount_cheapest_in_cart_order()

Discount the products based on the subtotal of the relevant products.

private discount_cheapest_in_cart_order(array<string|int, mixed> $products[, WC_Cart|bool $cart = false ][, WC_Order|bool $order = false ]) : void

Here we retrieve the total quantity of the relevant products and then calculate how many times the discount should be applied.

Parameters
$products : array<string|int, mixed>

The products.

$cart : WC_Cart|bool = false

Whether the products are cart items.

$order : WC_Order|bool = false

Whether the products are order items.

Return values
void —

discount_products_cart_basis()

Discount the additional products based on the cart quantity.

private discount_products_cart_basis(array<string|int, mixed> $products[, WC_Cart|bool $cart = false ][, WC_Order|bool $order = false ]) : void
Parameters
$products : array<string|int, mixed>

The products.

$cart : WC_Cart|bool = false

The cart.

$order : WC_Order|bool = false

The order.

Return values
void —

discount_products_line_item_basis()

Discount the products based on the line item quantity.

private discount_products_line_item_basis(array<string|int, mixed> $products[, bool $is_order = false ][, bool $is_cart_basis = false ], int $force_apply_count) : void
Parameters
$products : array<string|int, mixed>

The products.

$is_order : bool = false

Whether the products are order items.

$is_cart_basis : bool = false

Whether the discount is based on the cart quantity. (This bypasses the min required qty check)

$force_apply_count : int

The number of items to apply the discount to.

Return values
void —

get_cart_subtotal()

Get the appropriate subtotal used to determine the dynamic discount amount generated by the fixed price.

private get_cart_subtotal(WC_Cart $cart) : float
  • If the discount applies to all products, then the subtotal of the cart is used.
  • If the discount applies to specific products, then the subtotal of those products combined is used.
  • If the discount applies to specific categories, then the subtotal of the products in those categories combined is used.

The subtotal also needs to take into account whether prices include tax.

Parameters
$cart : WC_Cart

The cart.

Return values
float —

The subtotal.

get_order_subtotal()

Get the appropriate subtotal used to determine the dynamic discount amount generated by the fixed price.

private get_order_subtotal(WC_Order $order) : float
  • If the discount applies to all products, then the subtotal of the order is used.
  • If the discount applies to specific products, then the subtotal of those products combined is used.
  • If the discount applies to specific categories, then the subtotal of the products in those categories combined is used.

The subtotal also needs to take into account whether prices include tax.

Parameters
$order : WC_Order

The order.

Return values
float —

The subtotal.

order_has_product_with_required_qty()

Check if the order has a product with the required quantity.

private order_has_product_with_required_qty(array<string|int, mixed> $products[, bool|int $custom_additional_qty = false ][, bool $skip_additional_qty = false ]) : bool
Parameters
$products : array<string|int, mixed>

Array of products in the order.

$custom_additional_qty : bool|int = false

Whether to use the custom additional quantity or not.

$skip_additional_qty : bool = false
Return values
bool —

True if the order has a product with the required quantity, false otherwise.

Search results