Commit c5d1d3a7 authored by Mathias Verraes's avatar Mathias Verraes
Browse files

added better examples

parent 29fe1ad1
Verraes\Money
=============
This is a PHP implementation of the Money pattern, as described in [Fowler2002].
The problem
-----------
From [Fowler2002]:
This is a PHP implementation of the Money pattern, as described in [Fowler2002]:
> A large proportion of the computers in this world manipulate money, so it's always puzzled me
> that money isn't actually a first class data type in any mainstream programming language. The
......@@ -17,33 +12,69 @@ From [Fowler2002]:
> smallest currency unit. When you do this it's easy to lose pennies (or your local equivalent)
> because of rounding errors.
The goal
--------
Examples
========
Implement a reusable Money class in PHP, using all the best practices and taking care of all the
subtle intricacies of handling money.
Allocation
----------
Usage
=====
My company made a whopping profit of 5 cents, which has to be divided amongst myself (70%) and my
investor (30%). Cents can't be divided, so I can't give 3.5 and 1.5 cents. If I round up,
I get 4 cents, the investor gets 2, which means I need to conjure up an additional cent. Rounding
down to 3 and 1 cent leaves me 1 cent. Apart from re-investing that cent in the company, the best solution
is to keep handing out the remainder until all money is spent. In other words:
<?php
use Verraes\Money\Money,
Verraes\Money\Usd,
Verraes\Money\Euro;
$profit = new Money(5, new Euro);
list($my_cut, $investors_cut) = $profit->allocate(70, 30);
// $my_cut is 4 cents, $investors_cut is 1 cent
// The order is important:
list($investors_cut, $my_cut) = $profit->allocate(30, 70);
// $my_cut is 3 cents, $investors_cut is 2 cents
Immutability
------------
Jim and Hannah both want to buy a copy of book priced at EUR 25.
<?php
$jim_price = $hannah_price = new Money(2500, new Euro);
Jim has a coupon for EUR 5.
// One EURO, expressed in cents
$eur1 = new Money(100, new Euro);
// Shortcut
$eur2 = Money::euro(200);
<?php
$coupon = new Money(500, new Euro);
$jim_price->subtract($coupon);
Because $jim_price and $hannah_price are the same object, you'd expect Hannah to now have the reduced
price as well. To prevent this problem, Money objects are immutable. With the code above, both
$jim_price and $hannah_price are still EUR 25:
<?php
$jim_price->equals($hannah_price); // true
The correct way of doing operations is:
$jim_price = $jim_price->subtract($coupon);
$jim_price->lessThan($hannah_price); // true
$jim_price->equals(Money::euro(2000)); // true
Money::euro(300)->equals(
$eur1->add($eur2)
);
<?php
$m = new Money(100, new Euro);
list($part1, $part2, $part3) = $m->allocate(array(1, 1, 1));
// $part1 is now 34 cent, the others are 33 cent
The goal
========
Implement a reusable Money class in PHP, using all the best practices and taking care of all the
subtle intricacies of handling money. I hope to add a lot more features, such as dealing with major
units and subunits in currencies, currency conversion, string formatting and parsing, ...
Other ideas include integration with Doctrine2, which should make it easier to store money
in a database transparently.
Status
------
At the moment, all the features that Fowler describes are implemented, which should make
it usable for production code. Everything is unit tested (code coverage is close to 100%).
Inspiration
===========
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment