User Guide | Currency Helper Data

Helper functions are used to provide value formatting and calculation functionality, or to return data from the carts database tables.

The functions can act independently of data within the cart session, using database table ids or custom data directly submitted to the function to return values, rather than for example requiring the row id of an item in the cart.

This independence from data within the cart session means the functions can be used on pages across a site that do not display cart data, or even on items that have not been added to the cart.

Currency Helper Functions

Currency Function Index | Currency Config | Get Currency Session Data | Set Currency Session Data | Currency Admin Data
Format Currency Values

format_currency()

Calculate Currency Values

get_currency_value() | get_taxed_currency_value()

Get Currency Data from Database

get_currency_data() | get_currency_symbol() | get_exchange_rate()

Help with Helper 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.

format_currency()

Returns the submitted value formatted to a specified number of decimals using the specified currencies decimal and thousand separators.

Library and Requirements

Available via the lite, standard and admin libraries.

Does not require any database tables to be enabled.

Note: The currency database table must be enabled, if the 'currency_name' parameter is set.

Function Parameters
format_currency(value, format, decimals, internal_value, currency_name) Help
Name Data Type Required Default Description
value int Yes FALSE Sets the value to be formatted.
format bool No TRUE Define whether to format the returned value as a currency.
decimals int No 2 Defines the number of decimals to return the value with.
internal_value bool No FALSE Defines whether to return the value using the carts internal currency instead of the users current currency.
currency_name string No FALSE Define a specific currency to obtain the format settings from.
If a currency name is not set, the users current currency is used.
Note: Use of this parameter requires the currency database table to be enabled.
Notes

If a 'currency_name' is submitted that is not found in the database, the current cart session currency settings will be used to format the value.

Return Values

Failure:n/a

Success:int | (string if value is formatted)

Examples
Note: The returned example values below are displaying live data from the current cart session data.
format_currency(10, TRUE, 2, FALSE, FALSE) Format the number '10' to 2 decimals, using the format settings for the current currency. £10.00
format_currency(10, TRUE, 2, TRUE, FALSE) Format the number '10' to 2 decimals, using the format settings for the carts Internal currency. £10.00
format_currency(10, TRUE, 2, FALSE, 'AUD') Format the number '10' to 2 decimals, using the format settings for Australian Dollars. AU $10.00

get_currency_value()

Converts a value from a specified currency to the carts internal currency or vice versa.

This function is similar to 'get_taxed_currency_value()', with the exception it does NOT check whether cart prices include tax, therefore, values are directly converted from one value to another without adding or removing taxes during the conversion.

Library and Requirements

Available via the lite, standard and admin libraries.

Does not require any database tables to be enabled.

Note: The currency database table must be enabled, if the 'currency_name' parameter is set.

Function Parameters
get_currency_value(value, format, decimals, inverse, currency_name) Help
Name Data Type Required Default Description
value int Yes 0 Sets the value to be converted.
format bool No TRUE Define whether to format the returned value as a currency.
decimals int No 2 Defines the number of decimals to return the value with.
inverse bool No FALSE Define whether to inverse the exchange rate conversion.
If 'TRUE', the conversion is from the internal currency to 'x' currency.
If 'FALSE', the conversion is from the 'x' currency to the internal currency.
currency_name string No FALSE Define a specific currency to obtain the exchange rate from.
If a currency name is not set, the users current currency is used.
Note: Use of this parameter requires the currency database table to be enabled.
Return Values

Failure:n/a

Success:int | (string if value is formatted)

Examples
Note: The returned example values below are displaying live data from the current cart session data.
get_currency_value(10, TRUE, 2, FALSE, FALSE) What is £10, converted to the current currency (GBP)? £10.00
get_currency_value(10, TRUE, 2, TRUE, FALSE) What is £10, converted to the carts internal currency (GBP)? £10.00
get_currency_value(10, TRUE, 2, FALSE, 'AUD') What is £10, converted to Australian Dollars? AU $20.00
get_currency_value(10, TRUE, 2, TRUE, 'AUD') What is AU $10, converted to the carts internal currency (GBP)? £5.00

get_taxed_currency_value()

Converts a value from a specified currency to the carts internal currency or vice versa.

This function is similar to 'get_currency_value()', with the exception of its handling of taxes, read the notes below for further information.

Library and Requirements

Available via the lite, standard and admin libraries.

Does not require any database tables to be enabled.

Note: The currency database table must be enabled, if the 'currency_name' parameter is set.

Function Parameters
get_taxed_currency_value(value, tax_rate, format, decimals, inverse, currency_name) Help
Name Data Type Required Default Description
value int Yes FALSE Sets the value to be converted.
tax_rate int No FALSE Defines a specific tax rate to use with the conversion.
If a tax rate is not set, the carts default tax rate is used.
format bool No TRUE Define whether to format the returned value as a currency.
decimals int No 2 Defines the number of decimals to return the value with.
inverse bool No FALSE Define whether to inverse the exchange rate conversion.
If 'TRUE', the conversion is from the internal currency to 'x' currency.
If 'FALSE', the conversion is from the 'x' currency to the internal currency.
currency_name string No FALSE Define a specific currency to obtain the exchange rate from.
If a currency name is not set, the users current currency is used.
Note: Use of this parameter requires the currency database table to be enabled.
Notes

This function is similar to 'get_currency_value()', with the exception that the returned value varies depending on whether the cart is configured to include tax on internal pricing and whether the user if viewing pricing including tax.

Example: If cart prices include tax and the user is viewing prices excluding tax. The function will remove the tax from the to-be-converted value.
If the cart and user tax settings are reversed, the function will add the tax. If both the cart and user tax settings match each other, the tax is neither added or removed.

This function would typically be used when displaying a value based on the carts internal pricing, like an items price. The function would then automatically convert the price accordingly to whether the user is view prices including or excluding prices.

Return Values

Failure:n/a

Success:int | (string if value is formatted)

Examples
Note: The returned example values below are displaying live data from the current cart session data.
get_taxed_currency_value(10, FALSE, TRUE, 2, FALSE, FALSE) What is £10, converted to the current currency (GBP), using the carts default tax rate? £10.00
get_taxed_currency_value(10, FALSE, TRUE, 2, TRUE, FALSE) What is £10, converted to the carts internal currency (GBP), using the carts default tax rate? £10.00
get_taxed_currency_value(10, FALSE, TRUE, 2, FALSE, 'AUD') What is £10, converted to Australia Dollars, using the carts default tax rate? AU $20.00
get_taxed_currency_value(10, FALSE, TRUE, 2, TRUE, 'AUD') What is AU $10, converted to the carts internal currency (GBP), using the carts default tax rate? £5.00
get_taxed_currency_value(10, 5, TRUE, 2, FALSE, FALSE) What is £10, converted to the current currency (GBP), with a defined tax rate of 5%? £10.00
get_taxed_currency_value(10, 5, TRUE, 2, TRUE, FALSE) What is £10, converted to the carts internal currency (GBP), with a defined tax rate of 5%? £10.00
get_taxed_currency_value(10, 5, TRUE, 2, FALSE, 'AUD') What is £10, converted to Australian Dollars, with a defined tax rate of 5%? AU $20.00
get_taxed_currency_value(10, 5, TRUE, 2, TRUE, 'AUD') What is AU $10, converted to the carts internal currency (GBP), with a defined tax rate of 5%? £5.00

get_currency_data()

Looks-up the database and returns an array of currency data.

Library and Requirements

Available via the lite, standard and admin libraries.

Requires currency database table to be enabled.

Function Parameters
get_currency_data(sql_select, sql_where) Help
Name Data Type Required Default Description
sql_select string | array No FALSE Define the database fields returned via an SQL SELECT statement.
Read the defining SQL documentation for further information.
sql_where string | int | array No FALSE Set the SQL WHERE statement used to filter the database records to return.
Read the defining SQL documentation for further information.
Return Values

Failure:FALSE

Success:array

Examples
Note: The returned example values below are displaying live data from the current cart session data.
get_currency_data(FALSE, FALSE) Show all database currency data. Show / Hide Array 
Array
(
    [0] => Array
        (
            [curr_id] => 1
            [curr_name] => AUD
            [curr_exchange_rate] => 2.0000
            [curr_symbol] => AU $
            [curr_symbol_suffix] => 0
            [curr_thousand_separator] => ,
            [curr_decimal_separator] => .
            [curr_status] => 1
            [curr_default] => 0
        )

    [1] => Array
        (
            [curr_id] => 2
            [curr_name] => EUR
            [curr_exchange_rate] => 1.1500
            [curr_symbol] => €
            [curr_symbol_suffix] => 1
            [curr_thousand_separator] => .
            [curr_decimal_separator] => ,
            [curr_status] => 1
            [curr_default] => 0
        )

    [2] => Array
        (
            [curr_id] => 3
            [curr_name] => GBP
            [curr_exchange_rate] => 1.0000
            [curr_symbol] => £
            [curr_symbol_suffix] => 0
            [curr_thousand_separator] => ,
            [curr_decimal_separator] => .
            [curr_status] => 1
            [curr_default] => 1
        )

    [3] => Array
        (
            [curr_id] => 4
            [curr_name] => USD
            [curr_exchange_rate] => 1.6000
            [curr_symbol] => US $
            [curr_symbol_suffix] => 0
            [curr_thousand_separator] => ,
            [curr_decimal_separator] => .
            [curr_status] => 1
            [curr_default] => 0
        )

)
get_currency_data('curr_name, curr_exchange_rate', array('curr_id' => 2)) Show the name and exchange rate of the database currency with an id of '2'. Show / Hide Array 
Array
(
    [0] => Array
        (
            [curr_name] => EUR
            [curr_exchange_rate] => 1.1500
        )

)

get_currency_symbol()

Looks-up the database and returns the currency symbol (Example $, €, £) of a specified currency.

Library and Requirements

Available via the lite, standard and admin libraries.

Requires currency database table to be enabled.

Function Parameters
get_currency_symbol(internal_value, currency_name) Help
Name Data Type Required Default Description
internal_value bool No FALSE Defines whether to return the value of the carts internal currency instead of the users current currency.
currency_name string No FALSE Define a specific currency to obtain the format settings from.
If a currency name is not set, the users current currency is used.
Note: Use of this parameter requires the currency database table to be enabled.
Notes

If a 'currency_name' is submitted that is not found in the database, the current cart session currency settings will be used to format the value.

Return Values

Failure:n/a

Success:string

Examples
Note: The returned example values below are displaying live data from the current cart session data.
get_currency_symbol(FALSE) What is the current currency symbol used to display monetary values? £
get_currency_symbol(TRUE) What is the internal currency symbol used to display monetary values? £

get_exchange_rate()

Looks-up the database and returns the exchange rate of a submitted currency in comparison to the sites internal currency.

Library and Requirements

Available via the lite, standard and admin libraries.

Requires currency database table to be enabled.

Function Parameters
get_exchange_rate(currency_name, decimals) Help
Name Data Type Required Default Description
currency_name string No FALSE Define a specific currency to obtain the format settings from.
If a currency name is not set, the users current currency is used.
Note: Use of this parameter requires the currency database table to be enabled.
decimals int No 4 Defines the number of decimals to return the value with.
Notes

If a 'currency_name' is submitted that is not found in the database, the current cart session exchange rate will be returned.

Return Values

Failure:n/a

Success:int

Examples
Note: The returned example values below are displaying live data from the current cart session data.
get_exchange_rate('AUD', 2) What is the exchange rate conversion between Australian Dollars and the carts internal currency, to two decimals? 2.00
Copyright © 2024, Rob Hussey, All Rights Reserved.
flexi cart was designed and developed by