rebilly / money
Implementation of the Money Value Object
Installs: 343 937
Dependents: 0
Suggesters: 0
Security: 0
Stars: 6
Watchers: 20
Forks: 0
Open Issues: 0
Requires
- php: ^7.4 || ^8.0
- ext-json: *
- ext-mbstring: *
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.4
- phpunit/phpunit: ^9.5
- psalm/plugin-phpunit: ^0.16.1
- vimeo/psalm: ^4.20
README
Money
Value Object that represents a monetary value using a currency's smallest unit. This library is originally based on Sebastian Bergmann's discontinued library. It's been updated with support added for currency exchange.
Installation
Simply add a dependency on rebilly/money
to your project's composer.json
file if you use Composer to manage the dependencies of your project.
Usage Examples
Creating a Money object and accessing its monetary value
use Money\Currency; use Money\Money; // Create Money object that represents 1 EUR $m = new Money(100, new Currency('EUR')); // Access the Money object's monetary value print $m->getAmount(); // Access the Money object's monetary value converted to its base units print $m->getConvertedAmount();
The code above produces the output shown below:
100
1.00
Creating a Money object from a string value
use Money\Currency; use Money\Money; // Create Money object that represents 12.34 EUR $m = Money::fromString('12.34', new Currency('EUR')) // Access the Money object's monetary value print $m->getAmount();
The code above produces the output shown below:
1234
Basic arithmetic using Money objects
use Money\Currency; use Money\Money; // Create two Money objects that represent 1 EUR and 2 EUR, respectively $a = new Money(100, new Currency('EUR')); $b = new Money(200, new Currency('EUR')); // Negate a Money object $c = $a->negate(); print $c->getAmount(); // Calculate the sum of two Money objects $c = $a->add($b); print $c->getAmount(); // Calculate the difference of two Money objects $c = $b->subtract($a); print $c->getAmount(); // Multiply a Money object with a factor $c = $a->multiply(2); print $c->getAmount();
The code above produces the output shown below:
-100
300
100
200
The compareTo()
method returns an integer less than, equal to, or greater than
zero if the value of one Money
object is considered to be respectively less
than, equal to, or greater than that of another Money
object.
You can use the compareTo()
method to sort an array of Money
objects using
PHP's built-in sorting functions:
use Money\Currency; use Money\Money; $m = array( new Money(300, new Currency('EUR')), new Money(100, new Currency('EUR')), new Money(200, new Currency('EUR')) ); usort( $m, function ($a, $b) { return $a->compareTo($b); } ); foreach ($m as $_m) { print $_m->getAmount() . "\n"; }
The code above produces the output shown below:
100
200
300
Allocate the monetary value represented by a Money object among N targets
use Money\Currency; use Money\Money; // Create a Money object that represents 0,99 EUR $a = new Money(99, new Currency('EUR')); foreach ($a->allocateToTargets(10) as $t) { print $t->getAmount() . "\n"; }
The code above produces the output shown below:
10
10
10
10
10
10
10
10
10
9
Allocate the monetary value represented by a Money object using a list of ratios
use Money\Currency; use Money\Money; // Create a Money object that represents 0,05 EUR $a = new Money(5, new Currency('EUR')); foreach ($a->allocateByRatios(array(3, 7)) as $t) { print $t->getAmount() . "\n"; }
The code above produces the output shown below:
2
3
Extract a percentage (and a subtotal) from the monetary value represented by a Money object
use Money\Currency; use Money\Money; // Create a Money object that represents 100,00 EUR $original = new Money(10000, new Currency('EUR')); // Extract 21% (and the corresponding subtotal) $extract = $original->extractPercentage(21); printf( "%d = %d + %d\n", $original->getAmount(), $extract['subtotal']->getAmount(), $extract['percentage']->getAmount() );
The code above produces the output shown below:
10000 = 8265 + 1735
Please note that this extracts the percentage out of a monetary value where the
percentage is already included. If you want to get the percentage of the
monetary value you should use multiplication (multiply(0.21)
, for instance,
to calculate 21% of a monetary value represented by a Money object) instead.
Convert Money object currency to to another Money object given a conversion rate
use Money\Currency; use Money\Money; // Create a Money object that represents 100,00 EUR $original = new Money(10000, new Currency('EUR')); $converted = $original->convert(new Currency('USD'), 1.09, PHP_ROUND_HALF_UP); $converted->getConvertedAmount(); // 109.00
Convert Money using a Rate Object
$cp = new CurrencyPair(new Currency('USD'), new Currency('EUR')); $rate = new Rate($cp, new DateTime(), 0.92); $money = new Money(1000, new Currency('USD')); $markupBips = 500; // 5% markup $newMoney = $rate->convert($money)->multiply($markupBips / 10000 + 1);
Get Currency Exchange Rate Using a Rate Provider
$cp = new CurrencyPair(new Currency('USD'), new Currency('EUR')); $rateProvider = new InMemoryRateProvider(['EUR/USD' => 1.09, 'USD/EUR' => 0.9172], new DateTime()); $rate = $c->getRate($rateProvider);
Tests
phpunit
Security
If you discover a security vulnerability, please report it to security at rebilly dot com.
License
The Money library is open-sourced under the MIT License distributed with the software.