WC_Shipping_Method
extends WC_Settings_API
in package
WooCommerce Shipping Method Class.
Extended by shipping methods to handle shipping calculations etc.
Tags
Table of Contents
- $availability : string
- Availability - legacy. Used for method Availability.
- $countries : array<string|int, mixed>
- Availability countries - legacy. Used for method Availability.
- $enabled : string
- Yes or no based on whether the method is enabled.
- $errors : array<string|int, mixed>
- Validation errors.
- $fee : string
- Fee for the method (if applicable).
- $form_fields : array<string|int, mixed>
- Form option fields.
- $has_settings : bool
- Whether the shipping method has settings or not. Preferably, use {@see has_settings()} instead.
- $id : string
- Unique ID for the shipping method - must be set.
- $instance_form_fields : array<string|int, mixed>
- Instance form fields.
- $instance_id : int
- Instance ID if used.
- $instance_settings : array<string|int, mixed>
- Instance settings.
- $method_description : string
- Method description.
- $method_order : int
- Shipping method order.
- $method_title : string
- Method title.
- $minimum_fee : string
- Minimum fee for the method (if applicable).
- $plugin_id : string
- The plugin ID. Used for option names.
- $rates : array<string|int, mixed>
- This is an array of rates - methods must populate this array to register shipping costs.
- $settings : array<string|int, mixed>
- Setting values.
- $settings_html : string|bool
- When the method supports the settings modal, this is the admin settings HTML.
- $supports : array<string|int, mixed>
- Features this method supports. Possible features used by core: - shipping-zones Shipping zone functionality + instances - instance-settings Instance settings screens.
- $tax_status : string
- If 'taxable' tax will be charged for this method (if applicable).
- $title : string
- Shipping method title for the frontend.
- $data : array<string|int, mixed>
- The posted settings data. When empty, $_POST data will be used.
- __construct() : mixed
- Constructor.
- add_error() : mixed
- Add an error message for display in admin on save.
- add_rate() : mixed
- Add a shipping rate. If taxes are not set they will be calculated based on cost.
- admin_options() : mixed
- Output the shipping settings screen.
- calculate_shipping() : mixed
- Called to calculate shipping rates for this method. Rates can be added using the add_rate() method.
- display_errors() : mixed
- Display admin error messages.
- format_settings() : array<string|int, mixed>
- Format settings if needed.
- generate_checkbox_html() : string
- Generate Checkbox HTML.
- generate_color_html() : string
- Generate Color Picker Input HTML.
- generate_decimal_html() : string
- Generate Decimal Input HTML.
- generate_multiselect_html() : string
- Generate Multiselect HTML.
- generate_password_html() : string
- Generate Password Input HTML.
- generate_price_html() : string
- Generate Price Input HTML.
- generate_safe_text_html() : string
- Generates HTML for the 'safe_text' input type (mostly used for gateway-related settings).
- generate_select_html() : string
- Generate Select HTML.
- generate_settings_html() : string
- Generate Settings HTML.
- generate_text_html() : string
- Generate Text Input HTML.
- generate_textarea_html() : string
- Generate Textarea HTML.
- generate_title_html() : string
- Generate Title HTML.
- get_admin_options_html() : string
- Return admin options as a html string.
- get_custom_attribute_html() : string
- Get custom attributes.
- get_description_html() : string
- Get HTML for descriptions.
- get_errors() : mixed
- Get admin error messages.
- get_fee() : float
- Get fee to add to shipping cost.
- get_field_default() : string
- Get a fields default value. Defaults to "" if not set.
- get_field_key() : string
- Prefix key for settings.
- get_field_type() : string
- Get a fields type. Defaults to "text" if not set.
- get_field_value() : string
- Get a field's posted and validated value.
- get_form_fields() : array<string|int, mixed>
- Get the form fields after they are initialized.
- get_instance_form_fields() : array<string|int, mixed>
- Get settings fields for instances of this shipping method (within zones).
- get_instance_id() : int
- Return the shipping method instance ID.
- get_instance_option() : mixed
- Gets an option from the settings API, using defaults if necessary to prevent undefined notices.
- get_instance_option_key() : string
- Return the name of the option in the WP DB.
- get_method_description() : string
- Return the shipping method description.
- get_method_title() : string
- Return the shipping method title.
- get_option() : mixed
- Get_option function.
- get_option_key() : string
- Return the name of the option in the WP DB.
- get_post_data() : array<string|int, mixed>
- Returns the POSTed data, to be used to save the settings.
- get_rate_id() : string
- Returns a rate ID based on this methods ID and instance, with an optional suffix if distinguishing between multiple rates.
- get_rates_for_package() : array<string|int, mixed>
- Return calculated rates for a package.
- get_title() : string
- Return the shipping title which is user set.
- get_tooltip_html() : string
- Get HTML for tooltips.
- has_settings() : bool
- Does this method have a settings page?
- init_form_fields() : mixed
- Initialise settings form fields.
- init_instance_settings() : mixed
- Initialise Settings for instances.
- init_settings() : mixed
- Initialise Settings.
- is_available() : bool
- Is this method available?
- is_enabled() : bool
- Whether or not this method is enabled in settings.
- is_taxable() : bool
- Whether or not we need to calculate tax on top of the shipping rate.
- process_admin_options() : bool
- Processes and saves global shipping method options in the admin area.
- set_post_data() : mixed
- Sets the POSTed data. This method can be used to set specific data, instead of taking it from the $_POST array.
- supports() : bool
- Check if a shipping method supports a given feature.
- update_option() : bool
- Update a single option.
- validate_checkbox_field() : string
- Validate Checkbox Field.
- validate_decimal_field() : string
- Validate Decimal Field.
- validate_multiselect_field() : string|array<string|int, mixed>
- Validate Multiselect Field.
- validate_password_field() : string
- Validate Password Field. No input sanitization is used to avoid corrupting passwords.
- validate_price_field() : string
- Validate Price Field.
- validate_safe_text_field() : string
- Sanitize 'Safe Text' fields.
- validate_select_field() : string
- Validate Select Field.
- validate_settings_fields() : mixed
- Validate the data on the "Settings" form.
- validate_text_field() : string
- Validate Text Field.
- validate_textarea_field() : string
- Validate Textarea Field.
- get_taxes_per_item() : array<string|int, mixed>
- Calc taxes per item being shipping in costs array.
- set_defaults() : array<string|int, mixed>
- Set default required properties for each field.
Properties
$availability
Availability - legacy. Used for method Availability.
public
string
$availability
No longer useful for instance based shipping methods.
Tags
$countries
Availability countries - legacy. Used for method Availability.
public
array<string|int, mixed>
$countries
= array()
No longer useful for instance based shipping methods.
Tags
$enabled
Yes or no based on whether the method is enabled.
public
string
$enabled
= 'yes'
$errors
Validation errors.
public
array<string|int, mixed>
$errors
= array()
$fee
Fee for the method (if applicable).
public
string
$fee
=
ull
$form_fields
Form option fields.
public
array<string|int, mixed>
$form_fields
= array()
$has_settings
Whether the shipping method has settings or not. Preferably, use {@see has_settings()} instead.
public
bool
$has_settings
$id
Unique ID for the shipping method - must be set.
public
string
$id
= ''
$instance_form_fields
Instance form fields.
public
array<string|int, mixed>
$instance_form_fields
= array()
$instance_id
Instance ID if used.
public
int
$instance_id
= 0
$instance_settings
Instance settings.
public
array<string|int, mixed>
$instance_settings
= array()
$method_description
Method description.
public
string
$method_description
= ''
$method_order
Shipping method order.
public
int
$method_order
$method_title
Method title.
public
string
$method_title
= ''
$minimum_fee
Minimum fee for the method (if applicable).
public
string
$minimum_fee
=
ull
$plugin_id
The plugin ID. Used for option names.
public
string
$plugin_id
= 'woocommerce_'
$rates
This is an array of rates - methods must populate this array to register shipping costs.
public
array<string|int, mixed>
$rates
= array()
$settings
Setting values.
public
array<string|int, mixed>
$settings
= array()
$settings_html
When the method supports the settings modal, this is the admin settings HTML.
public
string|bool
$settings_html
Preferably, use {@see} instead.
$supports
Features this method supports. Possible features used by core: - shipping-zones Shipping zone functionality + instances - instance-settings Instance settings screens.
public
array<string|int, mixed>
$supports
= array('settings')
- settings Non-instance settings screens. Enabled by default for BW compatibility with methods before instances existed.
- instance-settings-modal Allows the instance settings to be loaded within a modal in the zones UI.
$tax_status
If 'taxable' tax will be charged for this method (if applicable).
public
string
$tax_status
= 'taxable'
$title
Shipping method title for the frontend.
public
string
$title
$data
The posted settings data. When empty, $_POST data will be used.
protected
array<string|int, mixed>
$data
= array()
Methods
__construct()
Constructor.
public
__construct(int $instance_id) : mixed
Parameters
- $instance_id : int
-
Instance ID.
Return values
mixed —add_error()
Add an error message for display in admin on save.
public
add_error(string $error) : mixed
Parameters
- $error : string
-
Error message.
Return values
mixed —add_rate()
Add a shipping rate. If taxes are not set they will be calculated based on cost.
public
add_rate([array<string|int, mixed> $args = array() ]) : mixed
Parameters
- $args : array<string|int, mixed> = array()
-
Arguments (default: array()).
Return values
mixed —admin_options()
Output the shipping settings screen.
public
admin_options() : mixed
Return values
mixed —calculate_shipping()
Called to calculate shipping rates for this method. Rates can be added using the add_rate() method.
public
calculate_shipping([array<string|int, mixed> $package = array() ]) : mixed
Parameters
- $package : array<string|int, mixed> = array()
-
Package array.
Return values
mixed —display_errors()
Display admin error messages.
public
display_errors() : mixed
Return values
mixed —format_settings()
Format settings if needed.
public
format_settings(array<string|int, mixed> $value) : array<string|int, mixed>
Parameters
- $value : array<string|int, mixed>
-
Value to format.
Tags
Return values
array<string|int, mixed> —generate_checkbox_html()
Generate Checkbox HTML.
public
generate_checkbox_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_color_html()
Generate Color Picker Input HTML.
public
generate_color_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_decimal_html()
Generate Decimal Input HTML.
public
generate_decimal_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_multiselect_html()
Generate Multiselect HTML.
public
generate_multiselect_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_password_html()
Generate Password Input HTML.
public
generate_password_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_price_html()
Generate Price Input HTML.
public
generate_price_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_safe_text_html()
Generates HTML for the 'safe_text' input type (mostly used for gateway-related settings).
public
generate_safe_text_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_select_html()
Generate Select HTML.
public
generate_select_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_settings_html()
Generate Settings HTML.
public
generate_settings_html([array<string|int, mixed> $form_fields = array() ][, bool $echo = true ]) : string
Generate the HTML for the fields on the "settings" screen.
Parameters
- $form_fields : array<string|int, mixed> = array()
-
(default: array()) Array of form fields.
- $echo : bool = true
-
Echo or return.
Tags
Return values
string — the html for the settingsgenerate_text_html()
Generate Text Input HTML.
public
generate_text_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_textarea_html()
Generate Textarea HTML.
public
generate_textarea_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —generate_title_html()
Generate Title HTML.
public
generate_title_html(string $key, array<string|int, mixed> $data) : string
Parameters
- $key : string
-
Field key.
- $data : array<string|int, mixed>
-
Field data.
Tags
Return values
string —get_admin_options_html()
Return admin options as a html string.
public
get_admin_options_html() : string
Return values
string —get_custom_attribute_html()
Get custom attributes.
public
get_custom_attribute_html(array<string|int, mixed> $data) : string
Parameters
- $data : array<string|int, mixed>
-
Field data.
Return values
string —get_description_html()
Get HTML for descriptions.
public
get_description_html(array<string|int, mixed> $data) : string
Parameters
- $data : array<string|int, mixed>
-
Data for the description.
Return values
string —get_errors()
Get admin error messages.
public
get_errors() : mixed
Return values
mixed —get_fee()
Get fee to add to shipping cost.
public
get_fee(string|float $fee, float $total) : float
Parameters
- $fee : string|float
-
Fee.
- $total : float
-
Total.
Return values
float —get_field_default()
Get a fields default value. Defaults to "" if not set.
public
get_field_default(array<string|int, mixed> $field) : string
Parameters
- $field : array<string|int, mixed>
-
Field key.
Return values
string —get_field_key()
Prefix key for settings.
public
get_field_key(string $key) : string
Parameters
- $key : string
-
Field key.
Return values
string —get_field_type()
Get a fields type. Defaults to "text" if not set.
public
get_field_type(array<string|int, mixed> $field) : string
Parameters
- $field : array<string|int, mixed>
-
Field key.
Return values
string —get_field_value()
Get a field's posted and validated value.
public
get_field_value(string $key, array<string|int, mixed> $field[, array<string|int, mixed> $post_data = array() ]) : string
Parameters
- $key : string
-
Field key.
- $field : array<string|int, mixed>
-
Field array.
- $post_data : array<string|int, mixed> = array()
-
Posted data.
Return values
string —get_form_fields()
Get the form fields after they are initialized.
public
get_form_fields() : array<string|int, mixed>
Return values
array<string|int, mixed> — of optionsget_instance_form_fields()
Get settings fields for instances of this shipping method (within zones).
public
get_instance_form_fields() : array<string|int, mixed>
Should be overridden by shipping methods to add options.
Tags
Return values
array<string|int, mixed> —get_instance_id()
Return the shipping method instance ID.
public
get_instance_id() : int
Tags
Return values
int —get_instance_option()
Gets an option from the settings API, using defaults if necessary to prevent undefined notices.
public
get_instance_option(string $key[, mixed $empty_value = null ]) : mixed
Parameters
- $key : string
-
Key.
- $empty_value : mixed = null
-
Empty value.
Return values
mixed — The value specified for the option or a default value for the option.get_instance_option_key()
Return the name of the option in the WP DB.
public
get_instance_option_key() : string
Tags
Return values
string —get_method_description()
Return the shipping method description.
public
get_method_description() : string
Tags
Return values
string —get_method_title()
Return the shipping method title.
public
get_method_title() : string
Tags
Return values
string —get_option()
Get_option function.
public
get_option(string $key[, mixed $empty_value = null ]) : mixed
Gets and option from the settings API, using defaults if necessary to prevent undefined notices.
Parameters
- $key : string
-
Key.
- $empty_value : mixed = null
-
Empty value.
Return values
mixed — The value specified for the option or a default value for the option.get_option_key()
Return the name of the option in the WP DB.
public
get_option_key() : string
Tags
Return values
string —get_post_data()
Returns the POSTed data, to be used to save the settings.
public
get_post_data() : array<string|int, mixed>
Return values
array<string|int, mixed> —get_rate_id()
Returns a rate ID based on this methods ID and instance, with an optional suffix if distinguishing between multiple rates.
public
get_rate_id([string $suffix = '' ]) : string
Parameters
- $suffix : string = ''
-
Suffix.
Tags
Return values
string —get_rates_for_package()
Return calculated rates for a package.
public
get_rates_for_package(array<string|int, mixed> $package) : array<string|int, mixed>
Parameters
- $package : array<string|int, mixed>
-
Package array.
Tags
Return values
array<string|int, mixed> —get_title()
Return the shipping title which is user set.
public
get_title() : string
Return values
string —get_tooltip_html()
Get HTML for tooltips.
public
get_tooltip_html(array<string|int, mixed> $data) : string
Parameters
- $data : array<string|int, mixed>
-
Data for the tooltip.
Return values
string —has_settings()
Does this method have a settings page?
public
has_settings() : bool
Return values
bool —init_form_fields()
Initialise settings form fields.
public
init_form_fields() : mixed
Add an array of fields to be displayed on the gateway's settings screen.
Tags
Return values
mixed —init_instance_settings()
Initialise Settings for instances.
public
init_instance_settings() : mixed
Tags
Return values
mixed —init_settings()
Initialise Settings.
public
init_settings() : mixed
Store all settings in a single database entry and make sure the $settings array is either the default or the settings stored in the database.
Tags
Return values
mixed —is_available()
Is this method available?
public
is_available(array<string|int, mixed> $package) : bool
Parameters
- $package : array<string|int, mixed>
-
Package.
Return values
bool —is_enabled()
Whether or not this method is enabled in settings.
public
is_enabled() : bool
Tags
Return values
bool —is_taxable()
Whether or not we need to calculate tax on top of the shipping rate.
public
is_taxable() : bool
Return values
bool —process_admin_options()
Processes and saves global shipping method options in the admin area.
public
process_admin_options() : bool
This method is usually attached to woocommerce_update_options_x hooks.
Tags
Return values
bool — was anything saved?set_post_data()
Sets the POSTed data. This method can be used to set specific data, instead of taking it from the $_POST array.
public
set_post_data([array<string|int, mixed> $data = array() ]) : mixed
Parameters
- $data : array<string|int, mixed> = array()
-
Posted data.
Return values
mixed —supports()
Check if a shipping method supports a given feature.
public
supports(string $feature) : bool
Methods should override this to declare support (or lack of support) for a feature.
Parameters
- $feature : string
-
The name of a feature to test support for.
Return values
bool — True if the shipping method supports the feature, false otherwise.update_option()
Update a single option.
public
update_option(string $key[, mixed $value = '' ]) : bool
Parameters
- $key : string
-
Option key.
- $value : mixed = ''
-
Value to set.
Tags
Return values
bool — was anything saved?validate_checkbox_field()
Validate Checkbox Field.
public
validate_checkbox_field(string $key, string $value) : string
If not set, return "no", otherwise return "yes".
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string —validate_decimal_field()
Validate Decimal Field.
public
validate_decimal_field(string $key, string $value) : string
Make sure the data is escaped correctly, etc.
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string —validate_multiselect_field()
Validate Multiselect Field.
public
validate_multiselect_field(string $key, string $value) : string|array<string|int, mixed>
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string|array<string|int, mixed> —validate_password_field()
Validate Password Field. No input sanitization is used to avoid corrupting passwords.
public
validate_password_field(string $key, string $value) : string
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string —validate_price_field()
Validate Price Field.
public
validate_price_field(string $key, string $value) : string
Make sure the data is escaped correctly, etc.
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string —validate_safe_text_field()
Sanitize 'Safe Text' fields.
public
validate_safe_text_field(string $key, string $value) : string
These fields are similar to regular text fields, but a much smaller set of HTML tags are allowed. By default,
this means <br>, <img>, <p> and <span> tags.
Note: this is a sanitization method, rather than a validation method (the name is due to some historic naming choices).
Parameters
- $key : string
-
Field key (currently unused).
- $value : string
-
Posted Value.
Return values
string —validate_select_field()
Validate Select Field.
public
validate_select_field(string $key, string $value) : string
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string —validate_settings_fields()
Validate the data on the "Settings" form.
public
validate_settings_fields([array<string|int, mixed> $form_fields = array() ]) : mixed
Parameters
- $form_fields : array<string|int, mixed> = array()
-
Array of fields.
Tags
Return values
mixed —validate_text_field()
Validate Text Field.
public
validate_text_field(string $key, string $value) : string
Make sure the data is escaped correctly, etc.
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Return values
string —validate_textarea_field()
Validate Textarea Field.
public
validate_textarea_field(string $key, string $value) : string
Parameters
- $key : string
-
Field key.
- $value : string
-
Posted Value.
Tags
Return values
string —get_taxes_per_item()
Calc taxes per item being shipping in costs array.
protected
get_taxes_per_item(array<string|int, mixed> $costs) : array<string|int, mixed>
Parameters
- $costs : array<string|int, mixed>
-
Costs.
Tags
Return values
array<string|int, mixed> — of taxesset_defaults()
Set default required properties for each field.
protected
set_defaults(array<string|int, mixed> $field) : array<string|int, mixed>
Parameters
- $field : array<string|int, mixed>
-
Setting field array.