Functions Reference

This 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.

Global Cart Functions

Cart API Methods

Global Order Functions

Order API Methods

is_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();

The 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 );

In 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:

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 );

The 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 );

In 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 );

Have a question? Please fill out this pre-sales form.
Already purchased and need assistance? Get in touch with us via the Help Desk!