User Guide | Setting Location Session Data

Data is set to the cart session by using functions primarily from flexi carts standard library.

The data that can be set in the cart session includes data of items added to the cart, user localisation data and cart configuration settings.

Since many of flexi carts features can be set using either manually submitted data, or data retrieved from the database; there are often two versions of a function to set session data. Functions that update session data using the database are prefixed with the function name 'update_xxx', whilst functions that use manually set data are prefixed with the name 'set_xxx'.

Set Location Session Data

Location Function Index | Location Config | Get Location Session Data | Get Location Helper Data | Location Admin Data
Set Location Data to Session

update_shipping_location() | update_tax_location() | update_location()

Help with Setting Session Data Functions

Show / Hide Help

Name: The name of the function (method).

Data Type: The data type that is expected by the function.

  • bool : Requires a boolean value of 'TRUE' or 'FALSE'.
  • string : Requires a textual value.
  • int : Requires a numeric value. It does not matter whether the value is an integer, float, decimal etc.
  • array : Requires an array.

Required: Defines whether the parameter requires a value to be submitted.

Default: Defines the default parameter value that is used if no other value is submitted.

update_shipping_location()

Updates the carts shipping locationUpdates the carts shipping location.
The location can then be used to calculate shipping rates for specific locations and zones.

Library and Requirements

Available via the standard library only.

Requires location database tables to be enabled.

Function Parameters
update_shipping_location(locations, update_shipping, recalculate_cart) Help
Name Data Type Required Default Description
locations string | int | array No FALSE Can be either a string, int, or an array of values, that the function will attempt to match against location ids and names within the location table.
update_shipping bool No TRUE Defines whether the carts shipping option and rate should be updated.
recalculate_cart bool No TRUE Define if all cart totals must be recalculated on success, regardless of whether the function has determined to do so or not.
The purpose of this is prevent multiple unnecessary recalculations of the cart if this function is used with other cart updating functions.
How it Works

The function compares the submitted location data to the carts current shipping data, if it is different, the new shipping location is updated.

The function then checks the 'update_shipping' parameter for whether the cart shipping option and rate should also be updated.

If no location data is submitted, the function will use the default shipping location defined via the database or config file.

Notes

If setting location data as a location name, ensure the value is of a string data type.
If a location name is numeric, like a zip code, the function may confuse the zip code as a location id.
This can be prevented by type casting the location name like this (string)'10101', see the example section below.

Zone names or ids cannot be set as a location, as the cart internally checks which zone the current location is related to.

This function can also be set via the 'update_cart()' function.

Return Values

Not Updated:FALSE | A status message will be set.

Updated:TRUE | A status message will be set.

Examples
// Example #1 : Update the location using a string or an int.

$location_data = 'New York';

$this->flexi_cart->update_shipping_location($location_data);

// Example #2 : Update the location using an array of strings and ints.

// Type cast numeric locations (i.e. Zip Codes) as strings to prevent the function using 
// the number as a table row id.
$location_data = array(
'New York', 
(string)'10101', // Zip Code example.
10 // Table row id example.
);

$this->flexi_cart->update_shipping_location($location_data);

update_tax_location()

Updates the carts tax location.
The location can then be used to calculate tax rates for specific locations and zones.

Library and Requirements

Available via the standard library only.

Requires location database tables to be enabled.

Function Parameters
update_tax_location(locations, update_tax, recalculate_cart) Help
Name Data Type Required Default Description
locations string | int | array No FALSE Can be either a string, int, or an array of values, that the function will attempt to match against location ids and names within the location table.
update_tax bool No TRUE Defines whether the carts tax rate should be updated.
recalculate_cart bool No TRUE Define if all cart totals must be recalculated on success, regardless of whether the function has determined to do so or not.
The purpose of this is prevent multiple unnecessary recalculations of the cart if this function is used with other cart updating functions.
How it Works

The function compares the submitted location data to the carts current tax data, if it is different, the new tax location is updated.

The function then checks the 'update_tax' parameter for whether the cart tax rate should also be updated.

If no location data is submitted, the function will use the default tax location defined via the database or config file.

Notes

If setting location data as a location name, ensure the value is of a string data type.
If a location name is numeric, like a zip code, the function may confuse the zip code as a location id.
This can be prevented by type casting the location name like this (string)'10101', see the example section below.

Zone names or ids cannot be set as a location, as the cart internally checks which zone the current location is related to.

This function can also be set via the 'update_cart()' function.

Return Values

Not Updated:FALSE | A status message will be set.

Updated:TRUE | A status message will be set.

Examples
// Example #1 : Update the location using a string or an int.

$location_data = 'New York';

$this->flexi_cart->update_tax_location($location_data);

// Example #2 : Update the location using an array of strings and ints.

// Type cast numeric locations (i.e. Zip Codes) as strings to prevent the function using 
// the number as a table row id.
$location_data = array(
'New York', 
(string)'10101', // Zip Code example.
10 // Table row id example.
);

$this->flexi_cart->update_tax_location($location_data);

update_location()

Updates the carts shipping and tax data to the same location.
The location can then be used to calculate shipping and tax rates for specific locations and zones.

Library and Requirements

Available via the standard library only.

Requires location database tables to be enabled.

Function Parameters
update_location(locations, update_dependents, recalculate_cart) Help
Name Data Type Required Default Description
locations string | int | array No FALSE Can be either a string, int, or an array of values, that the function will attempt to match against location ids and names within the location table.
update_dependents bool No TRUE Defines whether the carts shipping option and tax rate should be updated.
recalculate_cart bool No TRUE Define if all cart totals must be recalculated on success, regardless of whether the function has determined to do so or not.
The purpose of this is prevent multiple unnecessary recalculations of the cart if this function is used with other cart updating functions.
How it Works

The function compares the submitted location data to the carts current shipping and tax data, if it is different, the new location is updated.

The function then checks the 'update_tax' parameter for whether the cart tax rate should also be updated.

If no location data is submitted, the function will use the default shipping and tax locations defined via the database or config file.

Notes

If setting location data as a location name, ensure the value is of a string data type.
If a location name is numeric, like a zip code, the function may confuse the zip code as a location id.
This can be prevented by type casting the location name like this (string)'10101', see the example section below.

Zone names or ids cannot be set as a location, as the cart internally checks which zone the current location is related to.

This function can also be set via the 'update_cart()' function.

Return Values

Not Updated:FALSE | A status message will be set.

Updated:TRUE | A status message will be set.

Examples
// Example #1 : Update the location using a string or an int.

$location_data = 'New York';

$this->flexi_cart->update_location($location_data);

// Example #2 : Update the location using an array of strings and ints.

// Type cast numeric locations (i.e. Zip Codes) as strings to prevent the function using 
// the number as a table row id.
$location_data = array(
'New York', 
(string)'10101', // Zip Code example.
10 // Table row id example.
);

$this->flexi_cart->update_location($location_data);
Copyright © 2024, Rob Hussey, All Rights Reserved.
flexi cart was designed and developed by