This page is written for WooCommerce developers looking to extend or customize WooCommerce Composite Products. It requires an advanced understanding of PHP and WordPress development.
Summary
↑ Back to topThis guide introduces some of the most useful functions available in Composite Products. It does not include tutorials on how to achieve certain tasks.
We recommend reading Data Structures and Storage before consulting this reference. Take time to familiarize yourself with the plugin architecture and the the WC_CP_Cart and WC_CP_Order objects.
Shop Functions Summary
↑ Back to top| Name | Description |
|---|---|
| is_composite_product | Conditional function. Returns true when viewing a composite-type product details shop page. |
Cart Functions Summary
↑ Back to topGlobal Cart Functions
| Name | Description |
|---|---|
| wc_cp_is_composited_cart_item | Checks if a cart item is part of a composite. Instead of relying solely on cart item data, the function also checks that a parent cart item actually exists. |
| wc_cp_get_composited_cart_item_container | Finds and returns the composite parent cart item that a composite child item belongs to. |
| wc_cp_is_composite_container_cart_item | Checks if a cart item is a composite container item. |
| wc_cp_get_composited_cart_items | Finds and returns the child cart items associated with a composite container item. |
Cart API Methods
| Name | Description |
|---|---|
| add_composite_to_cart | Validates and adds a composite to the cart. Expects a composite configuration array to be constructed and passed into the method. |
| validate_composite_configuration | Validates a composite configuration array. |
Order Functions Summary
↑ Back to topGlobal Order Functions
| Name | Description |
|---|---|
| wc_cp_is_composited_order_item | Checks if an order item is part of a composite. Instead of relying solely on order item meta, the function also checks that a parent item actually exists. |
| wc_cp_get_composited_order_item_container | Finds and returns the container order item that a composite child item belongs to. |
| wc_cp_is_composite_container_order_item | Checks if an order item is a composite container item. |
| wc_cp_get_composited_order_items | Finds and returns the composite child order items associated with a composite container item. |
Order API Methods
| Name | Description |
|---|---|
| add_composite_to_order | Validates and adds a composite to an order. Expects a composite configuration array to be constructed and passed into the method. |
| get_order_items | Modifies composite parent/child order items depending on their shipping setup. Used to reconstruct an accurate physical representation of a composite, typically as a callback conditionally attached to the woocommerce_order_get_items filter when exporting order data to external fulfillment, shipping or inventory management services. |
| get_product_from_item | Modifies products constructed from composite parent/child order items. Used to reconstruct an accurate physical representation of a composite, typically as a callback conditionally attached to the woocommerce_get_product_from_item filter when exporting order data to external fulfillment, shipping or inventory management services. |
Shop Functions
↑ Back to topis_composite_product
Description
boolean is_composite_product()
True when viewing a product details shop page of a composite-type product.
Return Values
boolean – See description.
Usage
$result = is_composite_product();
Cart Functions
↑ Back to topGlobal Cart Functions
↑ Back to topThe extension provides the following global utility functions that allow you to identify and work with the parent/child cart items associated with a composite:
wc_cp_is_composited_cart_item
Description
boolean wc_cp_is_composited_cart_item( array $cart_item [, array $cart_contents = false ] )
Checks if a cart item is part of a composite. Instead of relying solely on cart item data, the function also checks that a parent item actually exists.
Arguments
array $cart_item – Cart item to check.array $cart_contents – Cart contents array to search in (optional).
Return Values
boolean – See description.
Usage
$result = wc_cp_is_composited_cart_item( $cart_item );
wc_cp_get_composited_cart_item_container
Description
mixed wc_cp_get_composited_cart_item_container( array $cart_item [, array $cart_contents = false ] [, boolean $return_id = false ] )
Finds and returns the container cart item that a composite child item belongs to. If the passed cart item is not a composite child item, false is returned.
Arguments
array $cart_item – The cart item whose composite container is searched.array $cart_contents – Cart contents array to search in (optional).boolean $return_id – When set to true, the function returns the cart ID of the found container item, instead of the item itself (if found) (optional).
Return Values
array|string|false – If the passed cart item is actually a composite child item and a container item is found, the function returns the container item (or its cart ID when the $return_id argument is true). Otherwise, a boolean false value is returned.
Usage
$container_item = wc_cp_get_composited_cart_item_container( $cart_item );
wc_cp_is_composite_container_cart_item
Description
boolean wc_cp_is_composite_container_cart_item( array $cart_item )
Checks if a cart item is a composite container item. Does not check for the existence of any child items — in some cases, a composite configuration may not include any child items.
Arguments
array $cart_item – Cart item to check.
Return Values
boolean – See description.
Usage
$result = wc_cp_is_composite_container_cart_item( $cart_item );
wc_cp_get_composited_cart_items
Description
array wc_cp_get_composited_cart_items( array $cart_item [, array $cart_contents = false ] [, boolean $return_ids = false ] )
Finds and returns the child cart items (children) associated with a composite container cart item. If the passed cart item is not a composite container cart item, an empty array is returned.
Arguments
array $cart_item – The (composite container) cart item whose children are searched.array $cart_contents – Cart contents array to search in (optional).boolean $return_ids – When set to true, the function returns the cart IDs of the child items, instead of the actual items (if found) (optional).
Return Values
array – If the passed cart item is actually a container cart item and a collection of child items exists, the function returns an array with the discovered cart items (or their cart IDs when the $return_ids argument is true). Otherwise, an empty array is returned.
Usage
$child_items = wc_cp_get_composited_cart_items( $cart_item );
Cart API Methods
↑ Back to topIn addition to the globally accessible utility methods documented in the previous section, the cart API of the extension includes methods for validating and adding an entire composite to the cart programmatically. The methods documented in this section are callable on the WC_CP_Cart instance accessible via WC_CP()->cart.
add_composite_to_cart
Description
mixed add_composite_to_cart( integer $product_id , integer $quantity [, array $configuration = array() ] [, array $cart_item_data = array() ] )
Validates and adds a composite to the cart. Expects a composite configuration array to be constructed and passed into the method.
Arguments
integer $product_id – Product ID of the composite to add to the cart.integer $quantity – Quantity of the composite.array $configuration – Composite configuration data. An array of component configuration data indexed by component ID. Component configuration data values are also arrays that must conform to the following schema:
| Field Key | Field Type | Description |
|---|---|---|
product_id |
integer |
ID of child product in component. |
quantity |
integer |
Quantity of child product. |
variation_id |
integer |
ID of selected variation, applicable if the child product is variable. |
attributes |
array |
Index of variation attribute names and values, applicable if the child product is variable. |
discount |
float |
Component discount, overrides the defined component discount (if present). Applicable when the Priced Individually option is enabled. |
Example:
$args = array(
12345481 => array(
'product_id' => 1543,
'quantity' => 3,
),
12345483 => array(
'product_id' => 1386,
'quantity' => 1,
'variation_id' => 3535,
'attributes' => array(
'attribute_pa_attribute-1' => 'value-1b',
'attribute_pa_attribute-2' => 'value-2b',
),
)
);
$added = WC_CP()->cart->add_composite_to_cart( 3520, 1, $args );
The composite product of this example contains 2 components with IDs 12345481 and 12345483. The chosen product IDs for these components are 1543 and 1386, respectively. Note that the latter one is a variable product, requiring the presence of a variation_id and an attributes field.
array $cart_item_data – Cart item data fields to pass into WC_Cart::add_to_cart (optional).
Return Values
string|WP_Error – If validation is successful, the method returns the cart item ID of the added composite container item. If not, it returns a WP_Error object, populated with all generated validation errors. Note that any WooCommerce notices generated during validation are not automatically cleared and will be displayed in the next front-end request. If needed, clear them from the WC session by calling wc_clear_notices().
Usage
$result = WC_CP()->cart->add_composite_to_cart( $composite_id, $quantity, $configuration );
validate_composite_configuration
Description
boolean validate_composite_configuration( mixed $product , integer $quantity, array $configuration [, string $context = 'add-to-cart' ] )
Validates a composite configuration. Expects a composite configuration array to be constructed and passed into the method.
Arguments
integer|string|WC_Product $product – Composite product (or ID of) to use for validating.integer $quantity – Quantity of the composite to use during validation.array $configuration – Composite configuration array. Contains component configuration data indexed by component ID. For details, refer to add_composite_to_cart.string $context – Validation context (optional, internal use only).
Return Values
boolean – Validation result.
Usage
$result = WC_CP()->cart->validate_composite_configuration( $composite, $quantity, $configuration );
Order Functions
↑ Back to topGlobal Order Functions
↑ Back to topThe extension provides the following global utility functions that allow you to identify and work with the parent/child order items associated with a composite:
wc_cp_is_composited_order_item
Description
boolean wc_cp_is_composited_order_item( array $order_item , WC_Order $order )
Checks if an order item is part of a composite. Instead of relying solely on order item meta, the function also checks that a parent item actually exists.
Arguments
array $order_item – Order item to check.WC_Order $order – WooCommerce order object.
Return Values
boolean – See description.
Usage
$result = wc_cp_is_composited_order_item( $order_item, $order );
wc_cp_get_composited_order_item_container
Description
mixed wc_cp_get_composited_order_item_container( array $order_item , WC_Order $order [, boolean $return_id = false ] )
Finds and returns the container order item that a composite child item belongs to. If the passed order item is not a composite child item, false is returned.
Arguments
array $order_item – The (composite child) order item whose container is searched.WC_Order $order – WooCommerce order object to search in.boolean $return_id – When set to true, the function returns the order item ID of the found container item, instead of the item itself (if found) (optional).
Return Values
array|integer|false – If the passed order item is actually a composite child item and a container item is found, the function returns the container item (or its order item ID when the $return_id argument is true). Otherwise, a boolean false value is returned.
Usage
$container_item = wc_cp_get_composited_order_item_container( $order_item, $order );
wc_cp_is_composite_container_order_item
Description
boolean wc_cp_is_composite_container_order_item( array $order_item )
Checks if an order item is a composite container item. Does not check for the existence of any child items – in some cases, a composite configuration may not include any children at all.
Arguments
array $order_item – Order item to check.
Return Values
boolean – See description.
Usage
$result = wc_cp_is_composite_container_order_item( $order_item );
wc_cp_get_composited_order_items
Description
array wc_cp_get_composited_order_items( array $cart_item , WC_Order $order [, boolean $return_ids = false ] )
Finds and returns the composite child order items associated with a composite container item. If the passed order item is not a composite container order item, an empty array is returned.
Arguments
array $order_item – The (composite container) cart item whose children are searched.WC_Order $order – WooCommerce order object to search in.boolean $return_ids – When set to true, the function returns the order item IDs of the found child items, instead of the items themselves (if found) (optional).
Return Values
array – If the passed order item is actually a composite container order item and a collection of child items exists, the function returns an array with the discovered child items (or their order item IDs when the $return_ids argument is true). Otherwise, an empty array is returned.
Usage
$child_items = wc_cp_get_composited_order_items( $order_item, $order );
Order API Methods
↑ Back to topIn addition to the globally accessible utility methods documented in the previous section, the order API of the extension is rounded off with add_composite_to_order, a method for validating and adding an entire composite to an order programmatically. This is callable on the WC_CP_Order instance accessible via WC_CP()->order.
add_composite_to_order
Description
mixed add_composite_to_order( WC_Product_Composite $product , WC_Order $order , integer $quantity [, array $args = array() ] )
Validates and adds a composite to an order. Expects a composite configuration array to be passed to the method as a configuration field of the $args argument. Validation of the specified composite configuration is done via WC_CP_Cart::validate_composite_configuration, which is documented here.
Arguments
WC_Product_Composite $product – Composite product to add to the order.WC_Order $order – Order to which the composite is added.integer $quantity – Quantity of the composite.array $args – Fields to be passed into the $args argument of WC_Order::add_product, when the composite container order item is added. Composite configuration data is passed into the method as a configuration field of this argument. Details about its schema are provided in the add_composite_to_cart method of the Cart API. Additionally, a silent field is used to control whether validation errors are displayed in the next front-end request. Refer to the Return Values section below for more information.
Example:
$args = array(
'configuration' => array(
12345481 => array(
'product_id' => 1543,
'quantity' => 3,
'args' => array()
),
12345483 => array(
'product_id' => 1386,
'quantity' => 1,
'variation_id' => 3535,
'attributes' => array(
'attribute_pa_attribute-1' => 'value-1b',
'attribute_pa_attribute-2' => 'value-2b'
)
)
),
'silent' => false
);
$composite = wc_get_product( 3520 );
$order = wc_get_order( 3539 );
$added = WC_CP()->order->add_composite_to_order( $composite, $order, 1, $args );
When a composite container item (parent) is added to an order, the entire $args array is passed into WC_Order::add_product. If you need to pass any custom fields into the $args argument of WC_Order::add_product, include them in the $args argument of add_composite_to_order. You can also pass custom fields into the $args argument of WC_Order::add_product when the method is called to add the individual child items to the order. This is possible by adding an args field to the component configuration data passed into the method. This is demonstrated in the example above, where an args field is added to the configuration of the component with ID 12345481.
Return Values
integer|WP_Error – If validation is successful, the method returns the order item ID of the added composite container item. If not, it returns a WP_Error object, populated with all generated validation errors. When validation fails, the method returns a WP_Error object without displaying any WooCommerce notices in the front-end. To have all validation notices displayed in the next front-end request, set the $args[ 'silent' ] field to false when calling the method.
Usage
$result = WC_CP()->order->add_composite_to_order( $composite, $order, $quantity, $args );
get_order_items
Description
mixed get_order_items( array $order_items , WC_Order $order )
Modifies composite parent/child order items depending on their shipping setup. Useful for reconstructing an accurate physical representation of a composite, typically as a callback conditionally attached to the woocommerce_order_get_items filter when exporting order data to external fulfillment, shipping or inventory management services.
The method:
- sets the totals of assembled child items to zero, and
- adds their original totals to the totals of their container.
Note that “assembled” in this context refers to items that are not Shipped Individually.
Arguments
array $order_items – Unmodified collection of order items.WC_Order $order – Order object.
Return Values
array – Modified collection of order items.
Usage
The method is used in the WC_CP_Shipstation_Compatibility class, which contains compatibility code for the WooCommerce Shipstation Integration extension.
For details, please refer to this note.
$result = WC_CP()->order->get_order_items( $order_items, $order );
get_product_from_item
Description
mixed get_product_from_item( WC_Product $product , array $order_item , WC_Order $order )
Modifies products constructed from composite parent/child order items. Used to reconstruct an accurate physical representation of a composite, typically as a callback conditionally attached to the woocommerce_get_product_from_item filter when exporting order data to external fulfillment, shipping or inventory management services.
The method applies the following modifications:
- If the product object is associated with a composite container item, then its weight is modified to include the weight of all assembled children.
- If the product object is associated with a child item that is assembled inside its parent, then it is marked as virtual.
Note that “assembled” in this context refers to items that are not Shipped Individually.
Arguments
WC_Product $product – Unmodified product object.array $order_item – Order item that the product object was created from.WC_Order $order – Order object.
Return Values
WC_Product – Modified product object.
Usage
The method is used in the WC_CP_Shipstation_Compatibility class, which contains compatibility code for the WooCommerce Shipstation Integration extension.
For details, please refer to this note.
$result = WC_PB()->order->get_product_from_item( $product, $order_item, $order );
Questions & Support
↑ Back to topHave a question? Please fill out this pre-sales form.
Already purchased and need assistance? Get in touch with us via the Help Desk!