Commit de8f979f30 for woocommerce

commit de8f979f302420256b4f46b618a44fdf9d18ca6f
Author: Michael Pretty <prettyboymp@users.noreply.github.com>
Date:   Thu Jan 8 07:11:11 2026 -0500

    Add performance guidance to get_available_variations() docblock (#62715)

    Document the performance implications of the 'array' vs 'objects' return
    types for WC_Product_Variable::get_available_variations(). The default
    'array' type is expensive for products with many variations as it calls
    get_available_variation() for each one, processing HTML, prices, images,
    and formatting. The 'objects' type returns variation objects directly
    without this overhead.

    Partially fixes WOOPLUG-6106 / #62686

diff --git a/plugins/woocommerce/changelog/wooplug-6106-get-available-variations-docs b/plugins/woocommerce/changelog/wooplug-6106-get-available-variations-docs
new file mode 100644
index 0000000000..41bd46b341
--- /dev/null
+++ b/plugins/woocommerce/changelog/wooplug-6106-get-available-variations-docs
@@ -0,0 +1,4 @@
+Significance: patch
+Type: dev
+
+Add performance guidance to WC_Product_Variable::get_available_variations() docblock
\ No newline at end of file
diff --git a/plugins/woocommerce/includes/class-wc-product-variable.php b/plugins/woocommerce/includes/class-wc-product-variable.php
index 4fb472ec12..d8b597f3b8 100644
--- a/plugins/woocommerce/includes/class-wc-product-variable.php
+++ b/plugins/woocommerce/includes/class-wc-product-variable.php
@@ -301,9 +301,26 @@ class WC_Product_Variable extends WC_Product {
 	/**
 	 * Get an array of available variations for the current product.
 	 *
-	 * @param string $return Optional. The format to return the results in. Can be 'array' to return an array of variation data or 'objects' for the product objects. Default 'array'.
+	 * Important: The default 'array' return type is expensive for products with many variations.
+	 * It calls get_available_variation() for each variation, which processes HTML generation
+	 * (wc_get_stock_html, get_price_html), price calculations (wc_get_price_to_display),
+	 * image attachment lookups, and dimension/weight formatting - all passed through filters.
+	 *
+	 * Use 'objects' when you only need the WC_Product_Variation objects or a subset of the generated
+	 * output of ::get_available_variation(), avoiding unnecessary processing overhead.
+	 *
+	 * @since 2.4.0
+	 *
+	 * @param string $return Optional. The format to return the results in. Default 'array'.
+	 *                       - 'array': Returns fully processed variation data arrays. Each variation
+	 *                         is passed through get_available_variation() which generates HTML,
+	 *                         calculates display prices, and formats dimensions/weights. Use this
+	 *                         when you need the complete variation data for front-end display.
+	 *                       - 'objects': Returns WC_Product_Variation objects directly without
+	 *                         additional processing. Use this when you need to work with variation
+	 *                         objects and will call methods on them selectively.
+	 * @return array[]|WC_Product_Variation[] Array of variation data arrays or variation objects.
 	 *
-	 * @return array[]|WC_Product_Variation[]
 	 * @phpstan-param 'array'|'objects' $return
 	 * @phpstan-return ($return is 'array' ? array[] : WC_Product_Variation[])
 	 */