pelmered/filament-money-field

1.4.3 2024-12-05 01:37 UTC

Requires

• php: ^8.2
• ext-intl: *
• filament/support: ^v3.2.39
• illuminate/support: ^11.0
• moneyphp/money: ^4.0

Requires (Dev)

• filament/filament: ^3.2
• laravel/pint: ^1.16
• nunomaduro/collision: ^8.0
• orchestra/testbench: ^9.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-drift: ^3.0
• pestphp/pest-plugin-type-coverage: ^3.0
• phpstan/phpstan: ^1.12.2

MIT

• Peter Elmered

README

Money field powered by Money PHP.

This package gives much better localization support for money fields in Filament than most other packages, and especially the built-in money support on TextColumns and TextEntries. For example when it comes to currency symbols and decimal and thousands separators. Especially for more obscure currencies. This also includes an input field that handles localized formats.

Example of a money field with Swedish localization. This package would give "1 234,56 kr", while most other solutions probably would give you something like "SEK 1234.56" which is not the correct format for Sweden.

Requirements

• PHP 8.2 or higher
• Filament 3.0 or higher
• PHP Internationalization extension (intl)
• The database column should be a integers with minor units (i.e. cents) and not a float (Floats should never be used for storing money).

Key features

• Fully localized money fields in most locales. Report in an issue if you find a locale that is not working as expected.
• Includes fully localized:
  • Input field with currency symbols and (optional) input mask.
  • Column for tables.
  • Entry for infolists.
• Comprehensive test suite.
• Configure currency and locale globally or per field.
• Validation rules for valid numeric input, and min/max values.
• A money formatter class that could be used in your project. Any public method there is considered stable and will not change without major version update.

Are you using this package to make profits? Please consider sponsoring me.

Installation

composer require pelmered/filament-money-field

Configure your locale

Set the default currency and locale

Set the default options for currency and locale so that you don't have to set them for every field.

Option 1 (Recommended): Put the default options in your .env file.

MONEY_DEFAULT_LOCALE=sv_SE
MONEY_DEFAULT_CURRENCY=SEK

Option 2: Publish the config file and set the default options there.

php artisan vendor:publish --provider="Pelmered\FilamentMoneyField\FilamentMoneyFieldServiceProvider" --tag="config"

Decimals and significant digits

The number of decimals and significant digits can be set in the config file. Defaults to 2.

//with input 123456
MONEY_DECIMAL_DIGITS=0 // Gives 0 decimals, e.g. $1,235
MONEY_DECIMAL_DIGITS=2 // Gives 2 decimals, e.g. $1,234.56

For significant digits, use negative values. For example -2 will give you 2 significant digits.

//with input 12345678
MONEY_DECIMAL_DIGITS=-2 // Gives 2 significant digits, e.g. $120,000
MONEY_DECIMAL_DIGITS=-4 // Gives 4 significant digits, e.g. $123,400

This can also be set on a per-field basis.

MoneyInput::make('price')->decimals(0);
MoneyEntry::make('price')->decimals(2);
MoneyColumn::make('price')->decimals(-2);

Usage

Form

use Pelmered\FilamentMoneyField\Forms\Components\MoneyInput;

MoneyInput::make('price'); // Defaults to USD and the current Laravel locale, or what you have set in your .env/config.

MoneyInput::make('price')
    ->currency('USD')
    ->locale('en_US'),

MoneyInput::make('price')
    ->currency('SEK')
    ->locale('sv_SE'),

MoneyInput::make('price')
    ->currency('SEK')
    ->locale('sv_SE')
    ->minValue(0) // Do not allow negative values.
    ->maxValue(10000) // Add min and max value (in minor units, i.e. cents) to the input field. In this case no values over 100
    ->step(100) // Step value for the input field. In this case only multiples of 100 are allowed.
    ->decimals(0)
    ->getSymbolPlacement('after'), // Possible options: 'after', 'before', 'none'. Defaults to 'before'

Table column

use Pelmered\FilamentMoneyField\Tables\Columns\MoneyColumn;

MoneyColumn::make('price'); // Defaults to USD and the current Laravel locale, or what you have set in your .env/config.

MoneyColumn::make('price')
    ->currency('USD')
    ->locale('en_US'),

MoneyColumn::make('price')
    ->currency('SEK')
    ->locale('sv_SE'),

MoneyColumn::make('price')
    ->short(), // Short format, e.g. $1.23M instead of $1,234,567.89

MoneyColumn::make('price')
    ->short(showCurrencySymbol: false), // Short format without currency symbol, e.g. 1.23M instead of $1.23M

MoneyColumn::make('price')
    ->decimals(4)
    ->short(), // $1.2345M

MoneyColumn::make('price')
    ->decimals(-3) // 3 significant digits
    ->short(), // $1.23K or $23.1M

InfoList

use Pelmered\FilamentMoneyField\Infolists\Components\MoneyEntry;

MoneyEntry::make('price'); // Defaults to USD and the current Laravel locale, or what you have set in your .env/config.

// The default can be set in the Infolist class with:
public static string $defaultCurrency = 'SEK';

MoneyEntry::make('price')
    ->currency('USD')
    ->locale('en_US'),

MoneyEntry::make('price')
    ->currency('SEK')
    ->locale('sv_SE'),

MoneyEntry::make('price')
    ->short(), // Short fromat, e.g. $1.23M instead of $1,234,567.89

Global Configuration

If you want to use the formatting mask on the MoneyInput component

This will auto format the input field as you type.

This is a bit experimental at the moment and is therefore disabled by default. Hopefully it will be improved in the future and enabled by default in the next major version. Please try it out and provide feedback.

MONEY_USE_INPUT_MASK=true // Defaults to false

Use international currency codes (ISO 4217)

If you want to use international currency codes istead of their symbols or local short variants. For example USD instead of $, EUR instead of € or SEK instead of kr.

MONEY_INTL_CURRENCY_SYMBOL=true // Defaults to false

Placement of currency symbol/code on input fields

Possible options: after, before, none.

MONEY_UNIT_PLACEMENT=after // Defaults to before

Decimals and significant digits

The number of decimals and significant digits can be set in the config file. Defaults to 2.

//with input 123456
MONEY_DECIMAL_DIGITS=0 // Gives 0 decimals, e.g. $1,235
MONEY_DECIMAL_DIGITS=2 // Gives 2 decimals, e.g. $1,234.56

For significant digits, use negative values. For example -2 will give you 2 significant digits.

//with input 12345678
MONEY_DECIMAL_DIGITS=-2 // Gives 2 significant digits, e.g. $120,000
MONEY_DECIMAL_DIGITS=-4 // Gives 4 significant digits, e.g. $123,400

This can also be set on a per-field basis.

MoneyInput::make('price')->decimals(0);
MoneyEntry::make('price')->decimals(2);
MoneyColumn::make('price')->decimals(-2);

// You can also pass a callback to the decimals method.
MoneyInput::make('price')->decimals(function () {
    return 0;
});

Roadmap / Ideas for the future

Contact me or create an issue if you want something of this, or something else. I appreciate if you could tell me a bit about your use case for that feature as well.

• Improve the input mask.
• Add support for dynamic currency and locale based on current user.
• Currency conversions. Set what base currency the value in the database is and then convert to the current users preferred currency on the fly. Not sure how edit/create should be handled in this case.

Contributing

I'm very happy to receive PRs with fixes or improvements. If it is a new feature, it is probably best to open an issue first, so I can give feedback and see if that is something I think would fit in this package. Especially if it is a larger feature, so you don't waste your time.

When you are submitting a PR, I appreciate if you:

• Add tests for your code. Not a strict requirement. Ask for guidance if you are unsure. I will try to help if I have time.
• Run the test suite and make sure it passes with composer test.
• Check the code with composer lint. This will run both PHPStan and Pint. See if you can address any issues there before submitting.