/includes/abstracts/abstract-wc-shipping-method.php

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