Graduate `__experimental_woocommerce_blocks_checkout_update_order_met…

…a` action to stable (woocommerce#5017) * Deprecate __experimental_woocommerce_blocks_checkout_update_order_meta * Update docs to show new action and remove deprecated one * Amend deprecated tag and add version numbers * Resolve conflict where old hook name was included in example docs
jonny-bull · Dec 14, 2021 · 1abc2eb · 1abc2eb
1 parent f7e5600
commit 1abc2eb
Show file tree

Hide file tree

Showing 5 changed files with 90 additions and 71 deletions.
diff --git a/bin/hook-docs/data/actions.json b/bin/hook-docs/data/actions.json
@@ -1,35 +1,6 @@
 {
     "$schema": "https://raw.githubusercontent.com/johnbillion/wp-hooks-generator/0.6.1/schema.json",
     "hooks": [
-        {
-            "name": "__experimental_woocommerce_blocks_checkout_update_order_meta",
-            "file": "StoreApi/Routes/Checkout.php",
-            "type": "action",
-            "doc": {
-                "description": "Fires when the Checkout Block/Store API updates an order's meta data.",
-                "long_description": "This hook gives extensions the chance to add or update meta data on the $order.\n This is similar to existing core hook woocommerce_checkout_update_order_meta. We're using a new action: - To keep the interface focused (only pass $order, not passing request data). - This also explicitly indicates these orders are from checkout block/StoreAPI.",
-                "tags": [
-                    {
-                        "name": "see",
-                        "content": "",
-                        "refers": "https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/3686"
-                    },
-                    {
-                        "name": "internal",
-                        "content": "This Hook is experimental and may change or be removed."
-                    },
-                    {
-                        "name": "param",
-                        "content": "Order object.",
-                        "types": [
-                            "\\WC_Order"
-                        ],
-                        "variable": "$order"
-                    }
-                ],
-                "long_description_html": "<p>This hook gives extensions the chance to add or update meta data on the $order.</p> <p>This is similar to existing core hook woocommerce_checkout_update_order_meta. We're using a new action:</p> <ul> <li>To keep the interface focused (only pass $order, not passing request data).</li> <li>This also explicitly indicates these orders are from checkout block/StoreAPI.</li> </ul>"
-            }
-        },
         {
             "name": "woocommerce_add_to_cart",
             "file": "StoreApi/Utilities/CartController.php",
@@ -112,7 +83,7 @@
         },
         {
             "name": "woocommerce_blocks_cart_enqueue_data",
-            "file": "BlockTypes/MiniCart.php",
+            "file": "BlockTypes/Cart.php",
             "type": "action",
             "doc": {
                 "description": "Fires after cart block data is registered.",
@@ -123,7 +94,7 @@
         },
         {
             "name": "woocommerce_blocks_cart_enqueue_data",
-            "file": "BlockTypes/Cart.php",
+            "file": "BlockTypes/MiniCart.php",
             "type": "action",
             "doc": {
                 "description": "Fires after cart block data is registered.",
@@ -200,6 +171,31 @@
                 "long_description_html": "<p>This hook gives extensions the chance to update orders based on the data in the request. This can be used in conjunction with the ExtendRestAPI class to post custom data and then process it.</p>"
             }
         },
+        {
+            "name": "woocommerce_blocks_checkout_update_order_meta",
+            "file": "StoreApi/Routes/Checkout.php",
+            "type": "action",
+            "doc": {
+                "description": "Fires when the Checkout Block/Store API updates an order's meta data.",
+                "long_description": "This hook gives extensions the chance to add or update meta data on the $order.\n This is similar to existing core hook woocommerce_checkout_update_order_meta. We're using a new action: - To keep the interface focused (only pass $order, not passing request data). - This also explicitly indicates these orders are from checkout block/StoreAPI.",
+                "tags": [
+                    {
+                        "name": "see",
+                        "content": "",
+                        "refers": "https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/3686"
+                    },
+                    {
+                        "name": "param",
+                        "content": "Order object.",
+                        "types": [
+                            "\\WC_Order"
+                        ],
+                        "variable": "$order"
+                    }
+                ],
+                "long_description_html": "<p>This hook gives extensions the chance to add or update meta data on the $order.</p> <p>This is similar to existing core hook woocommerce_checkout_update_order_meta. We're using a new action:</p> <ul> <li>To keep the interface focused (only pass $order, not passing request data).</li> <li>This also explicitly indicates these orders are from checkout block/StoreAPI.</li> </ul>"
+            }
+        },
         {
             "name": "woocommerce_blocks_enqueue_cart_block_scripts_after",
             "file": "BlockTypes/Cart.php",

diff --git a/docs/blocks/feature-flags-and-experimental-interfaces.md b/docs/blocks/feature-flags-and-experimental-interfaces.md
@@ -84,7 +84,7 @@ We also have individual features or code blocks behind a feature flag, this is a
 ### PHP filters and actions
 
 -   `__experimental_woocommerce_blocks_payment_gateway_features_list` hook that allows modification of the features supported by PayPal Standard. ([experimental hook](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/4cedb65367be0d1c4c1f9dd9c016e3b1325cf92e/src/Payments/Integrations/PayPal.php#L86)).
--   `__experimental_woocommerce_blocks_checkout_update_order_meta` hook when the draft order has been created or updated from the cart and is now ready for extensions to modify the metadata ([experimental hook](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/3686/files#diff-af2c90fa556cc086b780c8fad99b68373d87fd6007e6e2ff1b4c68ebe9ccb551R377-R393)).
+-   **Deprecated** - `__experimental_woocommerce_blocks_checkout_update_order_meta` hook when the draft order has been created or updated from the cart and is now ready for extensions to modify the metadata ([experimental hook](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/3686/files#diff-af2c90fa556cc086b780c8fad99b68373d87fd6007e6e2ff1b4c68ebe9ccb551R377-R393)). [Deprecated in PR 5017](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/5017).
 -   **Deprecated** - `__experimental_woocommerce_blocks_checkout_update_order_from_request` hook gives extensions the chance to update orders based on the data in the request ([deprecated experimental hook](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/d469a45d572f2c52d7917707c492dfb905ddfac0/src/StoreApi/Routes/Checkout.php#L466-L477)). [Deprecated in PR 5015](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/5015).
 -   **Deprecated** - `__experimental_woocommerce_blocks_checkout_order_processed` hook when order has completed processing and is ready for payment ([deprecated experimental hook](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/accd1bbf402e043b9fc322f118ab614ba7437c92/src/StoreApi/Routes/Checkout.php#L237)). [Deprecated in PR 5014](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/5014).
 -   `__experimental_woocommerce_blocks_add_data_attributes_to_namespace` hook that allows 3PD to add a namespace of blocks to receive block attributes as `data-` attributes ([experimental property](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/4a1ee97eb97011458174e93e44a9b7ad2f10ca36/src/BlockTypesController.php#L88)).

diff --git a/docs/examples/checkout-order-processed.md b/docs/examples/checkout-order-processed.md
@@ -5,5 +5,5 @@ function my_function_callback( $order ) {
   $order->save();
 }
 
-add_action( '__experimental_woocommerce_blocks_checkout_order_processed', 'my_function_callback', 10 );
+add_action( 'woocommerce_blocks_checkout_order_processed', 'my_function_callback', 10 );
 ```
diff --git a/docs/extensibility/actions.md b/docs/extensibility/actions.md
@@ -7,14 +7,14 @@
 ## Table of Contents
 
 
- - [__experimental_woocommerce_blocks_checkout_update_order_meta](#__experimental_woocommerce_blocks_checkout_update_order_meta)
  - [woocommerce_add_to_cart](#woocommerce_add_to_cart)
  - [woocommerce_applied_coupon](#woocommerce_applied_coupon)
  - [woocommerce_blocks_cart_enqueue_data](#woocommerce_blocks_cart_enqueue_data)
  - [woocommerce_blocks_cart_enqueue_data](#woocommerce_blocks_cart_enqueue_data-1)
  - [woocommerce_blocks_checkout_enqueue_data](#woocommerce_blocks_checkout_enqueue_data)
  - [woocommerce_blocks_checkout_order_processed](#woocommerce_blocks_checkout_order_processed)
  - [woocommerce_blocks_checkout_update_order_from_request](#woocommerce_blocks_checkout_update_order_from_request)
+ - [woocommerce_blocks_checkout_update_order_meta](#woocommerce_blocks_checkout_update_order_meta)
  - [woocommerce_blocks_enqueue_cart_block_scripts_after](#woocommerce_blocks_enqueue_cart_block_scripts_after)
  - [woocommerce_blocks_enqueue_cart_block_scripts_before](#woocommerce_blocks_enqueue_cart_block_scripts_before)
  - [woocommerce_blocks_enqueue_checkout_block_scripts_after](#woocommerce_blocks_enqueue_checkout_block_scripts_after)
@@ -30,40 +30,6 @@
 
 ---
 
-## __experimental_woocommerce_blocks_checkout_update_order_meta
-
-
-Fires when the Checkout Block/Store API updates an order's meta data.
-
-```php
-do_action( '__experimental_woocommerce_blocks_checkout_update_order_meta', \WC_Order $order )
-```
-
-
-**Note: This Hook is experimental and may change or be removed.**
-
-### Description
-
-<p>This hook gives extensions the chance to add or update meta data on the $order.</p> <p>This is similar to existing core hook woocommerce_checkout_update_order_meta. We're using a new action:</p> <ul> <li>To keep the interface focused (only pass $order, not passing request data).</li> <li>This also explicitly indicates these orders are from checkout block/StoreAPI.</li> </ul>
-
-### Parameters
-
-| Argument | Type | Description |
-| -------- | ---- | ----------- |
-| $order | \WC_Order | Order object. |
-
-### Related
-
-
- - https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/3686
-
-### Source
-
-
-File: [StoreApi/Routes/Checkout.php](../src/StoreApi/Routes/Checkout.php)
-
----
-
 ## woocommerce_add_to_cart
 
 
@@ -129,7 +95,7 @@ do_action( 'woocommerce_blocks_cart_enqueue_data' )
 ### Source
 
 
-File: [BlockTypes/MiniCart.php](../src/BlockTypes/MiniCart.php)
+File: [BlockTypes/Cart.php](../src/BlockTypes/Cart.php)
 
 ---
 
@@ -145,7 +111,7 @@ do_action( 'woocommerce_blocks_cart_enqueue_data' )
 ### Source
 
 
-File: [BlockTypes/Cart.php](../src/BlockTypes/Cart.php)
+File: [BlockTypes/MiniCart.php](../src/BlockTypes/MiniCart.php)
 
 ---
 
@@ -232,6 +198,37 @@ do_action( 'woocommerce_blocks_checkout_update_order_from_request', \WC_Order $o
 ### Source
 
 
+File: [StoreApi/Routes/Checkout.php](../src/StoreApi/Routes/Checkout.php)
+
+---
+
+## woocommerce_blocks_checkout_update_order_meta
+
+
+Fires when the Checkout Block/Store API updates an order's meta data.
+
+```php
+do_action( 'woocommerce_blocks_checkout_update_order_meta', \WC_Order $order )
+```
+
+### Description
+
+<p>This hook gives extensions the chance to add or update meta data on the $order.</p> <p>This is similar to existing core hook woocommerce_checkout_update_order_meta. We're using a new action:</p> <ul> <li>To keep the interface focused (only pass $order, not passing request data).</li> <li>This also explicitly indicates these orders are from checkout block/StoreAPI.</li> </ul>
+
+### Parameters
+
+| Argument | Type | Description |
+| -------- | ---- | ----------- |
+| $order | \WC_Order | Order object. |
+
+### Related
+
+
+ - https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/3686
+
+### Source
+
+
 File: [StoreApi/Routes/Checkout.php](../src/StoreApi/Routes/Checkout.php)
 
 ---

diff --git a/src/StoreApi/Routes/Checkout.php b/src/StoreApi/Routes/Checkout.php
@@ -420,8 +420,34 @@ private function create_or_update_draft_order() {
 		 * @internal This Hook is experimental and may change or be removed.
 		 *
 		 * @param \WC_Order $order Order object.
+		 *
+		 * @deprecated 6.3.0 Use woocommerce_blocks_checkout_update_order_meta instead.
+		 */
+		do_action_deprecated(
+			'__experimental_woocommerce_blocks_checkout_update_order_meta',
+			array(
+				$this->order,
+			),
+			'6.3.0',
+			'woocommerce_blocks_checkout_update_order_meta',
+			'This action was deprecated in WooCommerce Blocks version 6.3.0. Please use woocommerce_blocks_checkout_update_order_meta instead.'
+		);
+
+		/**
+		 * Fires when the Checkout Block/Store API updates an order's meta data.
+		 *
+		 * This hook gives extensions the chance to add or update meta data on the $order.
+		 *
+		 * This is similar to existing core hook woocommerce_checkout_update_order_meta.
+		 * We're using a new action:
+		 * - To keep the interface focused (only pass $order, not passing request data).
+		 * - This also explicitly indicates these orders are from checkout block/StoreAPI.
+		 *
+		 * @see https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/3686
+		 *
+		 * @param \WC_Order $order Order object.
 		 */
-		do_action( '__experimental_woocommerce_blocks_checkout_update_order_meta', $this->order );
+		do_action( 'woocommerce_blocks_checkout_update_order_meta', $this->order );
 
 		// Confirm order is valid before proceeding further.
 		if ( ! $this->order instanceof \WC_Order ) {