location => $fields ) { if ( in_array( $field_key, $fields, true ) ) { return $location; } } return ''; } /** * Sanitize an additional field against any custom sanitization rules. * * @since 8.7.0 * @param string $field_key The key of the field. * @param mixed $field_value The value of the field. * @return mixed */ public function sanitize_field( $field_key, $field_value ) { try { $field = $this->additional_fields[ $field_key ] ?? null; if ( $field ) { $field_value = call_user_func( $field['sanitize_callback'], $field_value, $field ); } /** * Allow custom sanitization of an additional field. * * @param mixed $field_value The value of the field being sanitized. * @param string $field_key Key of the field being sanitized. * * @since 8.7.0 */ return apply_filters( '__experimental_woocommerce_blocks_sanitize_additional_field', $field_value, $field_key ); } catch ( \Throwable $e ) { // One of the filters errored so skip it. This allows the checkout process to continue. // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_trigger_error trigger_error( sprintf( 'Field sanitization for %s encountered an error. %s', esc_html( $field_key ), esc_html( $e->getMessage() ) ), E_USER_WARNING ); } return $field_value; } /** * Validate an additional field against any custom validation rules. * * @since 8.6.0 * * @param string $field_key The key of the field. * @param mixed $field_value The value of the field. * @return WP_Error */ public function validate_field( $field_key, $field_value ) { $errors = new WP_Error(); try { $field = $this->additional_fields[ $field_key ] ?? null; if ( $field ) { $validation = call_user_func( $field['validate_callback'], $field_value, $field ); if ( is_wp_error( $validation ) ) { $errors->merge_from( $validation ); } } /** * Pass an error object to allow validation of an additional field. * * @param WP_Error $errors A WP_Error object that extensions may add errors to. * @param string $field_key Key of the field being sanitized. * @param mixed $field_value The value of the field being validated. * * @since 8.7.0 */ do_action( '__experimental_woocommerce_blocks_validate_additional_field', $errors, $field_key, $field_value ); } catch ( \Throwable $e ) { // One of the filters errored so skip them and validate the field. This allows the checkout process to continue. // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_trigger_error trigger_error( sprintf( 'Field validation for %s encountered an error. %s', esc_html( $field_key ), esc_html( $e->getMessage() ) ), E_USER_WARNING ); } return $errors; } /** * Update the default locale with additional fields without country limitations. * * @param array $locale The locale to update. * @return mixed */ public function update_default_locale_with_fields( $locale ) { foreach ( $this->fields_locations['address'] as $field_id => $additional_field ) { if ( empty( $locale[ $field_id ] ) ) { $locale[ $field_id ] = $additional_field; } } return $locale; } /** * Returns an array of fields keys for the address group. * * @return array An array of fields keys. */ public function get_address_fields_keys() { return $this->fields_locations['address']; } /** * Returns an array of fields keys for the contact group. * * @return array An array of fields keys. */ public function get_contact_fields_keys() { return $this->fields_locations['contact']; } /** * Returns an array of fields keys for the additional area group. * * @return array An array of fields keys. */ public function get_additional_fields_keys() { return $this->fields_locations['additional']; } /** * Returns an array of fields for a given group. * * @param string $location The location to get fields for (address|contact|additional). * @return array An array of fields definitions. */ public function get_fields_for_location( $location ) { if ( in_array( $location, array_keys( $this->fields_locations ), true ) ) { $order_fields_keys = $this->fields_locations[ $location ]; return array_filter( $this->get_additional_fields(), function( $key ) use ( $order_fields_keys ) { return in_array( $key, $order_fields_keys, true ); }, ARRAY_FILTER_USE_KEY ); } return []; } /** * Validates a set of fields for a given location against custom validation rules. * * @param array $fields Array of key value pairs of field values to validate. * @param string $location The location being validated (address|contact|additional). * @param string $group The group to get the field value for (shipping|billing|'') in which '' refers to the additional group. * @return WP_Error */ public function validate_fields_for_location( $fields, $location, $group = '' ) { $errors = new WP_Error(); try { /** * Pass an error object to allow validation of an additional field. * * @param WP_Error $errors A WP_Error object that extensions may add errors to. * @param mixed $fields List of fields (key value pairs) in this location. * @param string $group The group of this location (shipping|billing|''). * * @since 8.7.0 */ do_action( '__experimental_woocommerce_blocks_validate_location_' . $location . '_fields', $errors, $fields, $group ); } catch ( \Throwable $e ) { // One of the filters errored so skip them. This allows the checkout process to continue. // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_trigger_error trigger_error( sprintf( 'The action %s encountered an error. The field location %s may not have any custom validation applied to it. %s', esc_html( 'woocommerce_blocks_validate_' . $location . '_fields' ), esc_html( $location ), esc_html( $e->getMessage() ) ), E_USER_WARNING ); } return $errors; } /** * Validates a field to check it belongs to the given location and is valid according to its registration. * * This does not apply any custom validation rules on the value. * * @param string $key The field key. * @param mixed $value The field value. * @param string $location The location to validate the field for (address|contact|additional). * * @return true|WP_Error True if the field is valid, a WP_Error otherwise. */ public function validate_field_for_location( $key, $value, $location ) { if ( ! $this->is_field( $key ) ) { return new WP_Error( 'woocommerce_blocks_checkout_field_invalid', \sprintf( // translators: % is field key. __( 'The field %s is invalid.', 'woocommerce' ), $key ) ); } if ( ! in_array( $key, $this->fields_locations[ $location ], true ) ) { return new WP_Error( 'woocommerce_blocks_checkout_field_invalid_location', \sprintf( // translators: %1$s is field key, %2$s location. __( 'The field %1$s is invalid for the location %2$s.', 'woocommerce' ), $key, $location ) ); } $field = $this->additional_fields[ $key ]; if ( ! empty( $field['required'] ) && empty( $value ) ) { return new WP_Error( 'woocommerce_blocks_checkout_field_required', \sprintf( // translators: %s is field key. __( 'The field %s is required.', 'woocommerce' ), $key ) ); } return true; } /** * Returns true if the given key is a valid field. * * @param string $key The field key. * * @return bool True if the field is valid, false otherwise. */ public function is_field( $key ) { return array_key_exists( $key, $this->additional_fields ); } /** * Persists a field value for a given order. This would also optionally set the field value on the customer object if the order is linked to a registered customer. * * @param string $key The field key. * @param mixed $value The field value. * @param WC_Order $order The order to persist the field for. * @param bool $set_customer Whether to set the field value on the customer or not. * * @return void */ public function persist_field_for_order( $key, $value, $order, $set_customer = true ) { $this->set_array_meta( $key, $value, $order ); if ( $set_customer && $order->get_customer_id() ) { $customer = new WC_Customer( $order->get_customer_id() ); $this->persist_field_for_customer( $key, $value, $customer ); } } /** * Persists a field value for a given customer. * * @param string $key The field key. * @param mixed $value The field value. * @param WC_Customer $customer The customer to persist the field for. * * @return void */ public function persist_field_for_customer( $key, $value, $customer ) { $this->set_array_meta( $key, $value, $customer ); } /** * Sets a field value in an array meta, supporting routing things to billing, shipping, or additional fields, based on a prefix for the key. * * @param string $key The field key. * @param mixed $value The field value. * @param WC_Customer|WC_Order $object The object to set the field value for. * * @return void */ private function set_array_meta( $key, $value, $object ) { $meta_key = ''; if ( 0 === strpos( $key, '/billing/' ) ) { $meta_key = self::BILLING_FIELDS_KEY; $key = str_replace( '/billing/', '', $key ); } elseif ( 0 === strpos( $key, '/shipping/' ) ) { $meta_key = self::SHIPPING_FIELDS_KEY; $key = str_replace( '/shipping/', '', $key ); } else { $meta_key = self::ADDITIONAL_FIELDS_KEY; } $meta_data = $object->get_meta( $meta_key, true ); if ( ! is_array( $meta_data ) ) { $meta_data = array(); } $meta_data[ $key ] = $value; // Replacing all meta using `add_meta_data`. For some reason `update_meta_data` causes duplicate keys. $object->add_meta_data( $meta_key, $meta_data, true ); } /** * Returns a field value for a given object. * * @param string $key The field key. * @param WC_Customer $customer The customer to get the field value for. * @param string $group The group to get the field value for (shipping|billing|'') in which '' refers to the additional group. * * @return mixed The field value. */ public function get_field_from_customer( $key, $customer, $group = '' ) { return $this->get_field_from_object( $key, $customer, $group ); } /** * Returns a field value for a given order. * * @param string $field The field key. * @param WC_Order $order The order to get the field value for. * @param string $group The group to get the field value for (shipping|billing|'') in which '' refers to the additional group. * * @return mixed The field value. */ public function get_field_from_order( $field, $order, $group = '' ) { return $this->get_field_from_object( $field, $order, $group ); } /** * Returns a field value for a given object. * * @param string $key The field key. * @param WC_Customer|WC_Order $object The customer to get the field value for. * @param string $group The group to get the field value for (shipping|billing|'') in which '' refers to the additional group. * * @return mixed The field value. */ private function get_field_from_object( $key, $object, $group = '' ) { $meta_key = ''; if ( 0 === strpos( $key, '/billing/' ) || 'billing' === $group ) { $meta_key = self::BILLING_FIELDS_KEY; $key = str_replace( '/billing/', '', $key ); } elseif ( 0 === strpos( $key, '/shipping/' ) || 'shipping' === $group ) { $meta_key = self::SHIPPING_FIELDS_KEY; $key = str_replace( '/shipping/', '', $key ); } else { $meta_key = self::ADDITIONAL_FIELDS_KEY; } $meta_data = $object->get_meta( $meta_key, true ); if ( ! is_array( $meta_data ) ) { return ''; } if ( ! isset( $meta_data[ $key ] ) ) { return ''; } return $meta_data[ $key ]; } /** * Returns an array of all fields values for a given customer. * * @param WC_Customer $customer The customer to get the fields for. * @param bool $all Whether to return all fields or only the ones that are still registered. Default false. * * @return array An array of fields. */ public function get_all_fields_from_customer( $customer, $all = false ) { $meta_data = array( 'billing' => array(), 'shipping' => array(), 'additional' => array(), ); if ( $customer instanceof WC_Customer ) { $meta_data['billing'] = $customer->get_meta( self::BILLING_FIELDS_KEY, true ); $meta_data['shipping'] = $customer->get_meta( self::SHIPPING_FIELDS_KEY, true ); $meta_data['additional'] = $customer->get_meta( self::ADDITIONAL_FIELDS_KEY, true ); } return $this->format_meta_data( $meta_data, $all ); } /** * Returns an array of all fields values for a given order. * * @param WC_Order $order The order to get the fields for. * @param bool $all Whether to return all fields or only the ones that are still registered. Default false. * * @return array An array of fields. */ public function get_all_fields_from_order( $order, $all = false ) { $meta_data = array( 'billing' => array(), 'shipping' => array(), 'additional' => array(), ); if ( $order instanceof WC_Order ) { $meta_data['billing'] = $order->get_meta( self::BILLING_FIELDS_KEY, true ); $meta_data['shipping'] = $order->get_meta( self::SHIPPING_FIELDS_KEY, true ); $meta_data['additional'] = $order->get_meta( self::ADDITIONAL_FIELDS_KEY, true ); } return $this->format_meta_data( $meta_data, $all ); } /** * Returns an array of all fields values for a given meta object. It would add the billing or shipping prefix to the keys. * * @param array $meta The meta data to format. * @param bool $all Whether to return all fields or only the ones that are still registered. Default false. * * @return array An array of fields. */ private function format_meta_data( $meta, $all = false ) { $billing_fields = $meta['billing'] ?? array(); $shipping_fields = $meta['shipping'] ?? array(); $additional_fields = $meta['additional'] ?? array(); $fields = array(); if ( is_array( $billing_fields ) ) { foreach ( $billing_fields as $key => $value ) { if ( ! $all && ! $this->is_field( $key ) ) { continue; } $fields[ '/billing/' . $key ] = $value; } } if ( is_array( $shipping_fields ) ) { foreach ( $shipping_fields as $key => $value ) { if ( ! $all && ! $this->is_field( $key ) ) { continue; } $fields[ '/shipping/' . $key ] = $value; } } if ( is_array( $additional_fields ) ) { foreach ( $additional_fields as $key => $value ) { if ( ! $all && ! $this->is_field( $key ) ) { continue; } $fields[ $key ] = $value; } } return $fields; } /** * From a set of fields, returns only the ones that should be saved to the customer. * For now, this only supports fields in address location. * * @param array $fields The fields to filter. * @return array The filtered fields. */ public function filter_fields_for_customer( $fields ) { $customer_fields_keys = array_merge( $this->get_address_fields_keys(), $this->get_contact_fields_keys(), ); return array_filter( $fields, function( $key ) use ( $customer_fields_keys ) { if ( 0 === strpos( $key, '/billing/' ) ) { $key = str_replace( '/billing/', '', $key ); } elseif ( 0 === strpos( $key, '/shipping/' ) ) { $key = str_replace( '/shipping/', '', $key ); } return in_array( $key, $customer_fields_keys, true ); }, ARRAY_FILTER_USE_KEY ); } /** * From a set of fields, returns only the ones for a given location. * * @param array $fields The fields to filter. * @param string $location The location to validate the field for (address|contact|additional). * @return array The filtered fields. */ public function filter_fields_for_location( $fields, $location ) { return array_filter( $fields, function( $key ) use ( $location ) { if ( 0 === strpos( $key, '/billing/' ) ) { $key = str_replace( '/billing/', '', $key ); } elseif ( 0 === strpos( $key, '/shipping/' ) ) { $key = str_replace( '/shipping/', '', $key ); } return $this->is_field( $key ) && $this->get_field_location( $key ) === $location; }, ARRAY_FILTER_USE_KEY ); } /** * Filter fields for order confirmation. * * @param array $fields The fields to filter. * @return array The filtered fields. */ public function filter_fields_for_order_confirmation( $fields ) { return array_filter( $fields, function( $field ) { return ! empty( $field['show_in_order_confirmation'] ); } ); } /** * Get additional fields for an order. * * @param WC_Order $order Order object. * @param string $location The location to get fields for (address|contact|additional). * @param string $group The group to get the field value for (shipping|billing|'') in which '' refers to the additional group. * @param string $context The context to get the field value for (edit|view). * @return array An array of fields definitions as well as their values formatted for display. */ public function get_order_additional_fields_with_values( $order, $location, $group = '', $context = 'edit' ) { $fields = $this->get_fields_for_location( $location ); $fields_with_values = array(); foreach ( $fields as $field_key => $field ) { $value = $this->get_field_from_order( $field_key, $order, $group ); if ( '' === $value || null === $value ) { continue; } if ( 'view' === $context ) { $value = $this->format_additional_field_value( $value, $field ); } $field['value'] = $value; $fields_with_values[ $field_key ] = $field; } return $fields_with_values; } /** * Formats a raw field value for display based on its type definition. * * @param string $value Value to format. * @param array $field Additional field definition. * @return string */ public function format_additional_field_value( $value, $field ) { if ( 'checkbox' === $field['type'] ) { $value = $value ? __( 'Yes', 'woocommerce' ) : __( 'No', 'woocommerce' ); } if ( 'select' === $field['type'] ) { $options = array_column( $field['options'], 'label', 'value' ); $value = isset( $options[ $value ] ) ? $options[ $value ] : $value; } return $value; } }