Author: Condless

Cities Shipping Zones for WooCommerce

Which uses shop owners make with the customer city?

• Set shipping rates per cities
• Sales stats by city (Dashbaord => WooCommerce => Reports => Sales by city)
• Displaying certain products by city (filter by city category)
• Selling certain products per city (plugin that limits by state)
• Shipping certain products per city (associating the products to a class without price in the relevant shipping method)
• Applying taxes per city (using the city code in the state field in the settings)
• Enabling payment / shipping methods per city (conditional payment / shipping plugin)
• Displaying the cities in external checkout page (retreiving the states via WooCommerce REST API)

Options

What is the State Autofill option?
When enabled, the state will be auto filled by the selected city for countries that have states in their cities list. You may set the countries the option will be applied on with the csz_populate_state filter.

What is the Filters option?
When enabled, a state filter will be displayed in the checkout for the store country. the state will not be inserted into the order unless the ‘State Autofill’ option is enabled. The filter will not fuction when switching from a country with no built-in states.

How to add the filter in the cart page as well?
Add this code into your
shipping calculator template just before the line
<?php if ( apply_filters( 'woocommerce_shipping_calculator_enable_state', true ) ) : ?>

<?php
	if ( 'yes' === get_option( 'wc_csz_new_state_field' ) && in_array( WC()->countries->get_base_country(), get_option( 'wc_csz_countries_codes' ) ) ) {
		$country_states = [];
		include( WP_PLUGIN_DIR . '/cities-shipping-zones-for-woocommerce/i18n/cities/' . WC()->countries->get_base_country() . '.php' );
		woocommerce_form_field( 'calc_shipping_new_state', [
			'type'	=> 'select',
			'options'	=> [ '' => '' ] + apply_filters( 'csz_states', $country_states ),
			'class'		=> [ 'form-row-wide', 'address-field' ],
			'input_class'	=> [ 'state_select' ]
		] );
		?>
			<script type="text/javascript">
			jQuery( function( $ ) {
				var country = '<?php echo WC()->countries->get_base_country(); ?>';
				$( document ).ready( function() { new_state_visibility() } );
				$( '#calc_shipping_country' ).on( 'select2:select', function() { new_state_visibility() } );
				function new_state_visibility() {
					if ( $( '#calc_shipping_country option:selected' ).val() == country || $( '#calc_shipping_country' ).val() == country ) {
						$( '#calc_shipping_new_state_field' ).show();
					} else {
						$( '#calc_shipping_new_state_field' ).hide();
					}
				};
				$( '#calc_shipping_state' ).on( 'select2:open', function() {
					if ( $( '#calc_shipping_country option:selected' ).val() == country || $( '#calc_shipping_country' ).val() == country ) {
						$( '#calc_shipping_state' ).data( 'select2' ).dropdown.$search.val( $( '#calc_shipping_new_state option:selected' ).text() + ' - ' );
						$( '#calc_shipping_state' ).data( 'select2' ).dropdown.$search.trigger( 'input' );
						$( '#calc_shipping_state' ).trigger( 'query', { term } );
					}
				} );
				$( '#calc_shipping_state' ).on( 'select2:select', function() {
					$( '#calc_shipping_new_state option' ).filter( function() { return $( this ).text() == $( '#calc_shipping_state option:selected' ).text().split( ' - ' )[0]; } ).prop( 'selected', true );
					$( '#calc_shipping_new_state' ).trigger( 'change' );
				} );
			} );
			</script>
		<?php
	}
?>

Bulk Edit Tool

What is the required format?
Semicolon (;) between each city. For example: Wien; Rust; Steinbrunn

How to modify cities in list to the required format?
Replace [\r\n]+ (regex) with ; in Notepad++.

How to enter all the locations within certain distance from a city with distances list?
Enter exclamation mark (!) followed by the city code, if necessary add minium and maximum distance seperated by semicolon (;).

Integrations

Why in the integrated software the city appear twice or the city code is present?
You will have to remove the sending of the state field (billing/shipping, orders/customers) via its plugin’s code for the countries you apply the plugin on.

Why in my integrated software the city field is empty or the payment failed?
You will have to modify its way of retreiving the city field (billing/shipping) from the order for the countries you apply the plugin on- from: $_POST['billing_city'] into $order->get_billing_city(). As alternative, add to the woocommerce_checkout_create_order action a command that copies $order->get_billing_city() into $_POST['billing_city'].

Why the state code and not the state name appears in the order details in the first order email confirmation and in the my account section while using the populate state option on countries with WooCommerce built-in states list?
You may use the woocommerce_formatted_address_replacements filter to fix it.

How to integrate with Food Online Premium plugin?
Add to line 836 in class-fdoe-del.php file (update the mismatch cities names):

if ( is_plugin_active( 'cities-shipping-zones-for-woocommerce/cities-shipping-zones-for-woocommerce.php' ) && in_array( $country, get_option( 'wc_csz_countries_codes' ) ) ) {
	$cities = [
		'Talin' => 'Tallinn',
	];
	if ( isset( $cities[ $_POST['city'] ] ) ) {
		$_POST['city'] = $cities[ $_POST['city'] ];
	}
	$state = array_search( _x( wc_clean( $_POST['city'] ), "{$country}-cities", 'cities-shipping-zones-for-woocommerce' ), WC()->countries->get_states( $country ) );
	$_POST['city'] = '';
}

Cities List

How to modify cities names?
Update countries codes, and cities codes and names:
* Don’t use if the Filters option enabled

add_filter( 'csz_cities', 'csz_modify_cities' );
function csz_modify_ities( $states ) {
	$states['AT']['AT90001'] = 'Vienna';
	return $states;
}

How to remove some cities from the list?
Update country code and cities codes:

add_filter( 'csz_cities', 'csz_remove_cities' );
function csz_remove_cities( $states ) {
	$country_code = 'AT';
	$unnecessary_cities = [ 'AT10101', 'AT10201', 'AT10301' ];
	foreach ( $unnecessary_cities as $city ) {
		unset( $states[ $country_code ][ $city ] );
	}
	return $states;
}

How to keep only specific cities in the list?
Update country code and cities codes:

add_filter( 'csz_cities', 'csz_set_cities' );
function csz_set_cities( $states ) {
	$country = 'AT';
	$cities = [ 'AT10101', 'AT10201', 'AT10301' ];
	$new_states = [];
	foreach ( $cities as $city ) {
		if ( isset( $states[ $country ][ $city ] ) ) {
			$new_states[ $city ] = $states[ $country ][ $city ];
		}
	}
	$states[ $country ] = $new_states;
	return $states;
}

How to remove from the list all the cities of certain states?
Update states codes:

add_filter( 'csz_states', 'csz_remove_states_cities' );
function csz_remove_states_cities( $states ) {
	$unnecessary_states = [ 'EE001', 'EE004', 'EE006' ];
	foreach ( $unnecessary_states as $state_code ) {
		if ( isset( $states[ $state_code ] ) ) {
			unset( $states[ $state_code ] );
		}
	}
	return $states;
}

How to create shipping zones for quarters inside a city?
Create shipping zone with that city and restrict to the relevant postcodes, or (less recommended) split the city into areas (update country code and city code and areas names, if the store is located inside this city update the store location in WooCommerce settings):
* Don’t use if the State Autofill / Filters options are enabled

add_filter( 'csz_cities', 'csz_split_cities' );
function csz_split_cities( $states ) {
	$country_code = 'AT';
	$city_code = 'AT90001';
	$sub_cities = [ __( 'Northern', 'woocommerce' ), __( 'Southern', 'woocommerce' ) ];
	$count = 101;
	foreach ( $sub_cities as $sub_city ) {
		$states[ $country_code ][ $city_code . $count ] = $states[ $country_code ][ $city_code ] . ' - ' . $sub_city;
		$count++;
	}
	unset( $states[ $country_code ][ $city_code ] );
	return $states;
}

Distance Fee

How to apply distance fee?
Given a (domestic) city’s distances list, it will be possible to add distance based fee for the shipping rate or product price (for example- to sell moving services).

Why the tax is not calculated on the distance fee?
Enter in the shipping method cost greater than zero.

Where the configured product distance fee will be displayed?
The product the fee will be added to its price and will be displayed in the subtotal of the mini cart widget.

How I shall organize the distances list for some city?
Use as index the locations codes or names (as they appear in the dashboard and update $key_format), verify to set distance to the city itself, the distances should be greater than 0.

Shortcodes

How to display dropdown of cities with shortcode?
Use the [csz_field] shortcode:

add_action( 'wp_ajax_csz_match_shipping_zone', 'csz_match_shipping_zone' );
add_action( 'wp_ajax_nopriv_csz_match_shipping_zone', 'csz_match_shipping_zone' );
add_shortcode( 'csz_field', 'csz_field_shortcode' );

function csz_field_shortcode( $atts ) {
	$atts = shortcode_atts( [
		'key'	=> 'shipping_state',
		'type'	=> 'state',
		'required'	=> '1',
		'country'	=> WC()->countries->get_base_country(),
		'description'	=> '',
		'class'	=> [ 'form-row', 'address-field', 'form-row-first' ],
		'label'	=> __( 'City', 'woocommerce' ),
		'value'	=> '',
		'match'	=> false
	], $atts, 'csz_field' );
	$output = woocommerce_form_field( $atts['key'], [
		'type'	=> $atts['type'],
		'label'	=> $atts['label'],
		'class'	=> $atts['class'],
		'required'	=> $atts['required'],
		'description'	=> $atts['description'],
		'country'	=> $atts['country']
		], $atts['value'] );
	if ( 'country' === $atts['type'] || 'state' === $atts['type'] ) {
		wp_enqueue_script( 'selectWoo' );
		wp_enqueue_style( 'select2' );
		wp_enqueue_script( 'wc-country-select' );
		if ( $atts['match'] ) {
			add_action( 'wp_footer', 'csz_match_javascript' );
		}
	}
	return $output;
}

function csz_match_shipping_zone() {
	echo wc_get_shipping_zone( [ 'destination' => [ 'country' => WC()->countries->get_base_country(), 'state' => $_POST['state'], 'postcode' => '' ] ] )->get_zone_name();
	wp_die();
}

function csz_match_javascript() {
	?>
		<script type="text/javascript" >
		jQuery( function( $ ) {
			$( '#shipping_state' ).on( 'select2:select', function() {
				var data = {
					'action'	: 'csz_match_shipping_zone',
					'state'		: $( '#shipping_state option:selected' ).val()
				};
				$.post( '<?php echo admin_url( 'admin-ajax.php' ); ?>', data, function( response ) {
					alert( '<?php echo __( 'Shipping Zone', 'woocommerce' ); ?>: ' + response );
				} );
			} )
		} );
		</script>
	<?php
}

WooCommerce REST API

Use the class:

add_filter( 'woocommerce_rest_api_get_rest_namespaces', 'wc_states_api' );
function wc_states_api( $controllers ) {
	$controllers['wc/v3']['data-states'] = 'WC_REST_Data_States_Controller';
	return $controllers;
}

class WC_REST_Data_States_Controller extends WC_REST_Data_Controller {
	protected $namespace = 'wc/v3';
	protected $rest_base = 'data/states';
	function register_routes() {
		register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P<state>[\w-]+)/zone', [
			'methods'		=> 'GET',
			'callback'		=> [ $this, 'get_zone' ],
			'args'			=> [ 'state' => [ 'description' => __( 'State / County', 'woocommerce' ), 'type' => 'string' ] ],
			'permission_callback'	=> [ $this, 'get_items_permissions_check' ],
		] );
		register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P<state>[\w-]+)/state', [
			'methods'		=> 'GET',
			'callback'		=> [ $this, 'get_state' ],
			'args'			=> [ 'state' => [ 'description' => __( 'State / County', 'woocommerce' ), 'type' => 'string' ] ],
			'permission_callback'	=> [ $this, 'get_items_permissions_check' ],
		] );
	}
	function get_zone( $data ) {
		return [ 'id' => wc_get_shipping_zone( [ 'destination' => [ 'country' => substr( $data['state'], 0, 2 ), 'state' => $data['state'], 'postcode' => '' ] ] )->get_zone_id() ];
	}
	function get_state( $data ) {
		foreach ( get_option( 'wc_csz_countries_codes' ) as $country_code ) {
			$country_cities = '';
			$country_states = '';
			include( WP_PLUGIN_DIR . '/cities-shipping-zones-for-woocommerce/i18n/cities/' . $country_code . '.php' );
			if ( isset( $country_states ) ) {
				foreach ( $country_states as $state_code => $state_name ) {
					if ( isset( $country_cities[ $state_code ][ $data['state'] ] ) ) {
						return $country_states[ $state_code ];
					}
				}
			}
		}
		return false;
	}
}

How to retrieve the shipping zone a city belong to (for the countries the plugin apply on)?

/wp-json/wc/v3/data/states/<city_code>/zone

How to retrieve the state name a city belong to (for the countries the plugin apply on)?

/wp-json/wc/v3/data/states/<city_code>/state

Uninstall Plugin / Countries / Locations

• WooCommerce Shipping Zones settings: Remove the locations (you may use the Bulk Edit tool)
• Plugin Settings: Remove the countries
• WooCommerce Settings: Update the store location
• Users: convert/erase the state field values of users that were created/updated while the plugin was applied on the countries they belong to
• Plugins: Deactivate and delete the plugin