Download the PHP package onmoon/money without Composer

OnMoon Money

OnMoon Money is an opinionated wrapper around MoneyPHP Money: https://github.com/moneyphp/money

• Installation
• Features
• Usage
  • Currency classes
  • Money classes
    • Subunits
    • Validation
  • Error handling
  • Using the library with Symfony and Doctrine

Installation

The preferred way to install this extension is through composer.

Features

On top of the wonderful API of the original, more strictness and some additional features are added.

Money classes can be extended and used as Doctrine Embeddables

The MoneyPHP objects are final, so you can't create your own domain value objects adding more semantics to the code:

With OnMoon Money you can do this:

Also MoneyPHP Money class stores Currency internally as an object, that is a problem for mapping value objects in Doctrine using embeddables, as the Money object is itself an embeddable and you get nested embeddables:

OnMoon Money class stores currency internally as a string, and can be mapped as one embeddable using the provided Doctrine Types:

Money is created only from strings in strict formats depending on the currency

MoneyPHP allows creating Money objects from a wide range of inputs and requires the input amount to be in subunits of the currency. There is no check how many subunits the currency actually has. This requires you to perform validation and checks in your code and can be error-prone.

OnMoon Money instead accepts ammounts only as strings containing the monetary amount in a human-readable format and strictly enforces the format depending on the currency used.

The same API, but strictly typed

MoneyPHP Money:

OnMoon Money:

etc.

Custom validation for your code extending the library classes with meaningful messages

Usage

For beginning, you should make yourself familiar with the MoneyPHP Money documentation

Currency classes

OnMoon Money provies a class for representing currency values: OnMoon\Money\Currency.

To create a currency object you will need the currency code:

Money classes

The API of a OnMoon Money class is the same as the MoneyPHP Money class:

• Operations
• Comparison
• Allocation

You can create your own Money classes with your own semantics:

You can create an instance of the specific Money class by using the named constructor:

Subunits

The library provies three base classes that you can use directly or extend from:

OnMoon\Money\Money - can work with currencies with up to 2 subunits

OnMoon\Money\GaapMoney - can work with currencies with up to 4 subunits and conforms with the GAAP standard

OnMoon\Money\BTC - can work with 8 subunits and is restricted to the Bitcoin (XBT) currency

Depending on the base class you use or extend from, some currencies may be unavailable due to requiring more subunits than the base class can work with.

You should choose the base class depending on the currencies that your application will use with the money class.

If you need your own custom subunit amount you can extend any Money class and implement the classSubunits method.

Remember, that you cannot use Money classes of different subunits in the Money class API:

Validation

On top of the validation provided by the base classes, you can enforce additional constraints in your extended classes.

By implementing one of the following methods:

If you need more complex validation logic, implement the following method:

You can also specify the list of currencies that are allowed for a Money class and all classes that extend from it:

The default classes provided by the library support the following currencies:

OnMoon\Money\Money - All ISO currencies with 0-2 subunits

OnMoon\Money\GaapMoney - All ISO currencies with 0-4 subunits

OnMoon\Money\BTC - Only XBT with 8 subunits

All operations on the Money class that change the amount will return the base class instead of the extended, as the resulting amount can violate the invariants of the extended class:

Error handling

Exceptions thrown by OnMoon money classes are extended from two base exceptions:

• OnMoon\Money\Exception\MoneyLogicError - Errors that represent a logic error in your code and should be avoided in production, error messages should not be shown to the user.
• OnMoon\Money\Exception\MoneyRuntimeError - Errors that represent a runtime error in your code and can depend on user input. You can use them safely to display errors to the user.

Examples of OnMoon\Money\Exception\MoneyRuntimeError error messages:

• Invalid Money with amount: 100.00 and currency: RUB. Currency not allowed.
• Invalid Money with amount: 50.000 and currency: EUR. Invalid amount format. The correct format is: /^-?\d+.\d{2}$/.
• Invalid Money with amount: -11.00 and currency: USD. Amount must be greater than zero.

You can make theese messages even more helpful, by implementing the humanReadableName method in your Money Classes:

The error messages then will look like this:

• Invalid Transaction Fee with amount: 100.00 and currency: RUB. Currency not allowed.
• Invalid Transaction Fee with amount: 50.000 and currency: EUR. Invalid amount format. The correct format is: /^-?\d+.\d{2}$/.
• Invalid Transaction Fee with amount: -11.00 and currency: USD. Amount must be greater than zero.

If you want to catch all exceptions thrown by OnMoon Money, including the exceptions of the underlying MoneyPHP Money code - use the Money\Exception interface.

Using the library with Symfony and Doctrine

The library provides four Doctrine types to persist the Money and Currency objects to the database:

• OnMoon\Money\Type\BTCMoneyType - Should be used only for classes extending OnMoon\Money\BTC
• OnMoon\Money\Type\GaapMoneyType - Should be used only for classes extending OnMoon\Money\GaapMoney
• OnMoon\Money\Type\MoneyType - Should be used only for classes extending OnMoon\Money\Money
• OnMoon\Money\Type\CurrencyType - Should be used only for classes extending OnMoon\Money\Curency

The rule of thumb for Type classes mapping the Money object is that the Type class decimal precision should be equal to the Money class subunits. If they will be different, you will get other amounts from the database than previously saved.

Example code

Entity:

Value object:

/config/packages/doctrine.xml:

Entity mapping:

Value object mapping: