Graduate __experimental_woocommerce_blocks_checkout_order_processed…

… action to stable (woocommerce#5014) * Deprecate __experimental_woocommerce_blocks_checkout_order_processed * Update docs to reflect new hook name I also mentioned this hook is deprecated in the experimental interfaces doc. * Update deprecated tag in docblock * Fix typo in deprecated docblock * Send args to do_action_deprecated in an array * Amend deprecated tag and add version numbers
jonny-bull · Dec 14, 2021 · a1a8c1c · a1a8c1c
1 parent 3cb02c3
commit a1a8c1c
Show file tree

Hide file tree

Showing 5 changed files with 102 additions and 84 deletions.
diff --git a/bin/hook-docs/data/actions.json b/bin/hook-docs/data/actions.json
@@ -1,39 +1,6 @@
 {
     "$schema": "https://raw.githubusercontent.com/johnbillion/wp-hooks-generator/0.6.1/schema.json",
     "hooks": [
-        {
-            "name": "__experimental_woocommerce_blocks_checkout_order_processed",
-            "file": "StoreApi/Routes/Checkout.php",
-            "type": "action",
-            "doc": {
-                "description": "Fires before an order is processed by the Checkout Block/Store API.",
-                "long_description": "This hook informs extensions that $order has completed processing and is ready for payment.\n This is similar to existing core hook woocommerce_checkout_order_processed. 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/3238"
-                    },
-                    {
-                        "name": "example",
-                        "content": "docs/examples/checkout-order-processed.md"
-                    },
-                    {
-                        "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 informs extensions that $order has completed processing and is ready for payment.</p> <p>This is similar to existing core hook woocommerce_checkout_order_processed. 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": "__experimental_woocommerce_blocks_checkout_update_order_from_request",
             "file": "StoreApi/Routes/Checkout.php",
@@ -208,6 +175,35 @@
                 "long_description_html": ""
             }
         },
+        {
+            "name": "woocommerce_blocks_checkout_order_processed",
+            "file": "StoreApi/Routes/Checkout.php",
+            "type": "action",
+            "doc": {
+                "description": "Fires before an order is processed by the Checkout Block/Store API.",
+                "long_description": "This hook informs extensions that $order has completed processing and is ready for payment.\n This is similar to existing core hook woocommerce_checkout_order_processed. 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/3238"
+                    },
+                    {
+                        "name": "example",
+                        "content": "docs/examples/checkout-order-processed.md"
+                    },
+                    {
+                        "name": "param",
+                        "content": "Order object.",
+                        "types": [
+                            "\\WC_Order"
+                        ],
+                        "variable": "$order"
+                    }
+                ],
+                "long_description_html": "<p>This hook informs extensions that $order has completed processing and is ready for payment.</p> <p>This is similar to existing core hook woocommerce_checkout_order_processed. 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
@@ -86,7 +86,7 @@ We also have individual features or code blocks behind a feature flag, this is a
 -   `__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)).
 -   `__experimental_woocommerce_blocks_checkout_update_order_from_request` hook gives extensions the chance to update orders based on the data in the request ([experimental hook](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/d469a45d572f2c52d7917707c492dfb905ddfac0/src/StoreApi/Routes/Checkout.php#L466-L477)).
--   `__experimental_woocommerce_blocks_checkout_order_processed` hook when order has completed processing and is ready for payment ([experimental hook](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/accd1bbf402e043b9fc322f118ab614ba7437c92/src/StoreApi/Routes/Checkout.php#L237)).
+-   **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)).
 -   `__experimental_woocommerce_blocks_add_data_attributes_to_block` hook that allows 3PD to add a block to recieve block attributes as `data-` attributes ([experimental property](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/4a1ee97eb97011458174e93e44a9b7ad2f10ca36/src/BlockTypesController.php#L97)).
 

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_order_processed](#__experimental_woocommerce_blocks_checkout_order_processed)
  - [__experimental_woocommerce_blocks_checkout_update_order_from_request](#__experimental_woocommerce_blocks_checkout_update_order_from_request)
  - [__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_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,53 +30,6 @@
 
 ---
 
-## __experimental_woocommerce_blocks_checkout_order_processed
-
-
-Fires before an order is processed by the Checkout Block/Store API.
-
-```php
-do_action( '__experimental_woocommerce_blocks_checkout_order_processed', \WC_Order $order )
-```
-
-
-**Note: This Hook is experimental and may change or be removed.**
-
-### Description
-
-<p>This hook informs extensions that $order has completed processing and is ready for payment.</p> <p>This is similar to existing core hook woocommerce_checkout_order_processed. 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. |
-
-### Example
-
-```php
-// The action callback function.
-function my_function_callback( $order ) {
-  // Do something with the $order object.
-  $order->save();
-}
-
-add_action( '__experimental_woocommerce_blocks_checkout_order_processed', 'my_function_callback', 10 );
-```
-
-
-### Related
-
-
- - https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/3238
-
-### Source
-
-
-File: [StoreApi/Routes/Checkout.php](../src/StoreApi/Routes/Checkout.php)
-
----
-
 ## __experimental_woocommerce_blocks_checkout_update_order_from_request
 
 
@@ -242,6 +195,50 @@ File: [BlockTypes/Checkout.php](../src/BlockTypes/Checkout.php)
 
 ---
 
+## woocommerce_blocks_checkout_order_processed
+
+
+Fires before an order is processed by the Checkout Block/Store API.
+
+```php
+do_action( 'woocommerce_blocks_checkout_order_processed', \WC_Order $order )
+```
+
+### Description
+
+<p>This hook informs extensions that $order has completed processing and is ready for payment.</p> <p>This is similar to existing core hook woocommerce_checkout_order_processed. 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. |
+
+### Example
+
+```php
+// The action callback function.
+function my_function_callback( $order ) {
+  // Do something with the $order object.
+  $order->save();
+}
+
+add_action( 'woocommerce_blocks_checkout_order_processed', 'my_function_callback', 10 );
+```
+
+
+### Related
+
+
+ - https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/3238
+
+### Source
+
+
+File: [StoreApi/Routes/Checkout.php](../src/StoreApi/Routes/Checkout.php)
+
+---
+
 ## woocommerce_blocks_enqueue_cart_block_scripts_after
 
 

diff --git a/src/StoreApi/Routes/Checkout.php b/src/StoreApi/Routes/Checkout.php
@@ -246,8 +246,33 @@ protected function get_route_post_response( \WP_REST_Request $request ) {
 		 * @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_order_processed instead.
 		 */
-		do_action( '__experimental_woocommerce_blocks_checkout_order_processed', $this->order );
+		do_action_deprecated(
+			'__experimental_woocommerce_blocks_checkout_order_processed',
+			array(
+				$this->order,
+			),
+			'6.3.0',
+			'woocommerce_blocks_checkout_order_processed',
+			'This action was deprecated in WooCommerce Blocks version 6.3.0. Please use woocommerce_blocks_checkout_order_processed instead.'
+		);
+
+		/**
+		 * Fires before an order is processed by the Checkout Block/Store API.
+		 *
+		 * This hook informs extensions that $order has completed processing and is ready for payment.
+		 *
+		 * This is similar to existing core hook woocommerce_checkout_order_processed. 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/3238
+		 * @example See docs/examples/checkout-order-processed.md
+
+		 * @param \WC_Order $order Order object.
+		 */
+		do_action( 'woocommerce_blocks_checkout_order_processed', $this->order );
 
 		/**
 		 * Process the payment and return the results.