Currency extends Post_Type
in package

Application

Currency class.

Encapsulates a currency. A currency:

is associated with one wallet
specifies details relevant to the currency such as decimals
can render amounts

Create a new currency programmatically:

Normally you'd create a currency via the admin screens. But here's how you can do it in PHP:

$bitcoin = new Currency;
$bitcoin->name = 'Bitcoin';
$bitcoin->symbol = 'BTC';
$bitcoin->decimals = 8;
$bitcoin->pattern = 'BTC %01.8f';
$bitcoin->coingecko_id = 'bitcoin';
$bitcoin->min_withdraw = 100000; // all amounts are in satoshis
$bitcoin->max_withdraw = 0; // zero means no daily limit
$bitcoin->max_withdraw_per_role = [ 'administrator' => 0, 'subscriber' => 10000000, ]; // no limit for admins, 1BTC for subscribers
$bitcoin->fee_deposit_site = 0;
$bitcoin->fee_move_site = 100;
$bitcoin->explorer_uri_tx = 'https://blockchair.com/bitcoin/transaction/%s';
$bitcoin->explorer_uri_add = 'https://blockchair.com/bitcoin/address/%s';

try {
	$bitcoin->save();
} catch ( \Exception $e ) {
	error_log( 'Could not save bitcoin currency due to: ' . $e->getMessage() );
}

if ( $bitcoin->post_id ) {
	error_log( "Bitcoin currency was saved with post_id: $bitcoin->post_id" );
}

Get currency

...by post_id

In the general case, there can be multiple currencies using the same ticker symbol. It's safest to refer to currencies by their post_id, if you know it

...by coingecko_id

If you have associated your currency with its correct CoinGecko ID (you should do this to get exchange rates) then you can get a currency by its unique CoinGecko ID.

$bitcoin = \DSWallets\get_first_currency_by_coingecko_id( 'bitcoin' );

...by ticker symbol

If you know that only one currency uses this ticker, you can retrieve the currency by its ticker:

$bitcoin = \DSWallets\get_first_currency_by_symbol( 'BTC' );

Iterate over all the Currency posts:

$currencies = \DSWallets\get_all_currencies();

foreach ( $currencies as $currency ) {
	error_log( $currency );
	// do stuff with each currency
}

Get all fiat currencies

Fiat currencies should have the fiat taxonomy term (tag) assigned to them.

$fiat_currencies = Currency::load_many( get_currency_ids( 'fiat' ) );

Get all cryptocurrencies (i.e. not fiat)

$cryptocurrencies = Currency::load_many(
	array_diff(
		get_currency_ids(), // gets all currency IDs
		get_currency_ids( 'fiat' )
		)
	);

Is a currency fiat or not?

// returns true if currency has `fiat` tag, OR if it is assigned to the Bank_Fiat_Adapter
	$currency->is_fiat();

Displaying amounts to the user

Here we display the minimal withdrawal amount for this currency. We first convert the integer amount to a float, then we use the sprintf() pattern to render it to a string:

// get a hold of the currency
$bitcoin = \DSWallets\get_first_currency_by_symbol( 'BTC' );

// divide the integer amount by ten to the power of how many decimals are allowed, i.e. *10^(-8)
$min_withdraw_amount_btc = $bitcoin->min_withdraw * 10 ** -$bitcoin->decimals;

// use the pattern field to render the float amount
error_log( sprintf( "Min withdraw: $bitcoin->pattern", $min_withdraw_amount_btc" );

$object_cache


    protected
    static    mixed
    $object_cache
     = []

$post_id

The id of the post that this object represents.


    protected
        int
    $post_id

$coingecko_id

CoinGecko unique ID for currency.


    private
        string|null
    $coingecko_id

$contract_address

Contract address or asset_id.


    private
        string|null
    $contract_address
     = null

For EVM tokens, this will always start with 0x.
For Taproot Assets, this will typically be a string without the 0x prefix.
For other coins that are native to their blockchain, this will be null.

$decimals

Number of decimals


    private
        int
    $decimals
     = 0

This is used for saving all amounts as integers to DB and avoid FP/rounding errors.

Side effect: If a pattern is not set, an appropriate pattern for this number of decimals will also be set, when a new amount of decimals is set.

$explorer_uri_add

Block explorer URI pattern for addresses.


    private
        string|null
    $explorer_uri_add
     = null

An sprintf() pattern to generate a block explorer URI from an address string.

$explorer_uri_tx

Block explorer URI pattern for transactions.


    private
        string|null
    $explorer_uri_tx
     = null

An sprintf() pattern to generate a block explorer URI from a transaction id (TXID)

$fee_deposit_site

Deposit fee paid to the site (not the blockchain).


    private
        int
    $fee_deposit_site
     = 0

The amount must be shifted by $this->decimals decimal places to get the actual float amount.

$fee_move_site

Internal transaction fee paid to the site (off-chain transactions)


    private
        int
    $fee_move_site
     = 0

The amount must be shifted by $this->decimals decimal places to get the actual float amount.

$fee_withdraw_site

Withdrawal fee paid to the site (not the blockchain)


    private
        int
    $fee_withdraw_site
     = 0

The amount must be shifted by $this->decimals decimal places to get the actual float amount.

$icon_url

Coin icon url.


    private
        string|null
    $icon_url
     = null

The post thumbnail url. Read only. Admin must set the thumbnail image via the WP editor.

$max_withdraw

Daily maximum withdraw limit. Zero means no limit.


    private
        int
    $max_withdraw
     = 0

$max_withdraw_per_role

Daily maximum withdraw limits per role. Is an assoc array mapping role slugs to amounts. Zero means no limit.


    private
        array<string|int, mixed>
    $max_withdraw_per_role
     = []

$min_withdraw

Minimum withdraw amount.


    private
        int
    $min_withdraw
     = 0

$name

Currency name.


    private
        string
    $name

Free text string, stored on the post_title column in the DB.

$pattern

An sprintf() pattern for rendering amounts


    private
        string
    $pattern
     = '%f'

$rates

Exchange rates.


    private
        array<string, float>
    $rates
     = []

An assoc array of vs_currencies to rates.

The keys are strings containing ticker symbols for the major currencies.

$symbol

Ticker symbol


    private
        string
    $symbol

$tags

Array of tags.


    private
        array<string|int, ?string>
    $tags
     = null

Tags correspond to term slugs in the wallets_currency_tags taxonomy.

$wallet

The wallet adapter associated with this currency


    private
        Wallet|null
    $wallet

__get()

Allows getting one of this object's fields.


    public
                    __get(mixed $name) : mixed

Parameters

$name : mixed: The name of the field to retrieve.

Return values

mixed —

__set()

Sets a field of this Currency object.


    public
                    __set(string $name, mixed $value) : mixed

Parameters

$name : string: Can be: post_id, name, symbol, pattern, coingecko_id, contract_address, explorer_uri_tx, explorer_uri_add, wallet, min_withdraw, max_withdraw, fee_deposit_site, fee_move_site, fee_withdraw_site, decimals.
$value : mixed: The value to set to the field.

Return values

mixed —

__toString()

To String.


    public
                    __toString() : string

Return values

string —

delete()

Trashes this object in the DB.


    public
                    delete([mixed $force = false ]) : mixed

Parameters

$force : mixed = false

Return values

mixed —

from_values()

Factory to construct a currency in one go from database values.


    public
            static        from_values(int $post_id, string $post_title, array<string|int, mixed> $postmeta, array<string|int, string> $tags) : Currency

Parameters

$post_id : int: The ID of the post in the database
$post_title : string: The post's title to be used as currency name
$postmeta : array<string|int, mixed>: Key-value pairs
$tags : array<string|int, string>: The slugs of the terms on taxonomy wallets_currency_tags

Return values

Currency —

The constructed instance of the currency object

get_max_withdraw()

Get max withdraw for user


    public
                    get_max_withdraw([WP_User|null $user = null ]) : int

Returns the maximum allowed amount to withdraw for this user and currency.

The hard daily withdraw limit is max_withdraw. The user can also belong to a number of roles: The role with the highest withdrawal daily limit is always applicable, as long as it is less than the hard daily limit.

Parameters

$user : WP_User|null = null: The user whose limit to return. If not set, function returns the hard daily limit for this currency.

Return values

int —

The applicable daily withdrawal limit.

get_platform()


    public
                    get_platform() : string|null

Return values

string|null —

get_rate()

Get the exchange rate of this currency against the specified "VS currency".


    public
                    get_rate(string $vs_currency) : float|null

You can multiply an amount expressed in this currency by the returned value to convert to the "VS currency".

Parameters

$vs_currency : string: A CoinGecko "VS currency".

Return values

float|null —

The exchange rate, or null if not defined.

get_rate_to()

Get the exchange rate of this currency against the specified other currency.


    public
                    get_rate_to(Currency $currency) : float|null

For the conversion to be successful, there must be a common "VS currency rate" defined for both Currencies.

Example code:


get_rate_to( $doge );
  $rate2 = $doge->get_rate_to( $btc );

  printf( "BTC->get_rate_to(DOGE): %01.8f\nDOGE->get_rate_to(BTC): %01.8f", $rate1, $rate2 );
?>

Will print out:

BTC->get_rate_to(DOGE): 165837.47927032
DOGE->get_rate_to(BTC): 0.0000060374

Parameters

$currency : Currency: The other currency to convert to.

Return values

float|null —

The exchange rate, or null if not defined.

is_fiat()

Determines whether this currency is fiat.


    public
                    is_fiat() : bool

Return values

bool —

is_online()

Determines whether this currency is online.


    public
                    is_online() : bool

Checks if the currency is connected to a wallet and if that wallet is enabled and has a successfully instantiated wallet adapter, and if that adapter is responding to commands.

Return values

bool —

Whether we can connect to wallet backing this currency.

is_set_decimals()

Returns true iff decimals field has been set for this currency.


    public
                    is_set_decimals() : bool

Will return false if the field is not set. Will return true if field has been set to 0 (zero). This is to allow for currencies that have no decimals.

Return values

bool —

Whether the decimals field has been set to an integer or 0.

is_token()

Determines whether this currency is a token on a blockchain that supports multiple assets.


    public
                    is_token() : bool

Fiat currencies and crytocurrency coins are not tokens.

Return values

bool —

load()

Load a Currency object from its custom post entry.


    public
            static        load(int $post_id) : Currency

Parameters

$post_id : int: The post_id for the object to load.

Return values

Currency —

load_many()

Retrieve many currencies by their post_ids.


    public
            static        load_many(array<string|int, int> $post_ids[, string|null $unused = null ]) : array<string|int, Currency>

Any post_ids not found are skipped silently.

Parameters

$post_ids : array<string|int, int>: The post IDs
$unused : string|null = null: Do not use. Ignored.

Return values

array<string|int, Currency> —

The currencies

save()

Saves this object to the DB.


    public
                    save() : void

If the object already had a post_id, then the post is updated. Else, a new custom post is created and the new post_id is assigned to the object.

Return values

void —

set_rate()


    public
                    set_rate(string $vs_currency, float $rate) : bool

Parameters

$vs_currency : string
$rate : float

Return values

bool —

render_bool_field()


    protected
            static        render_bool_field(mixed $schema, mixed $value) : mixed

Parameters

$schema : mixed
$value : mixed

Return values

mixed —

render_boolean_field()


    protected
            static        render_boolean_field(mixed $schema, mixed $value) : mixed

Parameters

$schema : mixed
$value : mixed

Return values

mixed —

render_number_field()


    protected
            static        render_number_field(mixed $schema, mixed $value) : mixed

Parameters

$schema : mixed
$value : mixed

Return values

mixed —

render_secret_field()


    protected
            static        render_secret_field(mixed $schema, mixed $value) : mixed

Parameters

$schema : mixed
$value : mixed

Return values

mixed —

render_select_field()


    protected
            static        render_select_field(mixed $schema, mixed $value) : mixed

Parameters

$schema : mixed
$value : mixed

Return values

mixed —

render_string_field()


    protected
            static        render_string_field(mixed $schema, mixed $value) : mixed

Parameters

$schema : mixed
$value : mixed

Return values

mixed —

render_strings_field()


    protected
            static        render_strings_field(mixed $schema, mixed $value) : mixed

Parameters

$schema : mixed
$value : mixed

Return values

mixed —

Currency extends Post_Type in package Application

Create a new currency programmatically:

Get currency

...by post_id

...by coingecko_id

...by ticker symbol

Iterate over all the Currency posts:

Get all fiat currencies

Get all cryptocurrencies (i.e. not fiat)

Is a currency fiat or not?

Displaying amounts to the user

Tags

Table of Contents

Properties

$object_cache

$post_id

$coingecko_id

$contract_address

$decimals

$explorer_uri_add

Tags

$explorer_uri_tx

Tags

$fee_deposit_site

$fee_move_site

$fee_withdraw_site

$icon_url

$max_withdraw

$max_withdraw_per_role

$min_withdraw

$name

$pattern

Tags

$rates

$symbol

$tags

$wallet

Methods

__get()

Parameters

Return values

__set()

Parameters

Tags

Return values

__toString()

Tags

Return values

delete()

Parameters

Tags

Return values

from_values()

Parameters

Return values

get_max_withdraw()

Parameters

Return values

get_platform()

Return values

get_rate()

Parameters

Tags

Return values

get_rate_to()

Parameters

Return values

is_fiat()

Return values

is_online()

Return values

is_set_decimals()

Return values

is_token()

Return values

load()

Parameters

Tags

Return values

load_many()

Currency extends Post_Type
in package

Application