WooCommerce Code Reference

CartController
in package
Uses DraftOrderTrait

Woo Cart Controller class.

Helper class to bridge the gap between the cart API and Woo core.

Table of Contents

add_to_cart()  : string
Based on the core cart class but returns errors rather than rendering notices directly.
apply_coupon()  : mixed
Based on the core cart class but returns errors rather than rendering notices directly.
calculate_totals()  : mixed
Recalculates the cart totals.
empty_cart()  : mixed
Empty cart contents.
get_cart_coupons()  : array<string|int, mixed>
Returns all applied coupons.
get_cart_errors()  : WP_Error
Validate the cart and get a list of errors.
get_cart_hashes()  : array<string|int, mixed>
Get hashes for items in the current cart. Useful for tracking changes.
get_cart_instance()  : WC_Cart
Get main instance of cart class.
get_cart_item()  : array<string|int, mixed>
Return a cart item from the woo core cart class.
get_cart_items()  : array<string|int, mixed>
Returns all cart items.
get_shipping_packages()  : array<string|int, mixed>
Get shipping packages from the cart with calculated shipping rates.
has_coupon()  : bool
See if cart has applied coupon by code.
load_cart()  : mixed
Makes the cart and sessions available to a route by loading them from core.
select_shipping_rate()  : mixed
Selects a shipping rate.
set_cart_item_quantity()  : mixed
Based on core `set_quantity` method, but validates if an item is sold individually first and enforces any limits in place.
validate_add_to_cart()  : mixed
Validate all items in the cart and check for errors.
validate_cart()  : mixed
Validate cart and check for errors.
validate_cart_coupons()  : mixed
Validate all coupons in the cart and check for errors.
validate_cart_item()  : mixed
Validates an existing cart item and returns any errors.
validate_cart_items()  : mixed
Validate all items in the cart and check for errors.
filter_request_data()  : array<string|int, mixed>
Filter data for add to cart requests.
get_draft_order()  : WC_Order|null
Uses the draft order ID to return an order object, if valid.
get_draft_order_id()  : int
Gets draft order data from the customer session.
get_package_name()  : string
Creates a name for a package.
get_product_for_cart()  : WC_Product|Error
Get a product object to be added to the cart.
get_product_id()  : int
For a given product, get the product ID.
get_product_quantity_in_cart()  : int
Gets the qty of a product across line items.
get_remaining_stock_for_product()  : int
Gets remaining stock for a product.
get_variable_product_attributes()  : array<string|int, mixed>
Get product attributes from the variable product (which may be the parent if the product object is a variation).
get_variation_id()  : int
For a given product, get the variation ID.
get_variation_id_from_variation_data()  : int
Try to match request data to a variation ID and return the ID.
is_valid_draft_order()  : bool
Whether the passed argument is a draft order or an order that is pending/failed and the cart hasn't changed.
parse_variation_data()  : array<string|int, mixed>
If variations are set, validate and format the values ready to add to the cart.
sanitize_variation_data()  : array<string|int, mixed>
Format and sanitize variation data posted to the API.
set_draft_order_id()  : mixed
Updates draft order data in the customer session.
throw_default_product_exception()  : mixed
Default exception thrown when an item cannot be added to the cart.
validate_cart_coupon()  : mixed
Validates an existing cart coupon and returns any errors.
add_product_names_to_message()  : mixed
Generates the error message for out of stock products and adds product names to it.
get_error_message_for_stock_exception_type()  : string
Takes a string describing the type of stock extension, whether there is a single product or multiple products causing this exception and returns an appropriate error message.
stock_exceptions_to_wp_errors()  : WP_Error
This method will take arrays of exceptions relating to stock, and will convert them to a WP_Error object.

Methods

add_to_cart()

Based on the core cart class but returns errors rather than rendering notices directly.

public add_to_cart(array<string|int, mixed> $request) : string
Parameters
$request : array<string|int, mixed>

Add to cart request params.

Tags
todo

Overriding the core add_to_cart method was necessary because core outputs notices when an item is added to the cart. For us this would cause notices to build up and output on the store, out of context. Core would need refactoring to split notices out from other cart actions.

throws
RouteException

Exception if invalid data is detected.

Return values
string —

apply_coupon()

Based on the core cart class but returns errors rather than rendering notices directly.

public apply_coupon(string $coupon_code) : mixed
Parameters
$coupon_code : string

Coupon code.

Tags
todo

Overriding the core apply_coupon method was necessary because core outputs notices when a coupon gets applied. For us this would cause notices to build up and output on the store, out of context. Core would need refactoring to split notices out from other cart actions.

throws
RouteException

Exception if invalid data is detected.

Return values
mixed —

get_cart_coupons()

Returns all applied coupons.

public get_cart_coupons([callable $callback = null ]) : array<string|int, mixed>
Parameters
$callback : callable = null

Optional callback to apply to the array filter.

Return values
array<string|int, mixed> —

get_cart_errors()

Validate the cart and get a list of errors.

public get_cart_errors() : WP_Error
Return values
WP_Error — A WP_Error instance containing the cart's errors.

get_cart_hashes()

Get hashes for items in the current cart. Useful for tracking changes.

public get_cart_hashes() : array<string|int, mixed>
Return values
array<string|int, mixed> —

get_cart_item()

Return a cart item from the woo core cart class.

public get_cart_item(string $item_id) : array<string|int, mixed>
Parameters
$item_id : string

Cart item id.

Return values
array<string|int, mixed> —

get_cart_items()

Returns all cart items.

public get_cart_items([callable $callback = null ]) : array<string|int, mixed>
Parameters
$callback : callable = null

Optional callback to apply to the array filter.

Return values
array<string|int, mixed> —

get_shipping_packages()

Get shipping packages from the cart with calculated shipping rates.

public get_shipping_packages([bool $calculate_rates = true ]) : array<string|int, mixed>
Parameters
$calculate_rates : bool = true

Should rates for the packages also be returned.

Tags
todo

this can be refactored once https://github.com/woocommerce/woocommerce/pull/26101 lands.

Return values
array<string|int, mixed> —

has_coupon()

See if cart has applied coupon by code.

public has_coupon(string $coupon_code) : bool
Parameters
$coupon_code : string

Cart coupon code.

Return values
bool —

select_shipping_rate()

Selects a shipping rate.

public select_shipping_rate(int|string $package_id, string $rate_id) : mixed
Parameters
$package_id : int|string

ID of the package to choose a rate for.

$rate_id : string

ID of the rate being chosen.

Return values
mixed —

set_cart_item_quantity()

Based on core `set_quantity` method, but validates if an item is sold individually first and enforces any limits in place.

public set_cart_item_quantity(string $item_id[, int $quantity = 1 ]) : mixed
Parameters
$item_id : string

Cart item id.

$quantity : int = 1

Cart quantity.

Tags
throws
RouteException

Exception if invalid data is detected.

Return values
mixed —

validate_add_to_cart()

Validate all items in the cart and check for errors.

public validate_add_to_cart(WC_Product $product, array<string|int, mixed> $request) : mixed
Parameters
$product : WC_Product

Product object associated with the cart item.

$request : array<string|int, mixed>

Add to cart request params.

Tags
throws
RouteException

Exception if invalid data is detected.

Return values
mixed —

validate_cart()

Validate cart and check for errors.

public validate_cart() : mixed
Tags
throws
InvalidCartException

Exception if invalid data is detected in the cart.

Return values
mixed —

validate_cart_coupons()

Validate all coupons in the cart and check for errors.

public validate_cart_coupons() : mixed
Tags
throws
InvalidCartException

Exception if invalid data is detected.

Return values
mixed —

validate_cart_item()

Validates an existing cart item and returns any errors.

public validate_cart_item(array<string|int, mixed> $cart_item) : mixed
Parameters
$cart_item : array<string|int, mixed>

Cart item array.

Tags
throws
TooManyInCartException

Exception if more than one product that can only be purchased individually is in the cart.

throws
PartialOutOfStockException

Exception if an item has a quantity greater than what is available in stock.

throws
OutOfStockException

Exception thrown when an item is entirely out of stock.

throws
NotPurchasableException

Exception thrown when an item is not purchasable.

Return values
mixed —

validate_cart_items()

Validate all items in the cart and check for errors.

public validate_cart_items() : mixed
Tags
throws
InvalidCartException

Exception if invalid data is detected due to insufficient stock levels.

Return values
mixed —

filter_request_data()

Filter data for add to cart requests.

protected filter_request_data(array<string|int, mixed> $request) : array<string|int, mixed>
Parameters
$request : array<string|int, mixed>

Add to cart request params.

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

get_package_name()

Creates a name for a package.

protected get_package_name(array<string|int, mixed> $package, int $index) : string
Parameters
$package : array<string|int, mixed>

Shipping package from WooCommerce.

$index : int

Package number.

Return values
string —

get_product_for_cart()

Get a product object to be added to the cart.

protected get_product_for_cart(array<string|int, mixed> $request) : WC_Product|Error
Parameters
$request : array<string|int, mixed>

Add to cart request params.

Tags
throws
RouteException

Exception if invalid data is detected.

Return values
WC_Product|Error — Returns a product object if purchasable.

get_variable_product_attributes()

Get product attributes from the variable product (which may be the parent if the product object is a variation).

protected get_variable_product_attributes(WC_Product $product) : array<string|int, mixed>
Parameters
$product : WC_Product

Product being added to the cart.

Tags
throws
RouteException

Exception if product is invalid.

Return values
array<string|int, mixed> —

get_variation_id_from_variation_data()

Try to match request data to a variation ID and return the ID.

protected get_variation_id_from_variation_data(array<string|int, mixed> $request, WC_Product $product) : int
Parameters
$request : array<string|int, mixed>

Add to cart request params.

$product : WC_Product

Product being added to the cart.

Tags
throws
RouteException

Exception if variation cannot be found.

Return values
int — Matching variation ID.

is_valid_draft_order()

Whether the passed argument is a draft order or an order that is pending/failed and the cart hasn't changed.

protected is_valid_draft_order(WC_Order $order_object) : bool
Parameters
$order_object : WC_Order

Order object to check.

Return values
bool — Whether the order is valid as a draft order.

parse_variation_data()

If variations are set, validate and format the values ready to add to the cart.

protected parse_variation_data(array<string|int, mixed> $request) : array<string|int, mixed>
Parameters
$request : array<string|int, mixed>

Add to cart request params.

Tags
throws
RouteException

Exception if invalid data is detected.

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

sanitize_variation_data()

Format and sanitize variation data posted to the API.

protected sanitize_variation_data(array<string|int, mixed> $variation_data, array<string|int, mixed> $variable_product_attributes) : array<string|int, mixed>

Labels are converted to names (e.g. Size to pa_size), and values are cleaned.

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

Key value pairs of attributes and values.

$variable_product_attributes : array<string|int, mixed>

Product attributes we're expecting.

Tags
throws
RouteException

Exception if variation cannot be found.

Return values
array<string|int, mixed> —

set_draft_order_id()

Updates draft order data in the customer session.

protected set_draft_order_id(int $order_id) : mixed
Parameters
$order_id : int

Draft order ID.

Return values
mixed —

throw_default_product_exception()

Default exception thrown when an item cannot be added to the cart.

protected throw_default_product_exception(WC_Product $product) : mixed
Parameters
$product : WC_Product

Product object associated with the cart item.

Tags
throws
RouteException

Exception with code woocommerce_rest_product_not_purchasable.

Return values
mixed —

add_product_names_to_message()

Generates the error message for out of stock products and adds product names to it.

private add_product_names_to_message(string $singular, string $plural, array<string|int, mixed> $items) : mixed
Parameters
$singular : string

The message to use when only one product is in the list.

$plural : string

The message to use when more than one product is in the list.

$items : array<string|int, mixed>

The list of cart items whose names should be inserted into the message.

Tags
returns

string The translated and correctly pluralised message.

Return values
mixed —

get_error_message_for_stock_exception_type()

Takes a string describing the type of stock extension, whether there is a single product or multiple products causing this exception and returns an appropriate error message.

private get_error_message_for_stock_exception_type(string $exception_type, string $singular_or_plural) : string
Parameters
$exception_type : string

The type of exception encountered.

$singular_or_plural : string

Whether to get the error message for a single product or multiple.

Return values
string —

stock_exceptions_to_wp_errors()

This method will take arrays of exceptions relating to stock, and will convert them to a WP_Error object.

private stock_exceptions_to_wp_errors(array<string|int, TooManyInCartException> $too_many_in_cart_products, array<string|int, NotPurchasableException> $not_purchasable_products, array<string|int, PartialOutOfStockException> $partial_out_of_stock_products, array<string|int, OutOfStockException> $out_of_stock_products) : WP_Error
Parameters
$too_many_in_cart_products : array<string|int, TooManyInCartException>

Array of TooManyInCartExceptions.

$not_purchasable_products : array<string|int, NotPurchasableException>

Array of NotPurchasableExceptions.

$partial_out_of_stock_products : array<string|int, PartialOutOfStockException>

Array of PartialOutOfStockExceptions.

$out_of_stock_products : array<string|int, OutOfStockException>

Array of OutOfStockExceptions.

Return values
WP_Error — The WP_Error object returned. Will have errors if any exceptions were in the args. It will be empty if they do not.