From 2289fc70a9dd216c5e8ee604adeae4e8abcc538b Mon Sep 17 00:00:00 2001 From: Leif Singer Date: Wed, 20 Sep 2023 08:48:06 +0200 Subject: [PATCH] Tweak a few comments related to address type (#40110) * Tweak a few comments related to address type * tweak more address type comments * grammar nitpick * still more address type tweaks * appease the linter * Update plugins/woocommerce/includes/wc-template-functions.php Co-authored-by: Corey McKrill <916023+coreymckrill@users.noreply.github.com> --------- Co-authored-by: Corey McKrill <916023+coreymckrill@users.noreply.github.com> --- .../dev-update-address-type-comments | 5 ++ .../includes/class-wc-checkout.php | 2 +- .../includes/class-wc-customer.php | 37 +++++++++------ .../includes/class-wc-form-handler.php | 26 +++++++---- .../woocommerce/includes/class-wc-order.php | 46 +++++++++++++------ .../legacy/abstract-wc-legacy-order.php | 2 +- .../legacy/api/v2/class-wc-api-orders.php | 2 +- .../legacy/api/v3/class-wc-api-orders.php | 2 +- .../class-wc-rest-orders-v1-controller.php | 6 +-- .../class-wc-rest-orders-v2-controller.php | 2 +- .../class-wc-shortcode-my-account.php | 2 +- .../includes/wc-account-functions.php | 6 +-- .../includes/wc-template-functions.php | 2 +- .../PostToOrderAddressTableMigrator.php | 4 +- .../Orders/OrdersTableDataStore.php | 4 +- 15 files changed, 94 insertions(+), 54 deletions(-) create mode 100644 plugins/woocommerce/changelog/dev-update-address-type-comments diff --git a/plugins/woocommerce/changelog/dev-update-address-type-comments b/plugins/woocommerce/changelog/dev-update-address-type-comments new file mode 100644 index 00000000000..bb1a4fd5a34 --- /dev/null +++ b/plugins/woocommerce/changelog/dev-update-address-type-comments @@ -0,0 +1,5 @@ +Significance: patch +Type: tweak +Comment: This change only tweaks a few comments. + + diff --git a/plugins/woocommerce/includes/class-wc-checkout.php b/plugins/woocommerce/includes/class-wc-checkout.php index cd39ca9ef6d..8dc5c20e121 100644 --- a/plugins/woocommerce/includes/class-wc-checkout.php +++ b/plugins/woocommerce/includes/class-wc-checkout.php @@ -1291,7 +1291,7 @@ class WC_Checkout { * Get a posted address field after sanitization and validation. * * @param string $key Field key. - * @param string $type Type of address. Available options: 'billing' or 'shipping'. + * @param string $type Type of address; 'billing' or 'shipping'. * @return string */ public function get_posted_address_data( $key, $type = 'billing' ) { diff --git a/plugins/woocommerce/includes/class-wc-customer.php b/plugins/woocommerce/includes/class-wc-customer.php index 06b262e5439..9074442a2f7 100644 --- a/plugins/woocommerce/includes/class-wc-customer.php +++ b/plugins/woocommerce/includes/class-wc-customer.php @@ -454,18 +454,27 @@ class WC_Customer extends WC_Legacy_Customer { * * @since 3.0.0 * @param string $prop Name of prop to get. - * @param string $address billing or shipping. - * @param string $context What the value is for. Valid values are 'view' and 'edit'. What the value is for. Valid values are view and edit. + * @param string $address_type Type of address; 'billing' or 'shipping'. + * @param string $context What the value is for. Valid values are 'view' and 'edit'. * @return mixed */ - protected function get_address_prop( $prop, $address = 'billing', $context = 'view' ) { + protected function get_address_prop( $prop, $address_type = 'billing', $context = 'view' ) { $value = null; - if ( array_key_exists( $prop, $this->data[ $address ] ) ) { - $value = isset( $this->changes[ $address ][ $prop ] ) ? $this->changes[ $address ][ $prop ] : $this->data[ $address ][ $prop ]; + if ( array_key_exists( $prop, $this->data[ $address_type ] ) ) { + $value = isset( $this->changes[ $address_type ][ $prop ] ) ? $this->changes[ $address_type ][ $prop ] : $this->data[ $address_type ][ $prop ]; if ( 'view' === $context ) { - $value = apply_filters( $this->get_hook_prefix() . $address . '_' . $prop, $value, $this ); + /** + * Filter: 'woocommerce_customer_get_[billing|shipping]_[prop]' + * + * Allow developers to change the returned value for any customer address property. + * + * @since 3.6.0 + * @param string $value The address property value. + * @param WC_Customer $customer The customer object being read. + */ + $value = apply_filters( $this->get_hook_prefix() . $address_type . '_' . $prop, $value, $this ); } } return $value; @@ -920,18 +929,18 @@ class WC_Customer extends WC_Legacy_Customer { * Sets a prop for a setter method. * * @since 3.0.0 - * @param string $prop Name of prop to set. - * @param string $address Name of address to set. billing or shipping. - * @param mixed $value Value of the prop. + * @param string $prop Name of prop to set. + * @param string $address_type Type of address; 'billing' or 'shipping'. + * @param mixed $value Value of the prop. */ - protected function set_address_prop( $prop, $address, $value ) { - if ( array_key_exists( $prop, $this->data[ $address ] ) ) { + protected function set_address_prop( $prop, $address_type, $value ) { + if ( array_key_exists( $prop, $this->data[ $address_type ] ) ) { if ( true === $this->object_read ) { - if ( $value !== $this->data[ $address ][ $prop ] || ( isset( $this->changes[ $address ] ) && array_key_exists( $prop, $this->changes[ $address ] ) ) ) { - $this->changes[ $address ][ $prop ] = $value; + if ( $value !== $this->data[ $address_type ][ $prop ] || ( isset( $this->changes[ $address_type ] ) && array_key_exists( $prop, $this->changes[ $address_type ] ) ) ) { + $this->changes[ $address_type ][ $prop ] = $value; } } else { - $this->data[ $address ][ $prop ] = $value; + $this->data[ $address_type ][ $prop ] = $value; } } } diff --git a/plugins/woocommerce/includes/class-wc-form-handler.php b/plugins/woocommerce/includes/class-wc-form-handler.php index 21d5744ac11..972818b4cda 100644 --- a/plugins/woocommerce/includes/class-wc-form-handler.php +++ b/plugins/woocommerce/includes/class-wc-form-handler.php @@ -103,13 +103,13 @@ class WC_Form_Handler { return; } - $load_address = isset( $wp->query_vars['edit-address'] ) ? wc_edit_address_i18n( sanitize_title( $wp->query_vars['edit-address'] ), true ) : 'billing'; + $address_type = isset( $wp->query_vars['edit-address'] ) ? wc_edit_address_i18n( sanitize_title( $wp->query_vars['edit-address'] ), true ) : 'billing'; - if ( ! isset( $_POST[ $load_address . '_country' ] ) ) { + if ( ! isset( $_POST[ $address_type . '_country' ] ) ) { return; } - $address = WC()->countries->get_address_fields( wc_clean( wp_unslash( $_POST[ $load_address . '_country' ] ) ), $load_address . '_' ); + $address = WC()->countries->get_address_fields( wc_clean( wp_unslash( $_POST[ $address_type . '_country' ] ) ), $address_type . '_' ); foreach ( $address as $key => $field ) { if ( ! isset( $field['type'] ) ) { @@ -138,7 +138,7 @@ class WC_Form_Handler { foreach ( $field['validate'] as $rule ) { switch ( $rule ) { case 'postcode': - $country = wc_clean( wp_unslash( $_POST[ $load_address . '_country' ] ) ); + $country = wc_clean( wp_unslash( $_POST[ $address_type . '_country' ] ) ); $value = wc_format_postcode( $value, $country ); if ( '' !== $value && ! WC_Validation::is_postcode( $value, $country ) ) { @@ -191,12 +191,13 @@ class WC_Form_Handler { * * Allow developers to add custom validation logic and throw an error to prevent save. * + * @since 3.6.0 * @param int $user_id User ID being saved. - * @param string $load_address Type of address e.g. billing or shipping. + * @param string $address_type Type of address; 'billing' or 'shipping'. * @param array $address The address fields. - * @param WC_Customer $customer The customer object being saved. @since 3.6.0 + * @param WC_Customer $customer The customer object being saved. */ - do_action( 'woocommerce_after_save_address_validation', $user_id, $load_address, $address, $customer ); + do_action( 'woocommerce_after_save_address_validation', $user_id, $address_type, $address, $customer ); if ( 0 < wc_notice_count( 'error' ) ) { return; @@ -206,7 +207,16 @@ class WC_Form_Handler { wc_add_notice( __( 'Address changed successfully.', 'woocommerce' ) ); - do_action( 'woocommerce_customer_save_address', $user_id, $load_address ); + /** + * Hook: woocommerce_customer_save_address. + * + * Fires after a customer address has been saved. + * + * @since 3.6.0 + * @param int $user_id User ID being saved. + * @param string $address_type Type of address; 'billing' or 'shipping'. + */ + do_action( 'woocommerce_customer_save_address', $user_id, $address_type ); wp_safe_redirect( wc_get_endpoint_url( 'edit-address', '', wc_get_page_permalink( 'myaccount' ) ) ); exit; diff --git a/plugins/woocommerce/includes/class-wc-order.php b/plugins/woocommerce/includes/class-wc-order.php index 6a1874bcee9..f3550ec7beb 100644 --- a/plugins/woocommerce/includes/class-wc-order.php +++ b/plugins/woocommerce/includes/class-wc-order.php @@ -557,18 +557,27 @@ class WC_Order extends WC_Abstract_Order { * * @since 3.0.0 * @param string $prop Name of prop to get. - * @param string $address billing or shipping. + * @param string $address_type Type of address; 'billing' or 'shipping'. * @param string $context What the value is for. Valid values are view and edit. * @return mixed */ - protected function get_address_prop( $prop, $address = 'billing', $context = 'view' ) { + protected function get_address_prop( $prop, $address_type = 'billing', $context = 'view' ) { $value = null; - if ( array_key_exists( $prop, $this->data[ $address ] ) ) { - $value = isset( $this->changes[ $address ][ $prop ] ) ? $this->changes[ $address ][ $prop ] : $this->data[ $address ][ $prop ]; + if ( array_key_exists( $prop, $this->data[ $address_type ] ) ) { + $value = isset( $this->changes[ $address_type ][ $prop ] ) ? $this->changes[ $address_type ][ $prop ] : $this->data[ $address_type ][ $prop ]; if ( 'view' === $context ) { - $value = apply_filters( $this->get_hook_prefix() . $address . '_' . $prop, $value, $this ); + /** + * Filter: 'woocommerce_order_get_[billing|shipping]_[prop]' + * + * Allow developers to change the returned value for any order address property. + * + * @since 3.6.0 + * @param string $value The address property value. + * @param WC_Order $order The order object being read. + */ + $value = apply_filters( $this->get_hook_prefix() . $address_type . '_' . $prop, $value, $this ); } } return $value; @@ -896,11 +905,20 @@ class WC_Order extends WC_Abstract_Order { * Note: Merges raw data with get_prop data so changes are returned too. * * @since 2.4.0 - * @param string $type Billing or shipping. Anything else besides 'billing' will return shipping address. + * @param string $address_type Type of address; 'billing' or 'shipping'. * @return array The stored address after filter. */ - public function get_address( $type = 'billing' ) { - return apply_filters( 'woocommerce_get_order_address', array_merge( $this->data[ $type ], $this->get_prop( $type, 'view' ) ), $type, $this ); + public function get_address( $address_type = 'billing' ) { + /** + * Filter: 'woocommerce_get_order_address' + * + * Allow developers to change the returned value for an order's billing or shipping address. + * + * @since 2.4.0 + * @param array $address_data The raw address data merged with the data from get_prop. + * @param string $address_type Type of address; 'billing' or 'shipping'. + */ + return apply_filters( 'woocommerce_get_order_address', array_merge( $this->data[ $address_type ], $this->get_prop( $address_type, 'view' ) ), $address_type, $this ); } /** @@ -1067,17 +1085,17 @@ class WC_Order extends WC_Abstract_Order { * * @since 3.0.0 * @param string $prop Name of prop to set. - * @param string $address Name of address to set. billing or shipping. + * @param string $address_type Type of address; 'billing' or 'shipping'. * @param mixed $value Value of the prop. */ - protected function set_address_prop( $prop, $address, $value ) { - if ( array_key_exists( $prop, $this->data[ $address ] ) ) { + protected function set_address_prop( $prop, $address_type, $value ) { + if ( array_key_exists( $prop, $this->data[ $address_type ] ) ) { if ( true === $this->object_read ) { - if ( $value !== $this->data[ $address ][ $prop ] || ( isset( $this->changes[ $address ] ) && array_key_exists( $prop, $this->changes[ $address ] ) ) ) { - $this->changes[ $address ][ $prop ] = $value; + if ( $value !== $this->data[ $address_type ][ $prop ] || ( isset( $this->changes[ $address_type ] ) && array_key_exists( $prop, $this->changes[ $address_type ] ) ) ) { + $this->changes[ $address_type ][ $prop ] = $value; } } else { - $this->data[ $address ][ $prop ] = $value; + $this->data[ $address_type ][ $prop ] = $value; } } } diff --git a/plugins/woocommerce/includes/legacy/abstract-wc-legacy-order.php b/plugins/woocommerce/includes/legacy/abstract-wc-legacy-order.php index 8867096c739..3c2c8791b35 100644 --- a/plugins/woocommerce/includes/legacy/abstract-wc-legacy-order.php +++ b/plugins/woocommerce/includes/legacy/abstract-wc-legacy-order.php @@ -329,7 +329,7 @@ abstract class WC_Abstract_Legacy_Order extends WC_Data { /** * Set the customer address. * @param array $address Address data. - * @param string $type billing or shipping. + * @param string $type Type of address; 'billing' or 'shipping'. */ public function set_address( $address, $type = 'billing' ) { foreach ( $address as $key => $value ) { diff --git a/plugins/woocommerce/includes/legacy/api/v2/class-wc-api-orders.php b/plugins/woocommerce/includes/legacy/api/v2/class-wc-api-orders.php index 937de6e4d35..a8b65f6ef8a 100644 --- a/plugins/woocommerce/includes/legacy/api/v2/class-wc-api-orders.php +++ b/plugins/woocommerce/includes/legacy/api/v2/class-wc-api-orders.php @@ -761,7 +761,7 @@ class WC_API_Orders extends WC_API_Resource { * * @param WC_Order $order * @param array $posted - * @param string $type + * @param string $type Type of address; 'billing' or 'shipping'. */ protected function update_address( $order, $posted, $type = 'billing' ) { foreach ( $posted as $key => $value ) { diff --git a/plugins/woocommerce/includes/legacy/api/v3/class-wc-api-orders.php b/plugins/woocommerce/includes/legacy/api/v3/class-wc-api-orders.php index 4d602a94edb..7ed0870a1fb 100644 --- a/plugins/woocommerce/includes/legacy/api/v3/class-wc-api-orders.php +++ b/plugins/woocommerce/includes/legacy/api/v3/class-wc-api-orders.php @@ -805,7 +805,7 @@ class WC_API_Orders extends WC_API_Resource { * * @param WC_Order $order * @param array $posted - * @param string $type + * @param string $type Type of address; 'billing' or 'shipping'. */ protected function update_address( $order, $posted, $type = 'billing' ) { foreach ( $posted as $key => $value ) { diff --git a/plugins/woocommerce/includes/rest-api/Controllers/Version1/class-wc-rest-orders-v1-controller.php b/plugins/woocommerce/includes/rest-api/Controllers/Version1/class-wc-rest-orders-v1-controller.php index 7cf477b7db9..7e65221c8f5 100644 --- a/plugins/woocommerce/includes/rest-api/Controllers/Version1/class-wc-rest-orders-v1-controller.php +++ b/plugins/woocommerce/includes/rest-api/Controllers/Version1/class-wc-rest-orders-v1-controller.php @@ -593,9 +593,9 @@ class WC_REST_Orders_V1_Controller extends WC_REST_Posts_Controller { /** * Update address. * - * @param WC_Order $order - * @param array $posted - * @param string $type + * @param WC_Order $order Order object. + * @param array $posted Request data. + * @param string $type Type of address; 'billing' or 'shipping'. */ protected function update_address( $order, $posted, $type = 'billing' ) { foreach ( $posted as $key => $value ) { diff --git a/plugins/woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-orders-v2-controller.php b/plugins/woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-orders-v2-controller.php index d8a0a249ac0..8ee7a0edae1 100644 --- a/plugins/woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-orders-v2-controller.php +++ b/plugins/woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-orders-v2-controller.php @@ -804,7 +804,7 @@ class WC_REST_Orders_V2_Controller extends WC_REST_CRUD_Controller { * * @param WC_Order $order Order data. * @param array $posted Posted data. - * @param string $type Address type. + * @param string $type Type of address; 'billing' or 'shipping'. */ protected function update_address( $order, $posted, $type = 'billing' ) { foreach ( $posted as $key => $value ) { diff --git a/plugins/woocommerce/includes/shortcodes/class-wc-shortcode-my-account.php b/plugins/woocommerce/includes/shortcodes/class-wc-shortcode-my-account.php index 3a569201d82..4cfcc85e028 100644 --- a/plugins/woocommerce/includes/shortcodes/class-wc-shortcode-my-account.php +++ b/plugins/woocommerce/includes/shortcodes/class-wc-shortcode-my-account.php @@ -165,7 +165,7 @@ class WC_Shortcode_My_Account { /** * Edit address page. * - * @param string $load_address Type of address to load. + * @param string $load_address Type of address; 'billing' or 'shipping'. */ public static function edit_address( $load_address = 'billing' ) { $current_user = wp_get_current_user(); diff --git a/plugins/woocommerce/includes/wc-account-functions.php b/plugins/woocommerce/includes/wc-account-functions.php index 7cefe49d9eb..61ee51d95ba 100644 --- a/plugins/woocommerce/includes/wc-account-functions.php +++ b/plugins/woocommerce/includes/wc-account-functions.php @@ -309,11 +309,9 @@ function wc_get_account_orders_actions( $order ) { * Get account formatted address. * * @since 3.2.0 - * @param string $address_type Address type. - * Accepts: 'billing' or 'shipping'. - * Default to 'billing'. + * @param string $address_type Type of address; 'billing' or 'shipping'. * @param int $customer_id Customer ID. - * Default to 0. + * Defaults to 0. * @return string */ function wc_get_account_formatted_address( $address_type = 'billing', $customer_id = 0 ) { diff --git a/plugins/woocommerce/includes/wc-template-functions.php b/plugins/woocommerce/includes/wc-template-functions.php index d82d8df4063..678cd1ac361 100644 --- a/plugins/woocommerce/includes/wc-template-functions.php +++ b/plugins/woocommerce/includes/wc-template-functions.php @@ -3295,7 +3295,7 @@ if ( ! function_exists( 'woocommerce_account_edit_address' ) ) { /** * My Account > Edit address template. * - * @param string $type Address type. + * @param string $type Type of address; 'billing' or 'shipping'. */ function woocommerce_account_edit_address( $type ) { $type = wc_edit_address_i18n( sanitize_title( $type ), true ); diff --git a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderAddressTableMigrator.php b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderAddressTableMigrator.php index 31cd9d09b35..699e132fb06 100644 --- a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderAddressTableMigrator.php +++ b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderAddressTableMigrator.php @@ -16,7 +16,7 @@ use Automattic\WooCommerce\Internal\DataStores\Orders\OrdersTableDataStore; */ class PostToOrderAddressTableMigrator extends MetaToCustomTableMigrator { /** - * Type of addresses being migrated, could be billing|shipping. + * Type of addresses being migrated; 'billing' or 'shipping'. * * @var $type */ @@ -25,7 +25,7 @@ class PostToOrderAddressTableMigrator extends MetaToCustomTableMigrator { /** * PostToOrderAddressTableMigrator constructor. * - * @param string $type Type of addresses being migrated, could be billing|shipping. + * @param string $type Type of address being migrated; 'billing' or 'shipping'. */ public function __construct( $type ) { $this->type = $type; diff --git a/plugins/woocommerce/src/Internal/DataStores/Orders/OrdersTableDataStore.php b/plugins/woocommerce/src/Internal/DataStores/Orders/OrdersTableDataStore.php index dc7d37f2bc0..71d66846787 100644 --- a/plugins/woocommerce/src/Internal/DataStores/Orders/OrdersTableDataStore.php +++ b/plugins/woocommerce/src/Internal/DataStores/Orders/OrdersTableDataStore.php @@ -537,7 +537,7 @@ class OrdersTableDataStore extends \Abstract_WC_Order_Data_Store_CPT implements /** * Helper function to get alias for address table, this is used in select query. * - * @param string $type Address type. + * @param string $type Type of address; 'billing' or 'shipping'. * * @return string Alias. */ @@ -1665,7 +1665,7 @@ FROM $order_meta_table /** * Helper method to generate join and select query for address table. * - * @param string $address_type Type of address. Typically will be `billing` or `shipping`. + * @param string $address_type Type of address; 'billing' or 'shipping'. * @param string $order_table_alias Alias of order table to use. * @param string $address_table_alias Alias for address table to use. *