Commit 198c1221 authored by Mathias Verraes's avatar Mathias Verraes
Browse files

bumped to 2.0.0.alpha

parent 46482f0c
Money
=============
=====
Also see http://blog.verraes.net/2011/04/fowler-money-pattern-in-php/
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
> lack of a type causes problems, the most obvious surrounding currencies. If all your calculations
> are done in a single currency, this isn't a huge problem, but once you involve multiple currencies
> you want to avoid adding your dollars to your yen without taking the currency differences into
> account. The more subtle problem is with rounding. Monetary calculations are often rounded to the
> smallest currency unit. When you do this it's easy to lose pennies (or your local equivalent)
> because of rounding errors.
Examples
========
Creation
--------
All amounts are represented in the smallest unit (eg. cents), so USD 5.00 is written as
<?php
$fiver = new Money(500, new Currency('USD'));
// or shorter:
$fiver = Money::USD(500);
Allocation
----------
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
$profit = Money::EUR(5);
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 = Money::EUR(2500);
Jim has a coupon for EUR 5.
<?php
$coupon = Money::EUR(500);
$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::EUR(2000)); // true
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
===========
* https://github.com/RubyMoney/money
* http://css.dzone.com/books/practical-php-patterns/basic/practical-php-patterns-value
* http://www.codeproject.com/KB/recipes/MoneyTypeForCLR.aspx
* http://www.michaelbrumm.com/money.html
* http://stackoverflow.com/questions/1679292/proof-that-fowlers-money-allocation-algorithm-is-correct
* http://timeandmoney.sourceforge.net/
* https://github.com/lucamarrocco/timeandmoney/blob/master/lib/money.rb
* http://joda-money.sourceforge.net/
* http://en.wikipedia.org/wiki/Currency_pair
* https://github.com/RubyMoney/eu_central_bank
* http://en.wikipedia.org/wiki/ISO_4217
Bibliography
============
[Fowler2002]
Fowler, M., D. Rice, M. Foemmel, E. Hieatt, R. Mee, and R. Stafford, Patterns of Enterprise Application Architecture, Addison-Wesley, 2002.
http://martinfowler.com/books.html#eaa
PHP 5.3+ library to make working with money safer, easier, and fun!
The documentation is in the process of being moved to readthedocs.org. See /docs for now.
2.0.dev
\ No newline at end of file
2.0.0.alpha
\ No newline at end of file
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