WooCommerce Code Reference

WC_Shipping_Method extends WC_Settings_API
in package

WooCommerce Shipping Method Class.

Extended by shipping methods to handle shipping calculations etc.

Tags
class

WC_Shipping_Method

version
3.0.0

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

$countries

Availability countries - legacy. Used for method Availability.

public array<string|int, mixed> $countries = array()

No longer useful for instance based shipping methods.

Tags
deprecated
2.6.0

$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.

Methods

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

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

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
deprecated
2.6.0

Unused.

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
since
1.0.0
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
since
1.0.0
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
since
1.0.0
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
since
1.0.0
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
since
1.0.0
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
since
1.0.0
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
since
7.6.0
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
since
1.0.0
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
since
1.0.0
uses
method_exists()
Return values
stringthe html for the settings

generate_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
since
1.0.0
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
since
1.0.0
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
since
1.0.0
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_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_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_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
since
2.6.0
Return values
array<string|int, mixed>

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
mixedThe value specified for the option or a default value for the option.

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
mixedThe value specified for the option or a default value for the option.

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
since
2.6.0
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
since
2.6.0
Return values
array<string|int, mixed>

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

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
since
1.0.0
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
since
1.0.0
uses

get_option(), add_option()

Return values
mixed

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
since
2.6.0
Return values
boolwas 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
boolTrue 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
since
3.4.0
Return values
boolwas 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
deprecated
2.6.0

No longer used.

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
since
9.0.0

No longer allows storing IFRAME, which was allowed for "ShareThis" integration no longer found in core.

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
since
2.6.0
Return values
array<string|int, mixed>of taxes

set_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.

Return values
array<string|int, mixed>