WC_Shipping_Method

WooCommerce Shipping Method Class.

Defined (1)

The class is defined in the following location(s).

/includes/abstracts/abstract-wc-shipping-method.php  
  1. abstract class WC_Shipping_Method extends WC_Settings_API { 
  2.  
  3. /** 
  4. * Features this method supports. Possible features used by core: 
  5. * - shipping-zones Shipping zone functionality + instances 
  6. * - instance-settings Instance settings screens. 
  7. * - settings Non-instance settings screens. Enabled by default for BW compatibility with methods before instances existed. 
  8. * - instance-settings-modal Allows the instance settings to be loaded within a modal in the zones UI. 
  9. * @var array 
  10. */ 
  11. public $supports = array( 'settings' ); 
  12.  
  13. /** 
  14. * Unique ID for the shipping method - must be set. 
  15. * @var string 
  16. */ 
  17. public $id = ''; 
  18.  
  19. /** 
  20. * Method title. 
  21. * @var string 
  22. */ 
  23. public $method_title = ''; 
  24.  
  25. /** 
  26. * Method description. 
  27. * @var string 
  28. */ 
  29. public $method_description = ''; 
  30.  
  31. /** 
  32. * yes or no based on whether the method is enabled. 
  33. * @var string 
  34. */ 
  35. public $enabled = 'yes'; 
  36.  
  37. /** 
  38. * Shipping method title for the frontend. 
  39. * @var string 
  40. */ 
  41. public $title; 
  42.  
  43. /** 
  44. * This is an array of rates - methods must populate this array to register shipping costs. 
  45. * @var array 
  46. */ 
  47. public $rates = array(); 
  48.  
  49. /** 
  50. * If 'taxable' tax will be charged for this method (if applicable). 
  51. * @var string 
  52. */ 
  53. public $tax_status = 'taxable'; 
  54.  
  55. /** 
  56. * Fee for the method (if applicable). 
  57. * @var string 
  58. */ 
  59. public $fee = null; 
  60.  
  61. /** 
  62. * Minimum fee for the method (if applicable). 
  63. * @var string 
  64. */ 
  65. public $minimum_fee = null; 
  66.  
  67. /** 
  68. * Instance ID if used. 
  69. * @var int 
  70. */ 
  71. public $instance_id = 0; 
  72.  
  73. /** 
  74. * Instance form fields. 
  75. * @var array 
  76. */ 
  77. public $instance_form_fields = array(); 
  78.  
  79. /** 
  80. * Instance settings. 
  81. * @var array 
  82. */ 
  83. public $instance_settings = array(); 
  84.  
  85. /** 
  86. * Availability - legacy. Used for method Availability. 
  87. * No longer useful for instance based shipping methods. 
  88. * @deprecated 2.6.0 
  89. * @var string 
  90. */ 
  91. public $availability; 
  92.  
  93. /** 
  94. * Availability countries - legacy. Used for method Availability. 
  95. * No longer useful for instance based shipping methods. 
  96. * @deprecated 2.6.0 
  97. * @var array 
  98. */ 
  99. public $countries = array(); 
  100.  
  101. /** 
  102. * Constructor. 
  103. * @param int $instance_id 
  104. */ 
  105. public function __construct( $instance_id = 0 ) { 
  106. $this->instance_id = absint( $instance_id ); 
  107.  
  108. /** 
  109. * Check if a shipping method supports a given feature. 
  110. * Methods should override this to declare support (or lack of support) for a feature. 
  111. * @param $feature string The name of a feature to test support for. 
  112. * @return bool True if the shipping method supports the feature, false otherwise. 
  113. */ 
  114. public function supports( $feature ) { 
  115. return apply_filters( 'woocommerce_shipping_method_supports', in_array( $feature, $this->supports ), $feature, $this ); 
  116.  
  117. /** 
  118. * Called to calculate shipping rates for this method. Rates can be added using the add_rate() method. 
  119. */ 
  120. public function calculate_shipping( $package = array() ) {} 
  121.  
  122. /** 
  123. * Whether or not we need to calculate tax on top of the shipping rate. 
  124. * @return boolean 
  125. */ 
  126. public function is_taxable() { 
  127. return wc_tax_enabled() && 'taxable' === $this->tax_status && ! WC()->customer->get_is_vat_exempt(); 
  128.  
  129. /** 
  130. * Whether or not this method is enabled in settings. 
  131. * @since 2.6.0 
  132. * @return boolean 
  133. */ 
  134. public function is_enabled() { 
  135. return 'yes' === $this->enabled; 
  136.  
  137. /** 
  138. * Return the shipping method instance ID. 
  139. * @since 2.6.0 
  140. * @return int 
  141. */ 
  142. public function get_instance_id() { 
  143. return $this->instance_id; 
  144.  
  145. /** 
  146. * Return the shipping method title. 
  147. * @since 2.6.0 
  148. * @return string 
  149. */ 
  150. public function get_method_title() { 
  151. return apply_filters( 'woocommerce_shipping_method_title', $this->method_title, $this ); 
  152.  
  153. /** 
  154. * Return the shipping method description. 
  155. * @since 2.6.0 
  156. * @return string 
  157. */ 
  158. public function get_method_description() { 
  159. return apply_filters( 'woocommerce_shipping_method_description', $this->method_description, $this ); 
  160.  
  161. /** 
  162. * Return the shipping title which is user set. 
  163. * @return string 
  164. */ 
  165. public function get_title() { 
  166. return apply_filters( 'woocommerce_shipping_method_title', $this->title, $this->id ); 
  167.  
  168. /** 
  169. * Return calculated rates for a package. 
  170. * @since 2.6.0 
  171. * @param object $package 
  172. * @return array 
  173. */ 
  174. public function get_rates_for_package( $package ) { 
  175. $this->rates = array(); 
  176. if ( $this->is_available( $package ) && ( empty( $package['ship_via'] ) || in_array( $this->id, $package['ship_via'] ) ) ) { 
  177. $this->calculate_shipping( $package ); 
  178. return $this->rates; 
  179.  
  180. /** 
  181. * Returns a rate ID based on this methods ID and instance, with an optional 
  182. * suffix if distinguishing between multiple rates. 
  183. * @since 2.6.0 
  184. * @param string $suffix 
  185. * @return string 
  186. */ 
  187. public function get_rate_id( $suffix = '' ) { 
  188. $rate_id = array( $this->id ); 
  189.  
  190. if ( $this->instance_id ) { 
  191. $rate_id[] = $this->instance_id; 
  192.  
  193. if ( $suffix ) { 
  194. $rate_id[] = $suffix; 
  195.  
  196. return implode( ':', $rate_id ); 
  197.  
  198. /** 
  199. * Add a shipping rate. If taxes are not set they will be calculated based on cost. 
  200. * @param array $args (default: array()) 
  201. */ 
  202. public function add_rate( $args = array() ) { 
  203. $args = wp_parse_args( $args, array( 
  204. 'id' => $this->get_rate_id(), // ID for the rate. If not passed, this id:instance default will be used. 
  205. 'label' => '', // Label for the rate 
  206. 'cost' => '0', // Amount or array of costs (per item shipping) 
  207. 'taxes' => '', // Pass taxes, or leave empty to have it calculated for you, or 'false' to disable calculations 
  208. 'calc_tax' => 'per_order', // Calc tax per_order or per_item. Per item needs an array of costs 
  209. 'meta_data' => array(), // Array of misc meta data to store along with this rate - key value pairs. 
  210. 'package' => false, // Package array this rate was generated for @since 2.6.0 
  211. ) ); 
  212.  
  213. // ID and label are required 
  214. if ( ! $args['id'] || ! $args['label'] ) { 
  215. return; 
  216.  
  217. // Total up the cost 
  218. $total_cost = is_array( $args['cost'] ) ? array_sum( $args['cost'] ) : $args['cost']; 
  219. $taxes = $args['taxes']; 
  220.  
  221. // Taxes - if not an array and not set to false, calc tax based on cost and passed calc_tax variable. This saves shipping methods having to do complex tax calculations. 
  222. if ( ! is_array( $taxes ) && false !== $taxes && $total_cost > 0 && $this->is_taxable() ) { 
  223. $taxes = 'per_item' === $args['calc_tax'] ? $this->get_taxes_per_item( $args['cost'] ) : WC_Tax::calc_shipping_tax( $total_cost, WC_Tax::get_shipping_tax_rates() ); 
  224.  
  225. // Round the total cost after taxes have been calculated. 
  226. $total_cost = wc_format_decimal( $total_cost, wc_get_price_decimals() ); 
  227.  
  228. // Create rate object 
  229. $rate = new WC_Shipping_Rate( $args['id'], $args['label'], $total_cost, $taxes, $this->id ); 
  230.  
  231. if ( ! empty( $args['meta_data'] ) ) { 
  232. foreach ( $args['meta_data'] as $key => $value ) { 
  233. $rate->add_meta_data( $key, $value ); 
  234.  
  235. // Store package data 
  236. if ( $args['package'] ) { 
  237. $items_in_package = array(); 
  238. foreach ( $args['package']['contents'] as $item ) { 
  239. $product = $item['data']; 
  240. $items_in_package[] = $product->get_name() . ' × ' . $item['quantity']; 
  241. $rate->add_meta_data( __( 'Items', 'woocommerce' ), implode( ', ', $items_in_package ) ); 
  242.  
  243. $this->rates[ $args['id'] ] = $rate; 
  244.  
  245. /** 
  246. * Calc taxes per item being shipping in costs array. 
  247. * @since 2.6.0 
  248. * @access protected 
  249. * @param array $costs 
  250. * @return array of taxes 
  251. */ 
  252. protected function get_taxes_per_item( $costs ) { 
  253. $taxes = array(); 
  254.  
  255. // If we have an array of costs we can look up each items tax class and add tax accordingly 
  256. if ( is_array( $costs ) ) { 
  257.  
  258. $cart = WC()->cart->get_cart(); 
  259.  
  260. foreach ( $costs as $cost_key => $amount ) { 
  261. if ( ! isset( $cart[ $cost_key ] ) ) { 
  262. continue; 
  263.  
  264. $item_taxes = WC_Tax::calc_shipping_tax( $amount, WC_Tax::get_shipping_tax_rates( $cart[ $cost_key ]['data']->get_tax_class() ) ); 
  265.  
  266. // Sum the item taxes 
  267. foreach ( array_keys( $taxes + $item_taxes ) as $key ) { 
  268. $taxes[ $key ] = ( isset( $item_taxes[ $key ] ) ? $item_taxes[ $key ] : 0 ) + ( isset( $taxes[ $key ] ) ? $taxes[ $key ] : 0 ); 
  269.  
  270. // Add any cost for the order - order costs are in the key 'order' 
  271. if ( isset( $costs['order'] ) ) { 
  272. $item_taxes = WC_Tax::calc_shipping_tax( $costs['order'], WC_Tax::get_shipping_tax_rates() ); 
  273.  
  274. // Sum the item taxes 
  275. foreach ( array_keys( $taxes + $item_taxes ) as $key ) { 
  276. $taxes[ $key ] = ( isset( $item_taxes[ $key ] ) ? $item_taxes[ $key ] : 0 ) + ( isset( $taxes[ $key ] ) ? $taxes[ $key ] : 0 ); 
  277.  
  278. return $taxes; 
  279.  
  280. /** 
  281. * Is this method available? 
  282. * @param array $package 
  283. * @return bool 
  284. */ 
  285. public function is_available( $package ) { 
  286. $available = $this->is_enabled(); 
  287.  
  288. // Country availability (legacy, for non-zone based methods) 
  289. if ( ! $this->instance_id && $available ) { 
  290. $countries = is_array( $this->countries ) ? $this->countries : array(); 
  291.  
  292. switch ( $this->availability ) { 
  293. case 'specific' : 
  294. case 'including' : 
  295. $available = in_array( $package['destination']['country'], array_intersect( $countries, array_keys( WC()->countries->get_shipping_countries() ) ) ); 
  296. break; 
  297. case 'excluding' : 
  298. $available = in_array( $package['destination']['country'], array_diff( array_keys( WC()->countries->get_shipping_countries() ), $countries ) ); 
  299. break; 
  300. default : 
  301. $available = in_array( $package['destination']['country'], array_keys( WC()->countries->get_shipping_countries() ) ); 
  302. break; 
  303.  
  304. return apply_filters( 'woocommerce_shipping_' . $this->id . '_is_available', $available, $package ); 
  305.  
  306. /** 
  307. * Get fee to add to shipping cost. 
  308. * @param string|float $fee 
  309. * @param float $total 
  310. * @return float 
  311. */ 
  312. public function get_fee( $fee, $total ) { 
  313. if ( strstr( $fee, '%' ) ) { 
  314. $fee = ( $total / 100 ) * str_replace( '%', '', $fee ); 
  315. if ( ! empty( $this->minimum_fee ) && $this->minimum_fee > $fee ) { 
  316. $fee = $this->minimum_fee; 
  317. return $fee; 
  318.  
  319. /** 
  320. * Does this method have a settings page? 
  321. * @return bool 
  322. */ 
  323. public function has_settings() { 
  324. return $this->instance_id ? $this->supports( 'instance-settings' ) : $this->supports( 'settings' ); 
  325.  
  326. /** 
  327. * Return admin options as a html string. 
  328. * @return string 
  329. */ 
  330. public function get_admin_options_html() { 
  331. if ( $this->instance_id ) { 
  332. $settings_html = $this->generate_settings_html( $this->get_instance_form_fields(), false ); 
  333. } else { 
  334. $settings_html = $this->generate_settings_html( $this->get_form_fields(), false ); 
  335.  
  336. return '<table class="form-table">' . $settings_html . '</table>'; 
  337.  
  338. /** 
  339. * Output the shipping settings screen. 
  340. */ 
  341. public function admin_options() { 
  342. if ( ! $this->instance_id ) { 
  343. echo '<h2>' . esc_html( $this->get_method_title() ) . '</h2>'; 
  344. echo wp_kses_post( wpautop( $this->get_method_description() ) ); 
  345. echo $this->get_admin_options_html(); 
  346.  
  347. /** 
  348. * get_option function. 
  349. * Gets and option from the settings API, using defaults if necessary to prevent undefined notices. 
  350. * @param string $key 
  351. * @param mixed $empty_value 
  352. * @return mixed The value specified for the option or a default value for the option. 
  353. */ 
  354. public function get_option( $key, $empty_value = null ) { 
  355. // Instance options take priority over global options 
  356. if ( $this->instance_id && array_key_exists( $key, $this->get_instance_form_fields() ) ) { 
  357. return $this->get_instance_option( $key, $empty_value ); 
  358.  
  359. // Return global option 
  360. return parent::get_option( $key, $empty_value ); 
  361.  
  362. /** 
  363. * Gets an option from the settings API, using defaults if necessary to prevent undefined notices. 
  364. * @param string $key 
  365. * @param mixed $empty_value 
  366. * @return mixed The value specified for the option or a default value for the option. 
  367. */ 
  368. public function get_instance_option( $key, $empty_value = null ) { 
  369. if ( empty( $this->instance_settings ) ) { 
  370. $this->init_instance_settings(); 
  371.  
  372. // Get option default if unset. 
  373. if ( ! isset( $this->instance_settings[ $key ] ) ) { 
  374. $form_fields = $this->get_instance_form_fields(); 
  375. $this->instance_settings[ $key ] = $this->get_field_default( $form_fields[ $key ] ); 
  376.  
  377. if ( ! is_null( $empty_value ) && '' === $this->instance_settings[ $key ] ) { 
  378. $this->instance_settings[ $key ] = $empty_value; 
  379.  
  380. return $this->instance_settings[ $key ]; 
  381.  
  382. /** 
  383. * Get settings fields for instances of this shipping method (within zones). 
  384. * Should be overridden by shipping methods to add options. 
  385. * @since 2.6.0 
  386. * @return array 
  387. */ 
  388. public function get_instance_form_fields() { 
  389. return apply_filters( 'woocommerce_shipping_instance_form_fields_' . $this->id, array_map( array( $this, 'set_defaults' ), $this->instance_form_fields ) ); 
  390.  
  391. /** 
  392. * Return the name of the option in the WP DB. 
  393. * @since 2.6.0 
  394. * @return string 
  395. */ 
  396. public function get_instance_option_key() { 
  397. return $this->instance_id ? $this->plugin_id . $this->id . '_' . $this->instance_id . '_settings' : ''; 
  398.  
  399. /** 
  400. * Initialise Settings for instances. 
  401. * @since 2.6.0 
  402. */ 
  403. public function init_instance_settings() { 
  404. $this->instance_settings = get_option( $this->get_instance_option_key(), null ); 
  405.  
  406. // If there are no settings defined, use defaults. 
  407. if ( ! is_array( $this->instance_settings ) ) { 
  408. $form_fields = $this->get_instance_form_fields(); 
  409. $this->instance_settings = array_merge( array_fill_keys( array_keys( $form_fields ), '' ), wp_list_pluck( $form_fields, 'default' ) ); 
  410.  
  411. /** 
  412. * Processes and saves options. 
  413. * If there is an error thrown, will continue to save and validate fields, but will leave the erroring field out. 
  414. * @since 2.6.0 
  415. * @return bool was anything saved? 
  416. */ 
  417. public function process_admin_options() { 
  418. if ( $this->instance_id ) { 
  419. $this->init_instance_settings(); 
  420.  
  421. $post_data = $this->get_post_data(); 
  422.  
  423. foreach ( $this->get_instance_form_fields() as $key => $field ) { 
  424. if ( 'title' !== $this->get_field_type( $field ) ) { 
  425. try { 
  426. $this->instance_settings[ $key ] = $this->get_field_value( $key, $field, $post_data ); 
  427. } catch ( Exception $e ) { 
  428. $this->add_error( $e->getMessage() ); 
  429.  
  430. return update_option( $this->get_instance_option_key(), apply_filters( 'woocommerce_shipping_' . $this->id . '_instance_settings_values', $this->instance_settings, $this ) ); 
  431. } else { 
  432. return parent::process_admin_options();