README

Note: This project is based on cknow/laravel-money and abstracts MoneyPHP

Installation

Run the following command from you terminal:

composer require hasfoug/laravel-money

Usage

use Hasfoug\Money\Money; echo Money::USD(500); // $5.00 echo Money::USD(500, true); // $500.00 force decimals

Configuration

The defaults are set in config/money.php. Copy this file to your own config directory to modify the values. You can publish the config using this command:

php artisan vendor:publish --provider="Hasfoug\Money\MoneyServiceProvider"

This is the contents of the published file:

return [ /*  |--------------------------------------------------------------------------  | Laravel money  |--------------------------------------------------------------------------  */ 'locale' => config('app.locale', 'en_US'), 'defaultCurrency' => config('app.currency', 'USD'), 'defaultFormatter' => null, 'defaultSerializer' => null, 'currencies' => [ 'iso' => ['RUB', 'USD', 'EUR'], // 'all' to choose all ISOCurrencies 'bitcoin' => ['XBT'], // 'all' to choose all BitcoinCurrencies 'custom' => [ 'MY1' => 2, 'MY2' => 3 ] ] ];

Main changes to the cknow/laravel-money version:

Most operations now accept mixed values, parsing them to default currency before operation

Therefore, you are not required need to convert the operands to money instance anymore (unless you operate in non-default currency):

Money::USD(500)->add(100); // $6.00 Money::USD(500)->add(null); // $5.00 Money::USD(500)->subtract(100); // $4.00 Money::USD(500)->subtract(null); // $5.00 // Aggregation Money::min(Money::USD(100), Money::USD(200), 300, null); // Money::USD(0) Money::max(Money::USD(100), Money::USD(200), 400); // Money::USD(400) Money::avg(Money::USD(100), Money::USD(200), 300); // Money::USD(200) Money::sum(Money::USD(100), Money::USD(200), 300, null, 0); // Money::USD(600) // Comparing Money::USD(500)->equals(500); // true Money::USD(500)->greaterThan(100); // true Money::USD(500)->greaterThan(null); // true Money::USD(500)->greaterThanOrEqual(500); // true Money::USD(500)->lessThan(1000); // true Money::USD(500)->lessThan(null); // false Money::USD(500)->lessThanOrEqual(500); // true Money::USD(0)->lessThanOrEqual(null); // true

Added shortcuts for comparing operations

Money::USD(500)->eq(500); // true Money::USD(500)->gt(100); // true Money::USD(500)->gte(500); // true Money::USD(500)->lt(1000); // true Money::USD(500)->lte(500); // true

Added isNotZero accessor

Money::USD(500)->isNotZero(); // true Money::USD(0)->isNotZero(); // false

getAmount() method return type switched to int

Money::USD(500)->getAmount(); // '500' -> Before Money::USD(500)->isNotZero(); // 500 -> Now

Added defaultSerializer to the config to set default json serialization behaviour

Change the value of money.defaultSerializer setting to one of those values:

• \Hasfoug\Money\Tests\Serializers\ArrayMoneySerializer::class
• \Hasfoug\Money\Tests\Serializers\DecimalMoneySerializer::class
• \Hasfoug\Money\Tests\Serializers\IntegerMoneySerializer::class
• \Hasfoug\Money\Tests\Serializers\StringMoneySerializer::class

Or create your own, which should implement \Hasfoug\Money\Contracts\MoneySerializer

Advanced Usage

See MoneyPHP for more information

use Hasfoug\Money\Money; Money::USD(500)->add(Money::USD(500)); // $10.00 Money::USD(500)->add(Money::USD(500), Money::USD(500)); // $15.00 Money::USD(500)->subtract(Money::USD(400)); // $1.00 Money::USD(500)->subtract(Money::USD(200), Money::USD(100)); // $2.00 Money::USD(500)->multiply(2); // $10.00 Money::USD(1000)->divide(2); // $5.00 Money::USD(830)->mod(Money::USD(300)); // $2.30 -> Money::USD(230) Money::USD(-500)->absolute(); // $5.00 Money::USD(500)->negative(); // $-5.00 Money::USD(30)->ratioOf(Money::USD(2)); // 15 Money::USD(500)->isSameCurrency(Money::USD(100)); // true Money::USD(500)->equals(Money::USD(500)); // true Money::USD(500)->greaterThan(Money::USD(100)); // true Money::USD(500)->greaterThanOrEqual(Money::USD(500)); // true Money::USD(500)->lessThan(Money::USD(1000)); // true Money::USD(500)->lessThanOrEqual(Money::USD(500)); // true Money::USD(500)->isZero(); // false Money::USD(500)->isPositive(); // true Money::USD(500)->isNegative(); // false Money::USD(500)->getMoney(); // Instance of \Money\Money Money::isValidCurrency('USD'); // true Money::isValidCurrency('FAIL'); // false Money::getISOCurrencies(); // Load ISO currencies // Aggregation Money::min(Money::USD(100), Money::USD(200), Money::USD(300)); // Money::USD(100) Money::max(Money::USD(100), Money::USD(200), Money::USD(300)); // Money::USD(300) Money::avg(Money::USD(100), Money::USD(200), Money::USD(300)); // Money::USD(200) Money::sum(Money::USD(100), Money::USD(200), Money::USD(300)); // Money::USD(600) // Formatters Money::USD(500)->format(); // $5.00 Money::USD(199)->format(null, null, \NumberFormatter::DECIMAL); // 1,99 Money::XBT(41000000)->formatByBitcoin(); // \xC9\x830.41 Money::USD(500)->formatByCurrencySymbol(); // $5.00 Money::USD(500)->formatByCurrencySymbol(true); // 5.00$ Money::USD(500)->formatByDecimal(); // 5.00 Money::USD(500)->formatByIntl(); // $5.00 Money::USD(199)->formatByIntl(null, null, \NumberFormatter::DECIMAL); // 1,99 Money::USD(500)->formatByIntlLocalizedDecimal(); // $5.00 Money::USD(199)->formatByIntlLocalizedDecimal(null, null, \NumberFormatter::DECIMAL) // 1.99 // Parsers Money::parse('$1.00'); // Money::USD(100) Money::parseByBitcoin("\xC9\x830.41"); // Money::XBT(41000000) Money::parseByDecimal('1.00', 'USD'); // Money::USD(100) Money::parseByIntl('$1.00'); // Money::USD(100) Money::parseByIntlLocalizedDecimal('1.00', 'USD'); // Money::USD(100)

Create your formatter

class MyFormatter implements \Money\MoneyFormatter { public function format(\Money\Money $money) { return 'My Formatter'; } } Money::USD(500)->formatByFormatter(new MyFormatter()); // My Formatter

Rules

Below is a list of all available validation rules and their function:

currency

The field under validation must be a valid currency.

Validator::make([ 'currency1' => 'USD', 'currency2' => 'EUR', 'currency3' => new \Money\Currency('BRL'), ], [ 'currency1' => new \Hasfoug\Money\Rules\Currency(), 'currency2' => new \Hasfoug\Money\Rules\Currency(), 'currency3' => 'currency', ]);

money

The field under validation must be a valid money.

Validator::make([ 'money1' => '$10.00' 'money2' => '€10.00', 'money3' => 'R$10,00', 'money4' => '$10.00' 'money5' => '€10.00', 'money6' => 'R$10,00', ], [ 'money1' => new \Hasfoug\Money\Rules\Money(), 'money2' => new \Hasfoug\Money\Rules\Money('EUR'), // forcing currency 'money3' => new \Hasfoug\Money\Rules\Money('BRL', 'pt_BR'), // forcing currency and locale 'money4' => 'money', 'money5' => 'money:EUR', // forcing currency 'money6' => 'money:BRL,pt_BR', // forcing currency and locale ]);

Casts

At this stage the cast can be defined in the following ways:

use Hasfoug\Money\Casts\MoneyDecimalCast; use Hasfoug\Money\Casts\MoneyIntegerCast; use Hasfoug\Money\Casts\MoneyStringCast; protected $casts = [ // cast money as decimal using the currency defined in the package config 'money' => MoneyDecimalCast::class, // cast money as integer using the defined currency 'money' => MoneyIntegerCast::class . ':AUD', // cast money as string using the currency defined in the model attribute 'currency' 'money' => MoneyStringCast::class . ':currency', // cast money as decimal using the defined currency and forcing decimals 'money' => MoneyDecimalCast::class . ':USD,true', ];

In the example above, if the model attribute currency is null, the currency defined in the package configuration is used instead.

Setting money can be done in several ways:

$model->money = 10; // 0.10 USD or any other currency defined $model->money = 10.23; // 10.23 USD or any other currency defined $model->money = 'A$10'; // 10.00 AUD $model->money = '1,000.23'; // 1000.23 USD or any other currency defined $model->money = '10'; // 0.10 USD or any other currency defined $model->money = Money::EUR(10); // 10 EUR

When we pass the model attribute holding the currency, such attribute is updated as well when setting money:

$model->currency; // null $model->money = '€13'; $model->currency; // 'EUR' $model->money->getAmount(); // '1300'

Helpers

currency() // To use default currency present in `config/money.php` currency('USD'); money(500); // To use default currency present in `config/money.php` money(500, 'USD'); // Aggregation money_min(money(100, 'USD'), money(200, 'USD'), money(300, 'USD')); // Money::USD(100) money_max(money(100, 'USD'), money(200, 'USD'), money(300, 'USD')); // Money::USD(300) money_avg(money(100, 'USD'), money(200, 'USD'), money(300, 'USD')); // Money::USD(200) money_sum(money(100, 'USD'), money(200, 'USD'), money(300, 'USD')); // Money::USD(600) // Parsers money_parse('$5.00'); // Money::USD(500) money_parse_by_bitcoin("\xC9\x830.41"); // Money::XBT(41000000) money_parse_by_decimal('1.00', 'USD'); // Money::USD(100) money_parse_by_intl('$1.00'); // Money::USD(100) money_parse_by_intl_localized_decimal('1.00', 'USD'); // Money::USD(100)

Blade Extensions

@currency() // To use default currency present in `config/money.php` @currency('USD') @money(500) // To use default currency present in `config/money.php` @money(500, 'USD') // Aggregation @money_min(@money(100, 'USD'), @money(200, 'USD'), @money(300, 'USD')) // Money::USD(100) @money_max(@money(100, 'USD'), @money(200, 'USD'), @money(300, 'USD')) // Money::USD(300) @money_avg(@money(100, 'USD'), @money(200, 'USD'), @money(300, 'USD')) // Money::USD(200) @money_sum(@money(100, 'USD'), @money(200, 'USD'), @money(300, 'USD')) // Money::USD(600) // Parsers @money_parse('$5.00') // Money::USD(500) @money_parse_by_bitcoin("\xC9\x830.41") // Money::XBT(41000000) @money_parse_by_decimal('1.00', 'USD') // Money::USD(100) @money_parse_by_intl('$1.00') // Money::USD(100) @money_parse_by_intl_localized_decimal('1.00', 'USD') // Money::USD(100)