README

Requirements

This plugin requires Craft CMS 3.5.0 or later.

Installation

To install the plugin, follow these instructions.

1. Open your terminal and go to your Craft project:

$ cd /path/to/project

1. Then tell Composer to load the plugin:

$ composer require newism/craft3-money

1. In the Control Panel, go to Settings → Plugins and click the “Install” button for Money or run

$ ./craft plugin/install money

Money Overview

Money is a custom field type and formatter that uses the moneyphp/money library. Values are stored as json in the database and normalized as a Money Value Object.

Currencies are loaded from the moneyphp/money library. A full list can be found here: https://github.com/moneyphp/money/blob/master/resources/currency.php

This plugin also loads in symfony/intl for currency names.

Configuring Money

Money has two levels of configuration:

• Site settings using a config file or plugin settings
• Field settings

Note: Field settings are appended to Site settings.

The two settings are:

• Preferred currencies: These currencies are displayed first in the currency drop down.
• Excluded currencies: These currencies are excluded from the currency drop down.

Both settings accept a comma delimited list of alphabetical currency codes.

It's recommended that you exclude the following currencies: XBA, XBB, XBC, XBD, XTS, XXX, XAU, XPD, XPT, XAG

To use a config file see ./src/config.php.

Using Money

This plugin includes a service for rendering the field value.

Note: In the three methods below value must be an instance of Money. The examples use the 'Elvis Operator'.

International formatter

{{ value ? craft.money.intlFormatter.format(value) }}

# or explicitly define the locale
{{ value ? craft.money.getIntlFormatter(locale).format(value) }}

The intlFormatter returns a [IntlMoneyFormatter](http://moneyphp.org/en/stable/features/formatting.html#intl-money-formatter) object. This formatter requires the intl extension.

Calling .format() will return a string with the currency symbol in a format that matches locale. Separators will also match the locale.

locale is an optional parameter and falls back to the locale defined by Craft: \Craft::$app->locale->id

See: http://moneyphp.org/en/stable/features/formatting.html#intl-money-formatter

International Decimal Formatter

{{ value ? craft.money.intlDecimalFormatter.format(value) }}

# or explicitly define the locale
{{ value ? craft.money.getIntlDecimalFormatter(locale).format(value) }}

Outputs the same as above without the currency symbol.

See: http://moneyphp.org/en/stable/features/formatting.html#intl-decimal-formatter

Decimal Formatter

{{ value ? craft.money.decimalFormatter.format(value) }}

This formatter outputs a simple decimal string which is always in a consistent format independent of locale.

Money Roadmap

Some things to do, and ideas for potential features:

• Test multiple versions of PHP
• Review the usage of symfony/intl for currency names
• Write tests
• Check GraphQL output
• Add localised strings for plugin ui
• Release it

Credits

Brought to you by Newism