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

List all Cart Functions | Get Cart Item Session Data | Get Cart Summary Session Data | Get Cart Session Data
Insert and Update Cart Items

insert_items() | update_cart()

Manage Cart Contents

recalculate_cart() | unset_admin_data() | empty_cart() | destroy_cart()

Status and Error Messages

status_messages() | set_status_message() | clear_status_messages() | error_messages() | set_error_message() | clear_error_messages() | clear_messages() | get_messages_array() | get_messages()

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.

insert_items()

Inserts an item or multiple items to the cart.

Library and Requirements

Available via the standard library only.

Does not require any database tables to be enabled.

Function Parameters
insert_items(item_data, update_existing_items) Help
Name Data Type Required Default Description
item_data array Yes FALSE The array contains the item data that is to be inserted into the cart.
See the documentation below regarding how to set data.
update_existing_items bool No FALSE Define whether the submitted data should overwrite any matching item data that already exists in the cart.
How it Works

The function loops through the 'item_data' checking that the required columns are present and valid.

The function then generates a row id from the items id and any item options that have been set. If the row id already exists in the cart, depending on config settings, the existing cart item is updated with the new data, otherwise, the new data is added to the cart as a new item.

Once all item data has been processed, all cart values are recalculated.

Setting 'item_data' Array

The 'item_data' array can contain data for multiple items. To add one item use a single dimesional array, to add multiple items, use a multi-dimensional array. See the examples below for further details.

All array keys in the 'item_data' array must be the alias column name that has been set via the config. file, not the internal column name.

For example, using the default config. file setup, the cart item quantity column is setup as follows:
$config['cart']['items']['columns']['item_quantity'] = 'quantity';
The array key 'item_quantity' is the internal name, and the array value 'quantity' is the alias name.

When setting the array keys for the carts item quantity column in the 'item_data' array, it would be set as 'quantity' and NOT 'item_quantity'.

See below for further examples and read the 'Cart Column Configuration' for further information on cart columns that can be set.

When setting currency values, ensure the values match the carts default currency and tax settings.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example
// Example #1 : Adding 1 item to the cart using a single-dimensional array.

$item_data = array(
'id' => 101,
'name' => 'Example Item Name #1',
'quantity' => 3,
'price' => 10.99
);

$this->flexi_cart->insert_items($item_data);

// Example #2 : Adding multiple items to the cart using a multi-dimensional array.

$item_data = array(
array(
	'id' => 101,
	'name' => 'Example Item Name #1',
	'quantity' => 3,
	'price' => 10.99
),
array(
	'id' => 102,
	'name' => 'Example Item Name #2',
	'quantity' => 1,
	'price' => 25.49
)
)

$this->flexi_cart->insert_items($item_data);

update_cart()

Updates the cart with submitted item and summary data.

Library and Requirements

Available via the standard library only.

Does not require any database tables to be enabled.

Function Parameters
update_cart(item_data, settings_data, force_column_update, force_recalculate) Help
Name Data Type Required Default Description
item_data array Yes FALSE The array contains the item data that is to be update in the cart.
See the documentation below regarding how to set data.
settings_data array No FALSE Submitted settings data will update the carts location, shipping, tax, discount, surcharge and currency data.
See the documentation below regarding how to set data.
force_column_update bool No FALSE Define if all submitted data is updated regardless of whether the columns present are defined as 'Updatable Columns'.
force_recalculate bool No FALSE Define if all cart totals must be recalculated on success, regardless of whether the function has determined to do so.
How it Works

The function loops through the 'item_data' and sets the data to the cart session array.

The function then loops through the 'settings_data' and where available, updates the carts location, shipping, tax, discount, surcharge and currency data.

Once all item data has been processed, all cart values are recalculated.

Setting 'item_data' Array

The 'item_data' array can contain data for multiple items. To update one item use a single dimesional array, to update multiple items, use a multi-dimensional array. See the examples below for further details.

All array keys in the 'item_data' array must be the alias column name that has been set via the config. file, not the internal column name.

For example, using the default config. file setup, the cart item quantity column is setup as follows:
$config['cart']['items']['columns']['item_quantity'] = 'quantity';
The array key 'item_quantity' is the internal name, and the array value 'quantity' is the alias name.

When setting the array keys for the carts item quantity column in the 'item_data' array, it would be set as 'quantity' and NOT 'item_quantity'.

See below for further examples and read the 'Cart Column Configuration' for further information on cart columns that can be set.

When setting currency values, ensure the values match the carts default currency and tax settings.

Setting 'settings_data' Array

All array keys in the 'settings_data' array must refer to the name of the flexi cart function that the data is intended to be updated by.

The available functions to call using the 'settings_data' are as follows:

  • 'update_shipping_location' - Update the current shipping location, using the database.
  • 'update_shipping' - Update the current shipping option, using the database.
  • 'set_shipping' - Update the current shipping option, using manually submitted values.
  • 'update_tax_location' - Update the current tax location and rate, using the database.
  • 'set_tax' - Update the current tax rate, using the database.
  • 'update_discount_codes' - Update the discount codes applied to the cart.
  • 'set_discount' - Set a discount to the cart, using manually submitted values.
  • 'set_surcharge' - Set a surcharge to the cart, using manually submitted values.
  • 'update_currency' - Update the carts currency, using the database.
  • 'set_currency' - Set carts currency, using manually submitted values.

The data that is then submitted to the defined function must be prepared and structured as the standalone function would normally require.
For further details on each function, click the corresponding function name from above.

When setting currency values, ensure the values match the carts default currency and tax settings.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example
// Example #1 : Updating the item quantity of 1 item in the cart using a single-dimensional array.

$item_data = array(
'row_id' => '38b3eff8baf56627478ec76a704e9b52',
'quantity => 4
);

$this->flexi_cart->update_cart($item_data);

// Example #2 : Updating the item quantity of multiple items in the cart using a multi-dimensional array.

$item_data = array(
array(
	'row_id' => '38b3eff8baf56627478ec76a704e9b52',
	'quantity => 4
),
array(
	'row_id' => 'c45147dee729311ef5b5c3003946c48f',
	'quantity => 1
)
);

$this->flexi_cart->update_cart($item_data);

// Example #3 : Updating the items in the cart and cart settings data using a multi-dimensional array.

// Preparing item data.
$item_data = array(
array(
	'row_id' => '38b3eff8baf56627478ec76a704e9b52',
	'name => 'example_name_1',
	'quantity => 4
),
array(
	'row_id' => 'c45147dee729311ef5b5c3003946c48f',
	'name => 'example_name_2',
	'quantity => 1
)
);

// Preparing cart settings data.
$settings_data = array(
'update_shipping_location' => 'New York',
'set_tax' => array(
	'name' => 'New York Tax',
	'rate' => 8.37
)
);

$this->flexi_cart->update_cart($item_data, $settings_data);

recalculate_cart()

Recalculates all values within the cart.

Library and Requirements

Available via the standard library only.

Does not require any database tables to be enabled.

Return Values

Failure:n/a

Success:TRUE

Example
$this->flexi_cart->recalculate_cart();

unset_admin_data()

Unsets any 'admin data' that is present in the cart session.

Library and Requirements

Available via the standard library only.

Does not require any database tables to be enabled.

Notes

For further information on 'admin data', read the documentation.

Return Values

Failure:n/a

Success:TRUE | A status message will be set.

Example
$this->flexi_cart->unset_admin_data();

empty_cart()

Empties the cart of all items.

Library and Requirements

Available via the standard library only.

Does not require any database tables to be enabled.

Function Parameters
empty_cart(reset_shipping) Help
Name Data Type Required Default Description
reset_shipping bool No TRUE Defines whether to reset the current shipping option when emptying the cart.
Return Values

Failure:n/a

Success:TRUE

Example
$reset_shipping = FALSE;

$this->flexi_cart->empty_cart($reset_shipping);

destroy_cart()

Destroys the entire cart data session.

Library and Requirements

Available via the standard library only.

Does not require any database tables to be enabled.

Return Values

Failure:n/a

Success:TRUE

Example
$this->flexi_cart->destroy_cart();

status_messages()

Get any status message(s) that may have been set by recently run functions.

Library and Requirements

Available via the lite, standard and admin libraries.

Does not require any database tables to be enabled.

Function Parameters
status_messages(target_user, prefix_delimiter, suffix_delimiter) Help
Name Data Type Required Default Description
target_user string No 'public' Define whether to suppress any 'admin' error messages and only return 'public' messages intended for notifying public users.
Defining 'public' will return the message for both public and admin users.
Defining 'admin' will return the message for admin users only.
prefix_delimiter string No FALSE Define a string of characters to prefix to the status message.
Typically this is intended to allow elements to be wrapped around messages.
If no prefix is set, the 'status_prefix_delimiter' defined via the config. file is used instead.
suffix_delimiter string No FALSE Define a string of characters to suffix to the status message.
Typically this is intended to allow elements to be wrapped around messages.
If no suffix is set, the 'status_suffix_delimiter' defined via the config. file is used instead.
Notes

The messages returned by flexi cart functions can be returned in other languages by defining the translation in CodeIgniters language directory.

To define your own translations, create a folder within the CI language directory named as the language, e.g. 'french'.
Then copy the 'flexi_cart_lang.php' file from the 'english' folder to the new language folder and translate the messages within the file.

For further information, read the CodeIgniter documentation on the language library.

Return Values

Failure:FALSE

Success:string

Examples
status_messages('admin', FALSE, FALSE) This would return all admin status messages as non formatted text.
status_messages('public', FALSE, FALSE) This would return all public and admin status messages as non formatted text.
status_messages('admin', '<p>', '</p>') This would return all admin status messages formatted in a html <p> tag.

set_status_message()

Set a status message to be displayed to the user.

Library and Requirements

Available via the lite, standard and admin libraries.

Does not require any database tables to be enabled.

Function Parameters
set_status_message(status_message, target_user, overwrite_existing) Help
Name Data Type Required Default Description
status_message string Yes FALSE Defines the status message to be set.
target_user string No 'public' Define whether to set the message as a 'public' or 'admin' status message.
overwrite_existing bool No FALSE Define whether to overwrite any existing status messages.
Return Values

Failure:n/a

Success:'status_message' parameter value

Examples
set_status_message('This is a custom ADMIN status message', 'admin', FALSE) This would set a status message that would NOT be shown in public areas of the site.
set_status_message('This is a custom PUBLIC status message', 'public', FALSE) This would set a status message that would be shown in public and admin areas of the site.
set_status_message('This is a custom PUBLIC status message', 'public', TRUE) This would overwrite any existing messages and then set a status message that would be shown in public and admin areas of the site.

clear_status_messages()

Clear all status messages.

Library and Requirements

Available via the lite, standard and admin libraries.

Does not require any database tables to be enabled.

Return Values

Failure:n/a

Success:TRUE

Examples
clear_status_messages() This would remove all currently set status messages.

error_messages()

Get any error message(s) that may have been set by recently run functions.

Library and Requirements

Available via the lite, standard and admin libraries.

Does not require any database tables to be enabled.

Function Parameters
error_messages(target_user, prefix_delimiter, suffix_delimiter) Help
Name Data Type Required Default Description
target_user string No 'public' Define whether to suppress any 'admin' error messages and only return 'public' messages intended for notifying public users.
Defining 'public' will return the message for both public and admin users.
Defining 'admin' will return the message for admin users only.
prefix_delimiter string No FALSE Define a string of characters to prefix to the error message.
Typically this is intended to allow elements to be wrapped around messages.
If no prefix is set, the 'error_prefix_delimiter' defined via the config. file is used instead.
suffix_delimiter string No FALSE Define a string of characters to suffix to the error message.
Typically this is intended to allow elements to be wrapped around messages.
If no suffix is set, the 'error_suffix_delimiter' defined via the config. file is used instead.
Notes

The messages returned by flexi cart functions can be returned in other languages by defining the translation in CodeIgniters language directory.

To define your own translations, create a folder within the CI language directory named as the language, e.g. 'french'.
Then copy the 'flexi_cart_lang.php' file from the 'english' folder to the new language folder and translate the messages within the file.

For further information, read the CodeIgniter documentation on the language library.

Return Values

Failure:FALSE

Success:string

Examples
error_messages('admin', FALSE, FALSE) This would return all admin error messages as non formatted text.
error_messages('public', FALSE, FALSE) This would return all public and admin error messages as non formatted text.
error_messages('admin', '<p>', '</p>') This would return all admin error messages formatted in a html <p> tag.

set_error_message()

Set an error message to be displayed to the user.

Library and Requirements

Available via the lite, standard and admin libraries.

Does not require any database tables to be enabled.

Function Parameters
set_error_message(error_message, target_user, overwrite_existing) Help
Name Data Type Required Default Description
error_message string Yes FALSE Defines the error message to be set.
target_user string No 'public' Define whether to set the message as a 'public' or 'admin' error message.
overwrite_existing bool No FALSE Define whether to overwrite any existing error messages.
Return Values

Failure:n/a

Success:'error_message' parameter value

Examples
set_error_message('This is a custom ADMIN error message', 'admin', FALSE) This would set an error message that would NOT be shown in public areas of the site.
set_error_message('This is a custom PUBLIC error message', 'public', FALSE) This would set an error message that would be shown in public and admin areas of the site.
set_error_message('This is a custom PUBLIC error message', 'public', TRUE) This would overwrite any existing messages and then set a error message that would be shown in public and admin areas of the site.

clear_error_messages()

Clear all error messages.

Library and Requirements

Available via the lite, standard and admin libraries.

Does not require any database tables to be enabled.

Return Values

Failure:n/a

Success:TRUE

Examples
clear_error_messages() This would remove all currently set error messages.

clear_messages()

Clear all status and error messages.

Library and Requirements

Available via the lite, standard and admin libraries.

Does not require any database tables to be enabled.

Return Values

Failure:n/a

Success:TRUE

Examples
clear_messages() This would remove all currently set status and error messages.

get_messages_array()

Returns any set messages, grouped into a 'status' and 'error' array.
The returned status and error messages are then further grouped into 'public' and 'admin' type messages.

Library and Requirements

Available via the lite, standard and admin libraries.

Does not require any database tables to be enabled.

Function Parameters
get_messages_array(target_user, prefix_delimiter, suffix_delimiter) Help
Name Data Type Required Default Description
target_user string No 'public' Define whether to suppress any 'admin' error messages and only return 'public' messages intended for notifying public users.
Defining 'public' will return the message for both public and admin users.
Defining 'admin' will return the message for admin users only.
prefix_delimiter string No FALSE Define a string of characters to prefix to the messages.
Typically this is intended to allow elements to be wrapped around messages.
If no prefix is set, the corresponding 'status_prefix_delimiter' and 'error_prefix_delimiter' defined via the config. file is used instead.
suffix_delimiter string No FALSE Define a string of characters to suffix to the messages.
Typically this is intended to allow elements to be wrapped around messages.
If no suffix is set, the corresponding 'status_suffix_delimiter' and 'error_suffix_delimiter' defined via the config. file is used instead.
Notes

The messages returned by flexi cart functions can be returned in other languages by defining the translation in CodeIgniters language directory.

To define your own translations, create a folder within the CI language directory named as the language, e.g. 'french'.
Then copy the 'flexi_cart_lang.php' file from the 'english' folder to the new language folder and translate the messages within the file.

For further information, read the CodeIgniter documentation on the language library.

Return Values

Failure:FALSE

Success:array

Examples
get_messages_array('admin', FALSE, FALSE) This would return an array of all the admin status and error messages as non formatted text, with an array key indicating the message type.
get_messages_array('public', FALSE, FALSE) This would return an array of all the public and admin status and error messages as non formatted text, with an array key indicating the message type.
get_messages_array('admin', '<p>', '</p>') This would return an array of all the admin status and error messages formatted in a html <p> tag, with an array key indicating the message type.

get_messages()

Get any operational function messages whether of status or error type and format their output with delimiters.

Library and Requirements

Available via the lite, standard and admin libraries.

Does not require any database tables to be enabled.

Function Parameters
get_messages(target_user, prefix_delimiter, suffix_delimiter) Help
Name Data Type Required Default Description
target_user string No 'public' Define whether to suppress any 'admin' error messages and only return 'public' messages intended for notifying public users.
Defining 'public' will return the message for both public and admin users.
Defining 'admin' will return the message for admin users only.
prefix_delimiter string No FALSE Define a string of characters to prefix to the messages.
Typically this is intended to allow elements to be wrapped around messages.
If no prefix is set, the corresponding 'status_prefix_delimiter' and 'error_prefix_delimiter' defined via the config. file is used instead.
suffix_delimiter string No FALSE Define a string of characters to suffix to the messages.
Typically this is intended to allow elements to be wrapped around messages.
If no suffix is set, the corresponding 'status_suffix_delimiter' and 'error_suffix_delimiter' defined via the config. file is used instead.
Notes

The messages returned by flexi cart functions can be returned in other languages by defining the translation in CodeIgniters language directory.

To define your own translations, create a folder within the CI language directory named as the language, e.g. 'french'.
Then copy the 'flexi_cart_lang.php' file from the 'english' folder to the new language folder and translate the messages within the file.

For further information, read the CodeIgniter documentation on the language library.

Return Values

Failure:FALSE

Success:string

Examples
get_messages('admin', FALSE, FALSE) This would return all admin status and error messages as non formatted text.
get_messages('public', FALSE, FALSE) This would return all public and admin status and error messages as non formatted text.
get_messages('admin', '<p>', '</p>') This would return all admin status and error messages formatted in a html <p> tag.
Copyright © 2024, Rob Hussey, All Rights Reserved.
flexi cart was designed and developed by