Currencies extends AppModel
Currency Management
Table of Contents
Methods
| __construct() | Initialize Currencies |
| add() | Adds a new currency |
| convert() | Converts an amount from one currency to another using the exchange rate |
| delete() | Deletes an existing currency |
| edit() | Edits an existing currency |
| get() | Fetches a currency using the given currency code |
| getAll() | Fetches a full list of all currencies for a given company |
| getExchangeRateProcessor() | Retrieves an instance of the exchange rate processor. |
| getExchangeRateProcessors() | Retrieves a list of exchange rate processors |
| getFormats() | Returns an array containing every supported currency format with an example in key/value pairs |
| getList() | Fetches a list of all currencies for a given company |
| getListCount() | Returns the total number of currencies returned from Currencies::getList(), useful in constructing pagination for the getList() method. |
| toCurrency() | Converts the given decimal value into a currency value. |
| toCurrencyValue() | Converts the given decimal value into a currency value excluding the prefix, suffix, and currency code symbols |
| toDecimal() | Converts a currency value into a decimal representation based on ISO 31-0 |
| updateRates() | Updates all currency exchange rates for the current company using the configured processor. |
| validateCurrencyExists() | Validates a currency exists |
| validateCurrencyFormat() | Validates a currency's 'format' field |
| validateCurrencyInUse() | Checks if a currency code is currently in use |
| validateCurrencyIsDefault() | Checks if the given currency code is set as the default currency |
| getCurrencies() | Partially constructs the query required by Currencies::getList(), Currencies::getListCount(), and Currencies::getAll() |
| getRules() | Returns the rule set for adding/editing currencies |
Methods
__construct()
Initialize Currencies
public
__construct() : mixed
add()
Adds a new currency
public
add(array<string|int, mixed> $vars) : mixed
Parameters
- $vars : array<string|int, mixed>
-
An array of currency info including:
- code The ISO 4217 currency code
- company_id The Company ID
- format The format code to use for this currency
- precision The decimal precision to use for this currency
- prefix The prefix to use for this currency
- suffix The suffix to use for this currency
- exchange_rate The exchange rate in relation to the primary currency
- exchange_updated The datetime the exchange_rate was last updated
convert()
Converts an amount from one currency to another using the exchange rate
public
convert(float $amount, string $from_currency, string $to_currency, int $company_id) : float
Parameters
- $amount : float
-
The amount to convert
- $from_currency : string
-
The ISO 4217 currency code format representing $amount
- $to_currency : string
-
The ISO 4217 currency code to format to
- $company_id : int
-
The ID of the company
Return values
float —The $amount converted between currencies
delete()
Deletes an existing currency
public
delete(string $currency_code, int $company_id) : mixed
Parameters
- $currency_code : string
-
The ISO 4217 currency code we are deleting
- $company_id : int
-
The Company ID for this currency code
edit()
Edits an existing currency
public
edit(string $currency_code, int $company_id, array<string|int, mixed> $vars) : mixed
Parameters
- $currency_code : string
-
The ISO 4217 currency code we are updating
- $company_id : int
-
The Company ID for this currency code
- $vars : array<string|int, mixed>
-
An array of currency info including:
- format The format code to use for this currency
- precision The decimal precision to use for this currency
- prefix The prefix to use for this currency
- suffix The suffix to use for this currency
- exchange_rate The exchange rate in relation to the primary currency
- exchange_updated The datetime the exchange_rate was last updated
get()
Fetches a currency using the given currency code
public
get(string $currency_code, int $company_id) : mixed
Parameters
- $currency_code : string
-
The ISO 4217 currency code to fetch on
- $company_id : int
-
The ID of the company whose currency to fetch
Return values
mixed —stdClass object representing the currency if it exists, false otherwise
getAll()
Fetches a full list of all currencies for a given company
public
getAll(int $company_id) : mixed
Parameters
- $company_id : int
-
The ID of the company to fetch currencies for
Return values
mixed —An array of stdClass objects representing all currencies, or false if no currencies found
getExchangeRateProcessor()
Retrieves an instance of the exchange rate processor.
public
getExchangeRateProcessor(string $processor) : bool|ExchangeRate
Sets Input errors if the processor cannot not be found.
Parameters
- $processor : string
-
The name of the exchange rate processor (e.g. google_finance)
Return values
bool|ExchangeRate —An instance of the ExchangeRate processor if found, otherwise boolean false
getExchangeRateProcessors()
Retrieves a list of exchange rate processors
public
getExchangeRateProcessors() : array<string|int, mixed>
Return values
array<string|int, mixed> —A list of exchange rate processors
getFormats()
Returns an array containing every supported currency format with an example in key/value pairs
public
getFormats() : array<string|int, mixed>
Return values
array<string|int, mixed> —An array of currency formats in key/value pairs where the key is the format and the value is an example
getList()
Fetches a list of all currencies for a given company
public
getList(int $company_id[, int $page = 1 ][, string $order_by = ['code' => 'ASC'] ]) : mixed
Parameters
- $company_id : int
-
The ID of the company to fetch currencies for
- $page : int = 1
-
The page to return results for (optional, default 1)
- $order_by : string = ['code' => 'ASC']
-
The sort and order conditions (e.g. array('sort_field'=>"ASC"), optional)
Return values
mixed —An array of stdClass objects representing currencies, false if no currencies found
getListCount()
Returns the total number of currencies returned from Currencies::getList(), useful in constructing pagination for the getList() method.
public
getListCount(int $company_id) : int
Parameters
- $company_id : int
-
The ID of the company to fetch currencies for
Tags
Return values
int —The total number of currencies
toCurrency()
Converts the given decimal value into a currency value.
public
toCurrency(float $value, string $currency[, int $company_id = null ][, bool $prefix = true ][, bool $suffix = true ][, bool $code = false ][, bool $with_separator = true ][, int $decimals = null ][, bool $significant_decimals = false ]) : string
Parameters
- $value : float
-
The decimal value to convert
- $currency : string
-
The ISO 4217 currency code format to apply to $value
- $company_id : int = null
-
The company ID to fetch the currency for
- $prefix : bool = true
-
True to include the prefix symbol for this currency, false otherwise
- $suffix : bool = true
-
True to include the suffix symbol for this currency, false otherwise
- $code : bool = false
-
True to include the currency code for this currency, false otherwise
- $with_separator : bool = true
-
True to include the separator for this currency, false otherwise
- $decimals : int = null
-
The number of decimal places (precision) (optional, default null to use the currency's defined precision)
- $significant_decimals : bool = false
-
True to include only the significant decimals (non-zero), regardless of the given decimals precision (optional, false by default)
Tags
Return values
string —The value formatted for the specified currency
toCurrencyValue()
Converts the given decimal value into a currency value excluding the prefix, suffix, and currency code symbols
public
toCurrencyValue(float $value, string $currency[, bool $with_separator = true ][, int $company_id = null ][, int $decimals = null ]) : string
Parameters
- $value : float
-
The decimal value to convert
- $currency : string
-
The ISO 4217 currency code format to apply to $value
- $with_separator : bool = true
-
True to include the separator for this currency, false otherwise
- $company_id : int = null
-
The company ID to fetch the currency for
- $decimals : int = null
-
The number of decimal places (precision) (optional, default null to use the currency's defined precision)
Tags
Return values
string —The value formatted for the specified currency
toDecimal()
Converts a currency value into a decimal representation based on ISO 31-0
public
toDecimal(string $value, string $currency[, int $company_id = null ][, int $decimals = null ]) : string
Parameters
- $value : string
-
A currency value
- $currency : string
-
The ISO 4217 currency code format representing $value
- $company_id : int = null
-
The company ID to fetch the currency for
- $decimals : int = null
-
The number of decimal places (precision) (optional, default null to use the currency's defined precision)
Tags
Return values
string —The value in decimal format based on ISO 31-0
updateRates()
Updates all currency exchange rates for the current company using the configured processor.
public
updateRates() : mixed
validateCurrencyExists()
Validates a currency exists
public
validateCurrencyExists(string $code, int $company_id) : bool
Parameters
- $code : string
-
The currency code
- $company_id : int
-
The company ID
Return values
bool —True if the currency exists, false otherwise
validateCurrencyFormat()
Validates a currency's 'format' field
public
validateCurrencyFormat(string $format) : bool
Parameters
- $format : string
-
The format to check, (e.g. "#.###")
Return values
bool —True if validated, false otherwise
validateCurrencyInUse()
Checks if a currency code is currently in use
public
validateCurrencyInUse(string $currency_code, int $company_id) : bool
Parameters
- $currency_code : string
-
The ISO 4217 currency code to check
- $company_id : int
-
The company ID whose currency to check
Return values
bool —True if the currency code is in use, false otherwise
validateCurrencyIsDefault()
Checks if the given currency code is set as the default currency
public
validateCurrencyIsDefault(string $currency_code, int $company_id) : bool
Parameters
- $currency_code : string
-
The ISO 4217 currency code to check
- $company_id : int
-
The company ID whose default currency to check
Return values
bool —True if the currency is the default currency for this company, false otherwise
getCurrencies()
Partially constructs the query required by Currencies::getList(), Currencies::getListCount(), and Currencies::getAll()
private
getCurrencies(int $company_id) : Record
Parameters
- $company_id : int
-
The company ID to fetch currencies for
Return values
Record —The partially constructed query Record object
getRules()
Returns the rule set for adding/editing currencies
private
getRules(array<string|int, mixed> $vars) : array<string|int, mixed>
Parameters
- $vars : array<string|int, mixed>
-
The input vars
Return values
array<string|int, mixed> —Currency rules