Download the PHP package code-distortion/currency without Composer
On this page you can find all versions of the php package code-distortion/currency. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download code-distortion/currency
More information about code-distortion/currency
Files in code-distortion/currency
Package currency
Short Description Arbitrary precision currency maths with locale-aware formatting - integrated with Laravel or stand-alone
License MIT
Homepage https://github.com/code-distortion/currency
Informations about the package currency
Currency
code-distortion/currency is a PHP library for accurate currency maths with locale-aware formatting. It integrates with Laravel 5 - 9 but works stand-alone as well.
Currency | en-US | de-DE | sv-SE | hi-IN | ar-EG |
---|---|---|---|---|---|
USD | $1,234,567.89 | 1.234.567,89 $ | 1 234 567,89 US$ | $12,34,567.89 | ١٬٢٣٤٬٥٦٧٫٨٩ US$ |
EUR | €1,234,567.89 | 1.234.567,89 € | 1 234 567,89 € | €12,34,567.89 | ١٬٢٣٤٬٥٦٧٫٨٩ € |
SEK | SEK 1,234,567.89 | 1.234.567,89 SEK | 1 234 567,89 kr | SEK 12,34,567.89 | ١٬٢٣٤٬٥٦٧٫٨٩ SEK |
JPY | ¥1,234,568 | 1.234.568 ¥ | 1 234 568 JPY | JP¥12,34,568 | ١٬٢٣٤٬٥٦٨ JP¥ |
INR | ₹1,234,567.89 | 1.234.567,89 ₹ | 1 234 567,89 INR | ₹12,34,567.89 | ١٬٢٣٤٬٥٦٧٫٨٩ ₹ |
EGP | EGP 1,234,567.89 | 1.234.567,89 EGP | 1 234 567,89 EG£ | EGP 12,34,567.89 | ١٬٢٣٤٬٥٦٧٫٨٩ ج.م. |
Here is an example of why you might want arbitrary precision calculations:
If you would like to work with regular floating-point or percentage values, please consider the code-distortion/realnum package.
Installation
Install the package via composer:
Usage
Instantiate a Currency object and you can start performing calculations with it, perform comparisons, and render it as a readable string:
Default currency-code
The default currency-code isn't set to begin with but you can choose one. If you use Laravel this may be set in the /config/code-distortion.currency.php config file. See the Laravel section below for more details. Otherwise you may:
Note: All examples below use a default currency-code of USD.
Setting values
You may set the value explicitly:
The types of values you can pass to Currency are:
TIP: To maintain precision when passing values, pass them as strings instead of floating-point numbers:
You may also set other settings that Currency uses:
Retrieving values
To retrieve the value contained in a Currency object you may read the val
and cast
properties. The val
property maintains precision and in contrast, cast
will loose some precision so use them depending on your needs:
These properties associated to the currency may be read:
You may also read other settings that Currency uses:
And you can also obtain each currency's symbol:
Note: See the formatting output section below for more details about how to render the value as a readable string.
Calculations
The calculations available are:
The add()
, sub()
, div()
and mul()
methods accept multiple values:
Integer, float, numeric string and null values, as well as other Currency objects may be passed:
Comparisons
You can compare amounts to others with bound checking:
You may pass multiple values to these comparison methods. eg.
You can check if a Currency's value is between given bounds:
And you can check if the value is null:
Formatting output
Use the format()
method to generate a readable-string version of the current value:
You may alter the way format()
renders the output by passing options. The options you can alter are:
null=x
, decPl=x
, trailZeros
, symbol
, thousands
, showPlus
, accountingNeg
, locale=x
and breaking
.
Boolean options (those without an equals sign) can be negated by adding !
before it.
Note: format()
options are processed using the code-distortion/options package so they may be passed as expressive strings or associative arrays.
Multiple settings can be used together:
Casting a Currency to a string is equivalent to calling format()
with no arguments:
NOTE: Currency uses PHP's NumberFormatter to render the readable output, which currently has a limitation of being able to only show about 17 digits (including before the decimal place). So format()
's output will act a bit strangely if there are too many digits. The number stored inside will maintain its full accuracy, however. You may access the full number by reading the val
property (see the retrieving values section above).
Default format settings
Currency uses these default settings when format()
is called: "null=null decPl=null trailZeros symbol thousands !showPlus !accountingNeg locale=en !breaking"
Note: When using Laravel you may set this in the package config file. See the Laravel section below.
Note: format()
options are processed using the code-distortion/options package so they may be passed as expressive strings or associative arrays.
These can be adjusted per-object:
The default format-settings can be adjusted. All new Currency objects will then start with this setting:
Locale
Note: When using Laravel this will be set automatically. See the Laravel section below.
Currency's default locale is "en" (English) but you can choose which one to use.
You may change the locale per-object:
The default locale may be changed. All new Currency objects will then start with this setting:
Precision (custom decimal places)
The number of decimal places the current currency has is used by default (eg. 2 decimal places for USD). But you may specify the number to use for greater precision. This may be useful if you wish to perform some calculations and then round to the nearest cent at the end.
You may change this per-object using customDecPl()
:
You can revert back to the normal number of decimal places using currencyDecPl()
:
To find out how many decimal places a currency has:
Immutability
Note: When using Laravel you may set this in the package config file. See the Laravel section below.
Currency is immutable by default which means that once an object is created it won't change. Anything that changes its contents will return a new Currency instead. This way you can pass a Currency object to other parts of your code and be sure that it won't be changed unexpectedly:
Immutability may be turned off per-object:
Immutability may be turned off by default. All new Currency objects will then start with this setting:
You can explicitly make a clone of a Currency object:
Non-breaking whitespace
Some locales use spaces when rendering numbers (eg. Swedish uses spaces for the thousands separator). format()
can return strings containing either non-breaking whitespace characters, or regular space characters.
An example of non-breaking whitespace is UTF-8's \xc2\xa0
character which is used instead of a regular \x20
space character. There are others like \xe2\x80\xaf
which is a 'narrow no-break space'.
The \xc2\xa0
UTF-8 character will become the familiar
when turned into an html-entity.
Because format()
is designed to produce readable numbers for humans, Currency uses non-breaking whitespace by default, but you can instruct it to return regular spaces:
Tip: The non-breaking whitespace setting can be changed per-object and by default. See the default format settings sections above.
Chaining
The setting and calculation methods above may be chained together. eg.
Laravel
The Currency package is framework agnostic and works well on its own, but it also integrates with Laravel 5, 6, 7, 8 & 9.
Service-provider
Currency integrates with Laravel 5.5+ automatically thanks to Laravel's package auto-detection.
Laravel's locale is registered with Currency, and is updated later if it changes.
(Click here for Laravel <= 5.4)
For Laravel 5.0 - 5.4, add the following line to config/app.php:
Config
You may specify default immutability and format-settings by publishing the config/code-distortion.currency.php config file and updating it:
Testing
Changelog
Please see CHANGELOG for more information on what has changed recently.
SemVer
This library uses SemVer 2.0.0 versioning. This means that changes to X
indicate a breaking change: 0.0.X
, 0.X.y
, X.y.z
. When this library changes to version 1.0.0, 2.0.0 and so forth, it doesn't indicate that it's necessarily a notable release, it simply indicates that the changes were breaking.
Treeware
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
Contributing
Please see CONTRIBUTING for details.
Code of Conduct
Please see CODE_OF_CONDUCT for details.
Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.
All versions of currency with dependencies
ext-intl Version *
code-distortion/options Version ^0.5.8
code-distortion/realnum Version ^0.7.6