CheckoutFields
in package
Service class managing checkout fields and its related extensibility points.
Table of Contents
- ADDITIONAL_FIELDS_PREFIX = '_wc_additional/'
- Additional fields meta key.
- BILLING_FIELDS_PREFIX = '_wc_billing/'
- Billing fields meta key.
- OTHER_FIELDS_PREFIX = '_wc_other/'
- Other fields meta key.
- SHIPPING_FIELDS_PREFIX = '_wc_shipping/'
- Shipping fields meta key.
- $groups : array<string|int, mixed>
- Groups of fields to be saved.
- $additional_fields : array<string|int, mixed>
- Additional checkout fields.
- $asset_data_registry : AssetDataRegistry
- Instance of the asset data registry.
- $core_fields : array<string|int, mixed>
- Core checkout fields.
- $fields_locations : array<string|int, mixed>
- Fields locations.
- $supported_field_types : array<string|int, mixed>
- Supported field types
- __construct() : mixed
- Sets up core fields.
- add_fields_data() : mixed
- Add fields data to the asset data registry.
- add_session_meta_keys() : array<string|int, mixed>
- Add session meta keys.
- default_sanitize_callback() : mixed
- If a field does not declare a sanitization callback, this is the default sanitization callback.
- default_validate_callback() : WP_Error|void
- If a field does not declare a validation callback, this is the default validation callback.
- filter_fields_for_location() : array<string|int, mixed>
- From a set of fields, returns only the ones for a given location.
- filter_fields_for_order_confirmation() : array<string|int, mixed>
- Filter fields for order confirmation.
- format_additional_field_value() : string
- Formats a raw field value for display based on its type definition.
- get_additional_fields() : array<string|int, mixed>
- Returns an array of all additional fields.
- get_additional_fields_keys() : array<string|int, mixed>
- Returns an array of fields keys for the additional area location.
- get_address_fields_keys() : array<string|int, mixed>
- Returns an array of fields keys for the address location.
- get_all_fields_from_object() : array<string|int, mixed>
- Returns an array of all fields values for a given object in a group.
- get_contact_fields_keys() : array<string|int, mixed>
- Returns an array of fields keys for the contact location.
- get_core_fields() : array<string|int, mixed>
- Returns an array of all core fields.
- get_field_from_object() : mixed
- Returns a field value for a given object.
- get_field_location() : string
- Gets the location of a field.
- get_fields_for_group() : array<string|int, string>
- Returns all fields key for a given group.
- get_fields_for_location() : array<string|int, mixed>
- Returns an array of fields for a given location.
- get_group_key() : string
- Returns a group meta prefix based on its name.
- get_group_name() : string
- Returns a group name based on passed group key.
- get_order_additional_fields_with_values() : array<string|int, mixed>
- Get additional fields for an order.
- get_order_fields_keys() : array<string|int, mixed>
- Returns an array of fields keys for the additional area group.
- init() : mixed
- Initialize hooks.
- is_customer_field() : bool
- Returns true if the given key is a valid customer field.
- is_field() : bool
- Returns true if the given key is a valid field.
- persist_field_for_customer() : void
- Persists a field value for a given customer.
- persist_field_for_order() : void
- 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.
- register_checkout_field() : WP_Error|void
- Registers an additional field for Checkout.
- sanitize_field() : mixed
- Sanitize an additional field against any custom sanitization rules.
- sync_customer_additional_fields_with_order() : mixed
- Copies additional fields from an order to a customer.
- sync_order_additional_fields_with_customer() : mixed
- Copies additional fields from a customer to an order.
- update_default_locale_with_fields() : mixed
- Update the default locale with additional fields without country limitations.
- validate_field() : WP_Error
- Validate an additional field against any custom validation rules.
- validate_field_for_location() : true|WP_Error
- Validates a field to check it belongs to the given location and is valid according to its registration.
- validate_fields_for_location() : WP_Error
- Validates a set of fields for a given location against custom validation rules.
- process_checkbox_field() : array<string|int, mixed>|false
- Processes the options for a checkbox field and returns the new field_options array.
- process_select_field() : array<string|int, mixed>|false
- Processes the options for a select field and returns the new field_options array.
- register_field_attributes() : array<string|int, mixed>
- Processes the attributes supplied during field registration.
- set_array_meta() : void
- Sets a field value in an array meta, supporting routing things to billing, shipping, or additional fields, based on a prefix for the key.
- validate_options() : bool
- Validates the "base" options (id, label, location) and shows warnings if they're not supplied.
Constants
ADDITIONAL_FIELDS_PREFIX
Additional fields meta key.
public
string
ADDITIONAL_FIELDS_PREFIX
= '_wc_additional/'
Tags
BILLING_FIELDS_PREFIX
Billing fields meta key.
public
string
BILLING_FIELDS_PREFIX
= '_wc_billing/'
OTHER_FIELDS_PREFIX
Other fields meta key.
public
string
OTHER_FIELDS_PREFIX
= '_wc_other/'
SHIPPING_FIELDS_PREFIX
Shipping fields meta key.
public
string
SHIPPING_FIELDS_PREFIX
= '_wc_shipping/'
Properties
$groups
Groups of fields to be saved.
protected
array<string|int, mixed>
$groups
= ['billing', 'shipping', 'other']
$additional_fields
Additional checkout fields.
private
array<string|int, mixed>
$additional_fields
= []
$asset_data_registry
Instance of the asset data registry.
private
AssetDataRegistry
$asset_data_registry
$core_fields
Core checkout fields.
private
array<string|int, mixed>
$core_fields
$fields_locations
Fields locations.
private
array<string|int, mixed>
$fields_locations
$supported_field_types
Supported field types
private
array<string|int, mixed>
$supported_field_types
= ['text', 'select', 'checkbox']
Methods
__construct()
Sets up core fields.
public
__construct(AssetDataRegistry $asset_data_registry) : mixed
Parameters
- $asset_data_registry : AssetDataRegistry
-
Instance of the asset data registry.
Return values
mixed —add_fields_data()
Add fields data to the asset data registry.
public
add_fields_data() : mixed
Return values
mixed —add_session_meta_keys()
Add session meta keys.
public
add_session_meta_keys(array<string|int, mixed> $keys) : array<string|int, mixed>
This is an allow-list of meta data keys which we want to store in session.
Parameters
- $keys : array<string|int, mixed>
-
Session meta keys.
Return values
array<string|int, mixed> —default_sanitize_callback()
If a field does not declare a sanitization callback, this is the default sanitization callback.
public
default_sanitize_callback(mixed $value, array<string|int, mixed> $field) : mixed
Parameters
- $value : mixed
-
Value to sanitize.
- $field : array<string|int, mixed>
-
Field data.
Return values
mixed —default_validate_callback()
If a field does not declare a validation callback, this is the default validation callback.
public
default_validate_callback(mixed $value, array<string|int, mixed> $field) : WP_Error|void
Parameters
- $value : mixed
-
Value to sanitize.
- $field : array<string|int, mixed>
-
Field data.
Return values
WP_Error|void — If there is a validation error, return an WP_Error object.filter_fields_for_location()
From a set of fields, returns only the ones for a given location.
public
filter_fields_for_location(array<string|int, mixed> $fields, string $location) : array<string|int, mixed>
Parameters
- $fields : array<string|int, mixed>
-
The fields to filter.
- $location : string
-
The location to validate the field for (address|contact|order).
Return values
array<string|int, mixed> — The filtered fields.filter_fields_for_order_confirmation()
Filter fields for order confirmation.
public
filter_fields_for_order_confirmation(array<string|int, mixed> $fields) : array<string|int, mixed>
Parameters
- $fields : array<string|int, mixed>
-
The fields to filter.
Return values
array<string|int, mixed> — The filtered fields.format_additional_field_value()
Formats a raw field value for display based on its type definition.
public
format_additional_field_value(string $value, array<string|int, mixed> $field) : string
Parameters
- $value : string
-
Value to format.
- $field : array<string|int, mixed>
-
Additional field definition.
Return values
string —get_additional_fields()
Returns an array of all additional fields.
public
get_additional_fields() : array<string|int, mixed>
Return values
array<string|int, mixed> — An array of fields.get_additional_fields_keys()
Returns an array of fields keys for the additional area location.
public
get_additional_fields_keys() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> — An array of fields keys.get_address_fields_keys()
Returns an array of fields keys for the address location.
public
get_address_fields_keys() : array<string|int, mixed>
Return values
array<string|int, mixed> — An array of fields keys.get_all_fields_from_object()
Returns an array of all fields values for a given object in a group.
public
get_all_fields_from_object(WC_Data $wc_object[, string $group = 'other' ][, bool $all = false ]) : array<string|int, mixed>
Parameters
- $wc_object : WC_Data
-
The object or order to get the fields for.
- $group : string = 'other'
-
The group to get the fields for (shipping|billing|other).
- $all : bool = false
-
Whether to return all fields or only the ones that are still registered. Default false.
Return values
array<string|int, mixed> — An array of fields.get_contact_fields_keys()
Returns an array of fields keys for the contact location.
public
get_contact_fields_keys() : array<string|int, mixed>
Return values
array<string|int, mixed> — An array of fields keys.get_core_fields()
Returns an array of all core fields.
public
get_core_fields() : array<string|int, mixed>
Return values
array<string|int, mixed> — An array of fields.get_field_from_object()
Returns a field value for a given object.
public
get_field_from_object(string $key, WC_Customer|WC_Order $wc_object[, string $group = 'other' ]) : mixed
Parameters
- $key : string
-
The field key.
- $wc_object : WC_Customer|WC_Order
-
The customer or order to get the field value for.
- $group : string = 'other'
-
The group to get the field value for (shipping|billing|other).
Return values
mixed — The field value.get_field_location()
Gets the location of a field.
public
get_field_location(string $field_key) : string
Parameters
- $field_key : string
-
The key of the field to get the location for.
Return values
string — The location of the field.get_fields_for_group()
Returns all fields key for a given group.
public
get_fields_for_group([string $group = 'other' ]) : array<string|int, string>
Parameters
- $group : string = 'other'
-
The group to get the key for (shipping|billing|other).
Return values
array<string|int, string> — Field keys.get_fields_for_location()
Returns an array of fields for a given location.
public
get_fields_for_location(string $location) : array<string|int, mixed>
Parameters
- $location : string
-
The location to get fields for (address|contact|order).
Return values
array<string|int, mixed> — An array of fields definitions.get_group_key()
Returns a group meta prefix based on its name.
public
static get_group_key(string $group_name) : string
Parameters
- $group_name : string
-
The group name (billing|shipping|other).
Return values
string — The group meta prefix.get_group_name()
Returns a group name based on passed group key.
public
static get_group_name(string $group_key) : string
Parameters
- $group_key : string
-
The group name (_wc_billing|_wc_shipping|_wc_other).
Return values
string — The group meta prefix.get_order_additional_fields_with_values()
Get additional fields for an order.
public
get_order_additional_fields_with_values(WC_Order $order, string $location[, string $group = 'other' ][, string $context = 'edit' ]) : array<string|int, mixed>
Parameters
- $order : WC_Order
-
Order object.
- $location : string
-
The location to get fields for (address|contact|order).
- $group : string = 'other'
-
The group to get the field value for (shipping|billing|other).
- $context : string = 'edit'
-
The context to get the field value for (edit|view).
Return values
array<string|int, mixed> — An array of fields definitions as well as their values formatted for display.get_order_fields_keys()
Returns an array of fields keys for the additional area group.
public
get_order_fields_keys() : array<string|int, mixed>
Return values
array<string|int, mixed> — An array of fields keys.init()
Initialize hooks.
public
init() : mixed
Return values
mixed —is_customer_field()
Returns true if the given key is a valid customer field.
public
is_customer_field(string $key) : bool
Customer fields are fields saved to the customer data, like address and contact fields.
Parameters
- $key : string
-
The field key.
Return values
bool — True if the field is valid, false otherwise.is_field()
Returns true if the given key is a valid field.
public
is_field(string $key) : bool
Parameters
- $key : string
-
The field key.
Return values
bool — True if the field is valid, false otherwise.persist_field_for_customer()
Persists a field value for a given customer.
public
persist_field_for_customer(string $key, mixed $value, WC_Customer $customer[, string $group = 'other' ]) : void
Parameters
- $key : string
-
The field key.
- $value : mixed
-
The field value.
- $customer : WC_Customer
-
The customer to persist the field for.
- $group : string = 'other'
-
The group to persist the field for (shipping|billing|other).
Return values
void —persist_field_for_order()
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.
public
persist_field_for_order(string $key, mixed $value, WC_Order $order[, string $group = 'other' ][, bool $set_customer = true ]) : void
Parameters
- $key : string
-
The field key.
- $value : mixed
-
The field value.
- $order : WC_Order
-
The order to persist the field for.
- $group : string = 'other'
-
The group to persist the field for (shipping|billing|other).
- $set_customer : bool = true
-
Whether to set the field value on the customer or not.
Return values
void —register_checkout_field()
Registers an additional field for Checkout.
public
register_checkout_field(array<string|int, mixed> $options) : WP_Error|void
Parameters
- $options : array<string|int, mixed>
-
The field options.
Return values
WP_Error|void — True if the field was registered, a WP_Error otherwise.sanitize_field()
Sanitize an additional field against any custom sanitization rules.
public
sanitize_field(string $field_key, mixed $field_value) : mixed
Parameters
- $field_key : string
-
The key of the field.
- $field_value : mixed
-
The value of the field.
Tags
Return values
mixed —sync_customer_additional_fields_with_order()
Copies additional fields from an order to a customer.
public
sync_customer_additional_fields_with_order(WC_Order $order, WC_Customer $customer) : mixed
Parameters
- $order : WC_Order
-
The order to sync the fields for.
- $customer : WC_Customer
-
The customer to sync the fields for.
Return values
mixed —sync_order_additional_fields_with_customer()
Copies additional fields from a customer to an order.
public
sync_order_additional_fields_with_customer(WC_Order $order, WC_Customer $customer) : mixed
Parameters
- $order : WC_Order
-
The order to sync the fields for.
- $customer : WC_Customer
-
The customer to sync the fields for.
Return values
mixed —update_default_locale_with_fields()
Update the default locale with additional fields without country limitations.
public
update_default_locale_with_fields(array<string|int, mixed> $locale) : mixed
Parameters
- $locale : array<string|int, mixed>
-
The locale to update.
Return values
mixed —validate_field()
Validate an additional field against any custom validation rules.
public
validate_field(string $field_key, mixed $field_value) : WP_Error
Parameters
- $field_key : string
-
The key of the field.
- $field_value : mixed
-
The value of the field.
Tags
Return values
WP_Error —validate_field_for_location()
Validates a field to check it belongs to the given location and is valid according to its registration.
public
validate_field_for_location(string $key, mixed $value, string $location) : true|WP_Error
This does not apply any custom validation rules on the value.
Parameters
- $key : string
-
The field key.
- $value : mixed
-
The field value.
- $location : string
-
The location to validate the field for (address|contact|order).
Return values
true|WP_Error — True if the field is valid, a WP_Error otherwise.validate_fields_for_location()
Validates a set of fields for a given location against custom validation rules.
public
validate_fields_for_location(array<string|int, mixed> $fields, string $location[, string $group = 'other' ]) : WP_Error
Parameters
- $fields : array<string|int, mixed>
-
Array of key value pairs of field values to validate.
- $location : string
-
The location being validated (address|contact|order).
- $group : string = 'other'
-
The group to get the field value for (shipping|billing|other).
Return values
WP_Error —process_checkbox_field()
Processes the options for a checkbox field and returns the new field_options array.
private
process_checkbox_field(array<string|int, mixed> $field_data, array<string|int, mixed> $options) : array<string|int, mixed>|false
Parameters
- $field_data : array<string|int, mixed>
-
The field data array to be updated.
- $options : array<string|int, mixed>
-
The options supplied during field registration.
Return values
array<string|int, mixed>|false — The updated $field_data array or false if an error was encountered.process_select_field()
Processes the options for a select field and returns the new field_options array.
private
process_select_field(array<string|int, mixed> $field_data, array<string|int, mixed> $options) : array<string|int, mixed>|false
Parameters
- $field_data : array<string|int, mixed>
-
The field data array to be updated.
- $options : array<string|int, mixed>
-
The options supplied during field registration.
Return values
array<string|int, mixed>|false — The updated $field_data array or false if an error was encountered.register_field_attributes()
Processes the attributes supplied during field registration.
private
register_field_attributes(array<string|int, mixed> $id, array<string|int, mixed> $attributes) : array<string|int, mixed>
Parameters
- $id : array<string|int, mixed>
-
The field ID.
- $attributes : array<string|int, mixed>
-
The attributes supplied during field registration.
Return values
array<string|int, mixed> — The processed attributes.set_array_meta()
Sets a field value in an array meta, supporting routing things to billing, shipping, or additional fields, based on a prefix for the key.
private
set_array_meta(string $key, mixed $value, WC_Customer|WC_Order $wc_object, string $group) : void
Parameters
- $key : string
-
The field key.
- $value : mixed
-
The field value.
- $wc_object : WC_Customer|WC_Order
-
The object to set the field value for.
- $group : string
-
The group to set the field value for (shipping|billing|other).
Return values
void —validate_options()
Validates the "base" options (id, label, location) and shows warnings if they're not supplied.
private
validate_options(array<string|int, mixed> &$options) : bool
Parameters
- $options : array<string|int, mixed>
-
The options supplied during field registration.