Download the PHP package archtechx/money without Composer

Money

A simple package for working with money.

Main features:

• Simple API
• Livewire integration
• Custom currency support
• Highly customizable formatting
• Rounding logic for compliant accounting

This package is our implementation of the Money pattern.

You can read more about why we built it and how it works on our forum: New package: archtechx/money.

Installation

Require the package via composer:

Usage

The package has two main classes:

• Money which represents monetary values
• Currency which is extended by the currencies that you're using

This document uses the terms Terminology section for definitions.

Money

Important: As an implementation of the Money pattern, the Money object creates a new instance after each operation. Meaning, all Money instances are immutable. To modify the value of a variable, re-initialize it with a new value:

Creating Money instances

Arithmetics

Converting money to a different currency

Comparing money instances

Equality of monetary value

Equality of monetary value AND currency

Adding fees

You can use the addFee() or addTax() methods to add a % fee to the money:

Accessing the decimal value

Formatting money

You can format money using the ->formatted() method. It takes display decimals into consideration.

The method optionally accepts overrides for the currency specification:

The overrides can also be passed as an array:

There's also ->rawFormatted() if you wish to use display decimals.

Converting the formatted value back to the Money instance is also possible. The package tries to extract the currency from the provided string:

If you had passed overrides while formatting the money instance, the same can passed to this method.

Notes: 1) If currency is not specified and none of the currencies match the prefix and suffix, an exception will be thrown. 2) If currency is not specified and multiple currencies use the same prefix and suffix, an exception will be thrown. 3) fromFormatted() misses the cents if the display decimals.

Rounding money

Some currencies, such as the Czech Crown (CZK), generally display final prices in full crowns, but use cents for the intermediate math operations. For example:

If the customer purchases a single 3.30 item, he pays 3 CZK, but if he purchases three 3.30 items, he pays 10 CZK.

This rounding (to full crowns) is standard and legal per the accounting legislation, since it makes payments easier. However, the law requires you to keep track of the rounding difference for tax purposes.

Getting the used rounding

For that use case, our package lets you get the rounding difference using a simple method call:

Applying rounding to money

Currencies

To work with the registered currencies, use the bound CurrencyManager instance, accessible using the currencies() helper.

Creating a currency

This package provides only USD currency by default.

You can create a currency using one of the multiple supported syntaxes.

See the Currency logic section for a list of available properties to configure. Note that when registering a currency, two values must be specified:

1. The code of the currency (e.g. USD)
2. The name of the currency (e.g. United States Dollar)

Adding a currency

Register a new currency:

Removing a specific currency

To remove a specific currency, you can use the remove() method:

Removing all currencies

To remove all currencies, you can use the clear() method:

Resetting currencies

Can be useful in tests. This reverts all your changes and makes the CurrencyManager use USD as the default currency.

Currency logic

Currencies can have the following properties:

For each one, there's also a public method. Specifying a method can be useful when your currency config is dynamic, e.g. when the currency rate is taken from some API:

Setting the default currency

You can set the default currency using the setDefault() method:

Setting the current currency

You can set the current currency using the setCurrent() method:

Persisting a selected currency across requests

If your users can select the currency they want to see the app in, the package can automatically write the current currency to a persistent store of your choice, and read from that store on subsequent requests.

For example, say we want to use the currency session key to keep track of the user's selected session. To implement that, we only need to do this:

You can add this code to your AppServiceProvider's boot() method.

Now, whenever the current currency is changed using currencies()->setCurrent(), perhaps in a route like this:

it will also be written to the currency session key. The route can be used by a <form> in your navbar, or any other UI element.

Terminology

This section explains the terminology used in the package.

Values

Multiple different things can be meant by the "value" of a Money object. For that reason, we use separate terms.

Base value

The base value is the value passed to the money() helper:

and returned from the ->value() method:

This is the actual integer value of the money. In most currencies this will be the cents.

The package uses the base value for all money calculations.

Decimal value

The decimal value isn't used for calculations, but it is the human-readable one. It's typically used in the formatted value.

Value in default currency

This is the value of a Money object converted to the default currency.

For example, you may want to let administrators enter the price of a product in any currency, but still store it in the default currency.

It's generally recommended to use the default currency in the "code land". And only use other currencies for displaying prices to the user (e.g. customer) or letting the administrators enter prices of things in a currency that works for them.

Of course, there are exceptions, and sometimes you may want to store both the currency and the value of an item. For that, the package has JSON encoding features if you wish to store the entire Money object in a single database column.

Storing the integer price and the string currency as separate columns is, of course, perfectly fine as well.

Formatted value

The formatted value is the Money value displayed per its currency spec. It may use the prefix, suffix, decimal separator, thousands separator, and the display decimals.

For example:

Note that the math decimals.

For the Czech Crown (CZK), the display decimals will be 0, but the math decimals will be 2. Meaning, cents are used for money calculations, and the decimal() method will return the base value divided by 100, but the display decimals don't include any cents.

Raw formatted value

For the inverse of what was just explained above, you can use the rawFormatted() method. This returns the formatted value, but uses the math decimals for the display decimals. Meaning, the value in the example above will be displayed including cents:

This is mostly useful for currencies like the Czech Crown which generally don't use cents, but can use them in specific cases.

Currencies

Current currency

The current currency refers to the currently used currency.

By default, the package doesn't use it anywhere. All calls such as money() will use the provided currency, or the default currency.

The current currency is something you can convert money to in the final step of calculations, right before displaying it to the user in the browser.

Default currency

The default currency is the currency that Money defaults to in the context of your codebase.

The money() helper, Money::fromDecimal() method, and new Money() all use this currency (unless a specific one is provided).

It can be a good idea to use the default currency for data storage. See more about this in the Value in default currency section.

Math decimals

The math decimals refer to the amount of decimal points the currency has in a math context.

All math operations are still done in floats, using the base value, but the math decimals are used for knowing how to round the money after each operation, how to instantiate it with the Money::fromDecimal() method, and more.

Display decimals

The display decimals refer to the amount of decimals used in the formatted value.

Extra features

Livewire support

The package supports Livewire out of the box. You can typehint any Livewire property as Money and the monetary value & currency will be stored in the component's state.

Livewire's custom type support isn't advanced yet, so this is a bit harder to use in the Blade view — a wrapper Alpine component is recommended. In a future release, wire:model will be supported for currency and value directly.

The component can look roughly like this:

JSON serialization

Both currencies and Money instances can be converted to JSON, and instantiated from JSON.

Tips

💡 Accepted currency code formats

Most methods which accept a currency accept it in any of these formats:

💡 Dynamically add currencies

Class currencies are elegant, but not necessary. If your currency specs come from the database, or some API, you can register them as arrays.

Where the DB call returns an array of array currencies following the format mentioned above.

Development & contributing

Run all checks locally:

Code style will be automatically fixed by php-cs-fixer.

No database is needed to run the tests.