Data Structures and Storage

This document is written for WooCommerce developers looking to extend or customize WooCommerce Composite Products. It requires an advanced understanding of PHP and WordPress development.

Product Data

↑ Back to top

Composite Products are stored in the database as custom post type entries of the product post type, similar to all product types in WooCommerce core. The extension introduces the Composite type by adding a composite term value to the product_type taxonomy.

All composite products are instances of the WC_Product_Composite class, which extends the core WC_Product class. You can use all methods of the WC_Product class with composite-type product instances. In addition to these, the WC_Product_Composite class provides a number of methods specific to Composite Product objects. A detailed reference of all methods is beyond the scope of this document – please refer to the class itself for details about each method.

WC_Product_Composite objects rely on their own datastore for reading/writing object properties from/to the database. The following table contains a list of properties and meta fields specific to the Composite type:

Property	Meta Key	Description
`price`	`_bto_base_price`	Base price of the composite product.
`regular_price`	`_bto_base_regular_price`	Base regular price of the composite product.
`sale_price`	`_bto_base_sale_price`	Base sale price of the composite product.
`composite_data`	`_bto_data`	Component data, serialized.
`scenario_data`	`_bto_scenario_data`	Scenario definitions, serialized.
`layout`	`_bto_style`	Layout value. Values: `single \| progressive \| paged \| paged-componentized`
`shop_price_calc`	`_bto_shop_price_calc`	Catalog Price value. Values: `defaults \| min_max \| hidden`
`editable_in_cart`	`_bto_edit_in_cart`	Edit in Cart option value. Values: `yes \| no`
`add_to_cart_form_location`	`_bto_add_to_cart_form_location`	Form Location value. Values: `yes \| no`
`sold_individually_context`	`_bto_sold_individually`	Sold Individually option context. Values: `product \| configuration`
`virtual_composite`	`_wc_pb_virtual_composite`	Manages state for the Virtual checkbox. When the Virtual box is ticked, all Components, in addition to the Composite itself, are treated as Virtual. When the `virtual_composite` property is `true`, then the `virtual` property is also `true`. When the `virtual_composite` property is `false`, the `virtual` property is used to control whether the Composite is an assembled or unassembled one. For more information, refer to the examples that follow this table. Values: `yes \| no`
`aggregate_weight`	`_wc_bto_aggregate_weight`	When creating assembled Composites, this property controls whether chosen Component Option weights should be aggregated and added to the weight specified under Product Data > Shipping. Values: `yes \| no`

Examples: Physical/Virtual Composite Products

Virtual Composite — `virtual_composite => true | virtual => true`

Unassembled Composite — v`irtual_composite => false | virtual => true`

Assembled Composite — `virtual_composite => false | virtual => false`

Cart & Order Item Data

↑ Back to top

Relationships

↑ Back to top

In cart context, a WC_Product_Composite product acts as a trigger for adding additional products to the cart on the woocommerce_add_to_cart action, depending on the posted configuration data. Prior to this, the extension does its own client-side and server-side validation to ensure that a configuration can be added to the cart, taking into account all configuration and availability constraints.

In the cart, a composite product shows up as a group of cart items:

A container cart item, associated with the composite product itself.
A number of child cart items, each associated with a Component.

Assuming that an order is placed, the same group of quantity-synced cart items will find their way into the created order, as well.

Thanks to this approach:

All inventory management is relayed to WooCommerce core.
Compatibility with 3rd party plugins/extensions is greatly simplified, since the process of adding child products to the cart/orders does not bypass any hooks that would be normally triggered in core.
The container cart/order item can be used to easily override the physical properties of its children at the application layer, useful in use cases with complex shipping requirements.
A clear separation of parent and child prices in the cart makes it easier to implement complex pricing schemes and allows each child item to maintain its individual tax rate.

Cart Item Data

↑ Back to top

Parent/child cart items are identified by appending the following fields to cart items:

Field	Type	Item Context	Description
`composite_parent`	`string`	Child	Cart item ID of the container cart item that this child cart item belongs to.
`composite_children`	`array`	Parent	Cart item IDs of all child cart items associated with a composite container item.
`composite_data`	`array`	Parent/Child	Composite configuration data array, used for a) identifying the entire group uniquely and b) carrying out in-cart validation.
`composite_item`	`string`	Child	Component ID associated with this child cart item.

This data is used internally to establish the parent/child relationships of cart items associated with a composite product. The extension provides a set of global utility functions that you can use to:

Check if a cart item is a composite child item and get its parent.
Check if a cart item is a composite parent item and get its children.

For details, please refer to the Functions Reference.

Order Item Data

↑ Back to top

Parent/child order items are identified by creating the following order item meta:

Key	Type	Item Context	Description
`_composite_cart_key`	`string`	Parent/Child	Original cart item ID (or other unique hash) that identifies the order item.
`_composite_parent`	`string`	Child	Unique hash of the parent order item.
`_composite_children`	`serialized` `array`	Parent	Unique hashes of all associated child items.
`_composite_data`	`serialized` `array`	Parent/Child	Serialized array with composite configuration data, used for a) identifying the entire group uniquely and b) carrying out in-cart validation when re-ordering.
`_composite_item`	`string`	Child	Component ID associated with this child order item.
`_component_priced_- _individually`	`string`	Child	Indicates whether the item was Priced Individually when the order was placed.
`_component_needs_- shipping`	`string`	Child	Indicates whether the child item was Shipped Individually from the composite when the order was placed.
`_composite_weight`	`numeric`	Parent	The total per-unit weight of a composite parent when the order was placed. May differ from the value defined in the Weight field of the Shipping tab when using a variable container weight.

This data is used internally to establish the parent/child relationships of order items associated with a composite. The extension provides a set of global utility functions that you can use to:

Check if an order item is a composite child item and get its parent.
Check if an order item is a composite parent item and get its children.

For details, please refer to the Functions Reference.

Questions & Support

↑ Back to top

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