Download the PHP package mistralys/currency-parser without Composer

Currency parser

PHP library that can detect prices written in text or markup, adding non-breaking spaces, and normalising their formatting according to country-specific rules.

Requirements

• PHP 7.4+
• Composer

Installation

Use Composer to add the library to your project:

Alternatively, clone it locally using the GIT command line (or GitHub Desktop), or manually download a release.

Examples of recognized formats

Primarily intended to parse prices written by humans, the parser is quite tolerant and will recognize any of these notations (and more) - either as standalone text or scattered in a larger document.

• $1000
• $1,000.00 With thousands separators
• $ 1 , 000 . 00 Free-spacing, including newlines
• $1.000,00 Separator style agnostic
• $1.000.00 Same separator mistake*
• $1000.2 1 to 2 decimal places
• 1000 EUR Currency symbols or names
• EUR 1000 Symbol placement agnostic
• -$ 1000 Minus before symbol
• $ -1000 Minus after symbol
• 50,- € German short style decimals
• 1 000,00 € TTC French style with VAT
• .50 € Decimals only

• Based on the assumption that prices always have 1-2 decimal places, this part of the number is assumed to be the decimals.

Euro exception

The Euro is the only one of the supported currencies whose name begins with the same letters as its currency name, EUR. The parser will ignore prices written like this:

The reasoning being that using this name is ambiguous in a pure currency context. It is typically used when mentioning prices in body text, where price formatting is not necessary or even expected.

Quick Start

Get a list of prices in a text or markup

Format a single price string

Using auto-detection for all supported currencies:

Output:

With a specific currency locale for precise formatting when the currency is used in several countries, like the Euro:

Output:

Format all prices in a text or markup

The following will automatically format prices according to the selected currencies' default locale.

Output:

To be more precise, the currency locale can be provided. For example, Euros are formatted slightly differently in France than in the rest of Europe.

Output:

Add non-breaking spaces to prices

When formatting prices, spaces automatically get replaced by non-breaking space characters for use in text documents. This can be easily switched to an HTML context:

Output:

Change the currency symbol

By default, the currency filter makes no changes to the currency symbols used in the document. This means that a mixed symbol usage will remain the same even after formatting the numbers.

Change to currency symbols

Output:

Change to currency names

Output:

Change to country preferred style

For the Euro, the preferred style is to use the currency symbol for prices instead of the name.

Output:

Formatter usage

What is the formatter?

The formatter is used to format individual prices found in a text by the parser. It knows how to format prices according to the bundled currency locales, like American or Mexican Dollars, or French Euros. It can also be customised to format prices any way you like.

NOTE: To format multiple prices at once, look at the Price Filter.

Locale-based formatting

Fire-and-forget formatting that uses the currency locale definitions.

A locale formatter does not allow changing formatting details like the decimal separator. Only the symbol mode and space character can be adjusted:

Custom formatting

Using a custom formatter, all formatting details can can be freely adjusted.

Output:

NOTE: A formatter instance can be re-used as necessary.

Custom formatter based on a locale

Let's say that we wish to use the default USD formatting, but instead of placing the symbol at the beginning (default behavior), we want to display it at the end.

We have to use a custom formatter for this, but we can use an existing locale formatter to fill out the default settings. All that's left to do then is overwrite the relevant settings.

Filter usage

What is the price filter?

The Filter is used to format multiple prices in text or markup documents, with a minimum of code, and leaving the rest of the document intact.

Filtering a text document

The fire and forget version of filtering a document is to specify what kind of currencies to expect, and let the filter handle all the details based on how the currency is typically formatted.

Filtering an HTML document

This works exactly like a text document, except that the non-breaking space character is adjusted to use the HTML style (which uses an HTML entity instead of the actual character).

Using custom formatters

To use a custom formatter for a currency instead of the locale-based one, the formatter instance must be set separately.

Custom formatters and locale formatters can be freely combined. In the example above, we used PriceFilter::create(), because all formatters were custom. Here, we use a default locale formatter for french prices, and a custom one for U.S. dollars:

Parser usage

What is the parser?

The parser is able to find prices written in arbitrary texts, including within markup (HTML or XML). It can be used as a standalone utility to access price information, to do with as you please.

Detecting specific currencies

To be able to detect prices, the parser needs to know what kind of currencies to expect in the document. In the following example, we only use Euro prices.

Detecting all currencies

For performance reasons, it is best to limit the list currencies to search for in a document. If this cannot be determined reliably, you may use all of them:

Also see the next section on how to handle currencies that share the same currency symbol.

Multiple possible currencies per symbol

It is possible to add multiple currencies to the parser. However, it will not be able to tell them apart if they share the same symbol. Consider the following text:

The parser will not be able to tell which of those two prices are the CAD and USD ones. By default, the parser will use USD in case of conflict with the $ symbol. Using currency names does not have this issue:

Setting default currencies per symbol

The parser has built-in defaults for currency symbol conflicts, like USD for $. However, this can be adjusted if the target currency used in the document is known. Consider the following example:

If the document uses multiple currencies with the same symbol, this will not make it possible to distinguish between them. Only using currency names can solve such cases.

Mailcode compatibility

The Mailcode command preprocessor uses numbers as placeholders for commands when safeguarding them to apply formatting filters (more on the reasoning behind this). This can cause placeholders of variable commands to be falsely recognized as prices.

Example text with a variable command:

The showvar command is converted to a numeric placeholder by the safeguard feature:

To avoid this being formatted into a price (and thus breaking the Mailcode command), simply enable the Mailcode support in the currency parser via the expectMailcode() method:

NOTE: This will only work with the default Mailcode placeholder delimiters. Using a custom delimiter is not supported.

Handling multi-currency documents

In documents with multiple currencies, if they use the same symbol (USD and CAD for example), one must be set as default.

Philosophy

There is an excellent money library for PHP, Money. This library does not attempt to reproduce the same functionality - it was developed for an application in particular, which requires the formatting to be fully whitespace-aware. The methodology in general is focused on the filtering aspect, whereas Money is a full-fledged financial calculation tool.

The two libraries can be used together: Prices have a method to get their value in money integer style.

NOTE: The built-int locale-based formatting may vary slightly from a library like Money. This is due to the formatting rules defined in the application for which the library was developed.

Contributing

Contributions are always welcome. The library does not currently aim to include all worldwide currencies, but we are open tp any you may be able to add via pull requests. Look in the Currencies folder to get an overview of what's there.