From a1a8c1c36204f444dcb4b7bb492077a4661d3037 Mon Sep 17 00:00:00 2001 From: Thomas Roberts <5656702+opr@users.noreply.github.com> Date: Tue, 2 Nov 2021 08:46:54 +0000 Subject: [PATCH] Graduate `__experimental_woocommerce_blocks_checkout_order_processed` action to stable (#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 --- bin/hook-docs/data/actions.json | 62 ++++++------- ...ature-flags-and-experimental-interfaces.md | 2 +- docs/examples/checkout-order-processed.md | 2 +- docs/extensibility/actions.md | 93 +++++++++---------- src/StoreApi/Routes/Checkout.php | 27 +++++- 5 files changed, 102 insertions(+), 84 deletions(-) diff --git a/bin/hook-docs/data/actions.json b/bin/hook-docs/data/actions.json index e2c756c207a..dd2ec957bc0 100644 --- 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": "

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:

" - } - }, { "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": "

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:

" + } + }, { "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 index 784a78bf356..598fd458d51 100644 --- 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 index fd2bbdfdc74..b3260a288b2 100644 --- 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 index b72f14fc525..60d706e0659 100644 --- a/docs/extensibility/actions.md +++ b/docs/extensibility/actions.md @@ -7,7 +7,6 @@ ## 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) @@ -15,6 +14,7 @@ - [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 - -

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:

- -### 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 + +

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:

+ +### 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 index 6c8603f79c1..eb214a93f07 100644 --- 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.