User Guide | Setting Surcharge 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 Surcharge Session Data

Surcharge Function Index | Get Surcharge Session Data
Set Surcharge Data to Session

set_surcharge()

Unset Session Surcharge Data

unset_surcharge()

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.

set_surcharge()

Manually set or update a cart summary surcharge as either a fixed value or a percentage based on a cart summary column value.

Library and Requirements

Available via the standard library only.

Does not require any database tables to be enabled.

Function Parameters
set_surcharge(surcharge_data, recalculate_cart) Help
Name Data Type Required Default Description
surcharge_data array Yes FALSE The array contains the surcharge data that is to update the carts surcharge data.
See the notes and examples below for further information.
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 loops through the 'surcharge_data' array and sets any data from the following array keys to the cart surcharge data.

The valid array keys are 'id', 'description', 'value', 'column' and 'tax_rate'.

  • 'id' - The id to reference the surcharge by if updating or deleting it.
  • 'description' - The description of the surcharge.
  • 'value' - The value of the surcharge. If a 'column' value is not set, the surcharge is applied as a fixed rate surcharge, otherwise it's applied as a percentage based surcharge calculated against the 'column' value. Submitted values must be numeric.
  • 'column' - If applying a percentage based surcharge, the summary column to apply the surcharge against must be submitted.
    Valid column names are 'item_summary_total', 'shipping_total' and 'total'.
  • 'tax_rate' - Tax rate applied to surcharge value, the carts tax value is used if no value is submitted. Submitted values must be numeric.
Notes

As well as setting new surcharges, this function can be used to update an existing surcharge too. When updating a surcharge, simply include the id of the to-be-updated surcharge in the 'surcharge_data' array. The other data in the array will then be used to update the surcharge.

Multiple surcharges can be applied to the same summary column.

If multiple percentage based surcharges are applied to the same column, the surcharge is based on the columns original non-surcharged value. This prevents the cart from surcharging a surcharge.

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

Return Values
Failure:FALSE | An error message will be set.
Success:TRUE | A status message will be set.
Example
$surcharge_data = array(
	'id' => 'example_id',
	'description' => 'Example Description',
	'value' => 10,
	'column' => 'total', // Percentage based surcharge on cart total column
	'tax_rate' => 20 // 20% tax
);

$this->flexi_cart->set_surcharge($surcharge_data);

unset_surcharge()

Remove surcharges from the cart session data.

Library and Requirements

Available via the standard library only.

Does not require any database tables to be enabled.

Function Parameters
unset_surcharge(surcharge_data, recalculate_cart) Help
Name Data Type Required Default Description
surcharge_data string | int | array No FALSE Can be either a string, int, or an array of values, that the function will attempt to match against surcharge ids within the cart data.
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 loops through the 'surcharge_data' and attempts to match the data against any surcharge ids that are in the cart surcharge data. If a match is found, the surcharge is unset from the cart session data.

If no 'surcharge_data' is submitted, then all surcharges are removed.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example
// Example #1 : Unsetting a surcharge via either a string or int value.
$surcharge_id = 'example_id';

$this->flexi_cart->unset_surcharge($surcharge_id);

// Example #2 : Unsetting a surcharge via an array of either string or int values.
$surcharge_ids = array(
	'example_id_1',
	'example_id_2'
);

$this->flexi_cart->unset_surcharge($surcharge_ids);

// Example #3 : Unsetting all surcharges.
$this->flexi_cart->unset_surcharge();
Copyright © 2024, Rob Hussey, All Rights Reserved.
flexi cart was designed and developed by