Filament Money Field

https://github.com/pelmered/filament-money-field
Admin
A Filament money field package powered by Money PHP, offering superior localization support for...
Tokens:7,416
Snippets:30
Trust Score:9.1
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Filament Money Field

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Installs the filament-money-field package using Composer. This command downloads and integrates the package into your Laravel project.

```bash
composer require pelmered/filament-money-field
```

--------------------------------

### Configuring Available Currencies

Source: https://github.com/pelmered/filament-money-field/blob/main/UPGRADE.md

Shows how to define the list of available currencies for the package, either within the `filament-money-field.php` configuration file or via the `MONEY_AVAILABLE_CURRENCIES` environment variable.

```php
'available_currencies' => [
    'USD',
    'EUR',
    'GBP',
],
```

```env
MONEY_AVAILABLE_CURRENCIES=USD,EUR,GBP
```

--------------------------------

### Money Formatter: Using numberFormat()

Source: https://github.com/pelmered/filament-money-field/blob/main/UPGRADE.md

Demonstrates the change in the Money Formatter, where `formatAsDecimal()` has been removed and replaced by `numberFormat()`. The `numberFormat()` method does not require a currency parameter.

```php
// Old method (removed):
// MoneyFormatter::formatAsDecimal(123456, Currency::fromCode('USD')); // Output: $1,234.56

// New method:
MoneyFormatter::numberFormat(123456); // Output: $1,234.56
```

--------------------------------

### Eloquent Accessors for Raw Money/Currency Values

Source: https://github.com/pelmered/filament-money-field/blob/main/UPGRADE.md

Provides examples of creating Eloquent accessors to retrieve raw values for money and currency fields, bypassing the value object casting. This is useful if you prefer to work with raw string values in your application.

```php
use Illuminate\Database\Eloquent\Casts\Attribute;

protected function price(): Attribute
{
    return Attribute::make(
        get: static fn (string $value) => $value
    );
}
protected function priceCurrency(): Attribute
{
    return Attribute::make(
        get: static fn (string $value) => $value,
    );
```

--------------------------------

### Database Schema Modifications for Money Fields

Source: https://github.com/pelmered/filament-money-field/blob/main/UPGRADE.md

Illustrates how to add new money fields to a database table using the `money()` schema builder method, which automatically creates both the money and currency columns. It also shows how to change an existing column to a currency column.

```php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::table('tablename', function (Blueprint $table) {
    $table->money('price'); // Creates 'price' (integer) and 'price_currency' (char(3))
});
```

```php
Schema::table('tablename', function (Blueprint $table) {
    $table->char('price_currency', 3)->after('price')->change();
    $this->index(['price', 'price_currency']);
});
```

--------------------------------

### Eloquent Model Casting for Money and Currency

Source: https://github.com/pelmered/filament-money-field/blob/main/UPGRADE.md

Demonstrates how to configure Eloquent model casts for money and currency fields using Pelmered\FilamentMoneyField\Casts\MoneyCast and Pelmered\FilamentMoneyField\Casts\CurrencyCast. This can be done within the `casts()` method or as a `$casts` property in the model.

```php
use Pelmered\FilamentMoneyField\Casts\CurrencyCast;
use Pelmered\FilamentMoneyField\Casts\MoneyCast;

protected function casts(): array
{
    return [
        'price' => MoneyCast::class,
        'price_currency' => CurrencyCast::class,
        'another_price' => MoneyCast::class,
        'another_price_currency' => CurrencyCast::class,
    ];
}
```

```php
protected $casts = [
    'price' => MoneyCast::class,
    'price_currency' => CurrencyCast::class,
    'another_price' => MoneyCast::class,
    'another_price_currency' => CurrencyCast::class,
];
```

--------------------------------

### Get Currency Formatting Rules

Source: https://github.com/pelmered/filament-money-field/blob/main/MONEY-FORMATTER.md

Retrieves the formatting rules for a specific currency and locale, including the currency symbol, decimal separator, grouping separator, and number of fraction digits. This is useful for displaying monetary values consistently.

```php
public static function getFormattingRules(
    string $locale,
    Currency|MoneyCurrency $currency
): Pelmered\LaraPara\MoneyFormatter\CurrencyFormattingRules
```

--------------------------------

### Get Default Application Currency

Source: https://github.com/pelmered/filament-money-field/blob/main/MONEY-FORMATTER.md

Retrieves the default currency configured for the application. It checks the `filament-money-field.default_currency` configuration or falls back to Filament's default currency setting.

```php
public static function getDefaultCurrency(): Pelmered\LaraPara\Currencies\Currency
```

--------------------------------

### Configure Decimal and Significant Digits

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Control the number of decimal places or significant digits displayed for monetary values. This can be set globally via environment variables or on a per-field basis in your Filament setup. The amount is always saved with full precision.

```env
//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
```

```env
//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
```

--------------------------------

### Run Test Suite

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Executes the project's test suite using Composer. This command ensures that all tests pass before submitting changes.

```shell
composer test
```

--------------------------------

### Publish Configuration

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Publish the package's configuration file to your application's config directory using the Artisan command. This allows for direct modification of default settings.

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

--------------------------------

### Filament Money Input Component

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Demonstrates the usage of the MoneyInput component in Filament forms. It covers default settings and customization options like currency, locale, minimum/maximum values, step, decimals, symbol placement, and currency switcher.

```php
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'
    ->hideCurrencySymbol() // Hide currency symbol. 
    ->currencySwitcherEnabled() // Enable the currency switcher (if it is disabled globally in the config file). 
    ->currencySwitcherDisabled() // Disable the currency switcher (if it is enabled globally in the config file). 
```

--------------------------------

### Check Code with Linter

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Runs PHPStan and Pint to check code quality and style. This command helps identify and fix potential issues before submission.

```shell
composer lint
```

--------------------------------

### Filament Money Entry Component

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Shows the implementation of the MoneyEntry component for displaying monetary values in Filament infolists. It covers default settings and customization for currency, locale, and short formatting.

```php
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 for Money Field

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Explains the global configuration options available for the Filament Money Field package via environment variables. This includes enabling input masks, using international currency symbols, setting currency symbol placement, and defining default decimal digits or significant digits.

```env
MONEY_USE_INPUT_MASK=true // Defaults to false

MONEY_INTL_CURRENCY_SYMBOL=true // Defaults to false

MONEY_UNIT_PLACEMENT=after // Defaults to before

//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

//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
```

--------------------------------

### Database Migrations for Money Fields

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Define database schema changes to include money and currency columns. The `money` method creates both the amount column (integer or decimal) and a corresponding currency column. Available types include `money`, `nullableMoney`, `smallMoney`, and `unsignedMoney` with different storage options.

```php
Schema::table('tablename', function (Blueprint $table) {
    $table->money('price'); // Creates 'price' (integer) and 'price_currency' (char(3))
});
```

```php
Schema::table('tablename', function (Blueprint $table) {
    $table->char('price_currency', 3)->after('price')->change();
    $this->index(['price', 'price_currency']);
});
```

--------------------------------

### Per-Field Decimals Configuration

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Demonstrates how to set the number of decimals or significant digits on a per-field basis for MoneyInput, MoneyEntry, and MoneyColumn components. This includes using static values and callbacks.

```php
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;
});
```

--------------------------------

### Format Money Object

Source: https://github.com/pelmered/filament-money-field/blob/main/MONEY-FORMATTER.md

Formats a Money\Money object into a localized currency string. It takes the Money object, locale, an optional output style, and the number of decimals as input.

```php
use Money\Money;
use Money\Currency;
use Pelmered\LaraPara\MoneyFormatter\MoneyFormatter;

$money = new Money(123456, new Currency('USD'));
echo MoneyFormatter::formatMoney($money, 'en_US'); // Output: $1,234.56

$moneySEK = new Money(123456, new Currency('SEK'));
echo MoneyFormatter::formatMoney($moneySEK, 'sv_SE'); // Output: 1 234,56 kr
```

--------------------------------

### Eloquent Casts for Money and Currency

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Configure Eloquent model casts to automatically convert database columns into `MoneyMoney` and `PelmeredLaraParaCurrenciesCurrency` value objects. This provides convenient access to monetary data with proper type handling.

```php
use Pelmered\FilamentMoneyField\Casts\CurrencyCast;
use Pelmered\FilamentMoneyField\Casts\MoneyCast;

protected function casts(): array
{
    return [
        'price' => MoneyCast::class,
        'price_currency' => CurrencyCast::class,
        'another_price' => MoneyCast::class,
        'another_price_currency' => CurrencyCast::class,
    ];
}
```

```php
protected $casts = [
    'price' => MoneyCast::class,
    'price_currency' => CurrencyCast::class,
    'another_price' => MoneyCast::class,
    'another_price_currency' => CurrencyCast::class,
];
```

--------------------------------

### Filament Money Column Component

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Illustrates how to use the MoneyColumn component in Filament table columns for displaying monetary values. It includes options for setting currency, locale, and using a short format for large numbers.

```php
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()
    ->hideCurrencySymbol(), // 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
```

--------------------------------

### Money Formatter Class

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Details the Money Formatter class, which can be used in your project for currency formatting. Public methods are stable and will not change without major version updates. This class is part of the LaraPara package.

```APIDOC
MoneyFormatter:
  // Public methods are stable and will not change without major version updates.
  // See documentation (MONEY-FORMATTER.md) for details.
  // This class is now part of the LaraPara package.
  // Example usage:
  // $formatter = new PelmeredFilamentMoneyFieldFormatterMoneyFormatter();
  // $formattedAmount = $formatter->format(1234.56, 'USD', 'en_US');
```

--------------------------------

### Short Number Formatting

Source: https://github.com/pelmered/filament-money-field/blob/main/MONEY-FORMATTER.md

Formats a value into a short, abbreviated format (e.g., "1.2K", "$10M"). Useful for displaying large numbers concisely. It handles currency symbols and allows customization of decimal places and whether to show the symbol.

```php
public static function formatShort(
    null|int|string|Money $value,
    Currency|MoneyCurrency $currency,
    string $locale,
    int $decimals = 2,
    bool $showCurrencySymbol = true
): string
```

```php
use Pelmered\LaraPara\MoneyFormatter\MoneyFormatter;
use Pelmered\LaraPara\Currencies\Currency;

// Values >= 100000 minor units (1000) are abbreviated
echo MoneyFormatter::formatShort(123456, Currency::fromCode('USD'), 'en_US'); // Output: $1.23K
echo MoneyFormatter::formatShort(123456789, Currency::fromCode('USD'), 'en_US'); // Output: $1.23M

// Different decimals
echo MoneyFormatter::formatShort(123456789, Currency::fromCode('USD'), 'en_US', decimals: 1); // Output: $1.2M
echo MoneyFormatter::formatShort(123456789, Currency::fromCode('USD'), 'en_US', decimals: 0); // Output: $1M
echo MoneyFormatter::formatShort(123456789, Currency::fromCode('USD'), 'en_US', decimals: -3); // Output: $1.23M

// Without currency symbol
echo MoneyFormatter::formatShort(123456789, Currency::fromCode('USD'), 'en_US', showCurrencySymbol: false); // Output: 1.23M

// Values < 100000 minor units (1000) are not abbreviated
echo MoneyFormatter::formatShort(99999, Currency::fromCode('USD'), 'en_US'); // Output: $999.99
echo MoneyFormatter::formatShort(0, Currency::fromCode('USD'), 'en_US'); // Output: $0.00
```

--------------------------------

### Custom Accessors for Raw Values

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Provides an alternative to using value objects by defining custom Eloquent accessors that return the raw string values of the money and currency columns. This can be useful if direct string manipulation is preferred.

```php
use Illuminate\Database\Eloquent\Casts\Attribute;

protected function price(): Attribute
{
    return Attribute::make(
        get: static fn (string $value) => $value
    );
}
protected function priceCurrency(): Attribute
{
    return Attribute::make(
        get: static fn (string $value) => $value,
    );
}
```

--------------------------------

### Set Default Currency and Locale

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Configure the default currency and locale for all money fields by setting environment variables. This avoids the need to specify them for each field individually.

```env
MONEY_DEFAULT_LOCALE=sv_SE
MONEY_DEFAULT_CURRENCY=SEK
```

--------------------------------

### Accessing Money and Currency Value Objects

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Demonstrates how to access the amount and currency code from the casted Eloquent model attributes. The `Money` object's amount can be retrieved using `getAmount()`, and the currency code from the `Currency` object using `getCode()`.

```php
// Accessing the Money object
$model->price->getAmount(); 

// Accessing the Currency object
$model->priceCurrency->getCode();
```

--------------------------------

### Fix Code Automatically

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Attempts to automatically fix code style and quality issues identified by the linter. This is a convenient way to address linting errors.

```shell
composer fix
```

--------------------------------

### Format Value with Currency

Source: https://github.com/pelmered/filament-money-field/blob/main/MONEY-FORMATTER.md

Formats a raw numeric value or a Money\Money object into a localized string, with an option to show the currency symbol. It supports various input types for the value and currency.

```php
use Pelmered\LaraPara\MoneyFormatter\MoneyFormatter;
use Pelmered\LaraPara\Currencies\Currency;
use Money\Money;

// Using integer (minor units)
echo MoneyFormatter::format(123456, Currency::fromCode('USD'), 'en_US'); // Output: $1,234.56
echo MoneyFormatter::format(123456, Currency::fromCode('SEK'), 'sv_SE'); // Output: 1 234,56 kr

// Without currency symbol
echo MoneyFormatter::format(123456, Currency::fromCode('USD'), 'en_US', showCurrencySymbol: false); // Output: 1,234.56

// Different decimals
echo MoneyFormatter::format(123456, Currency::fromCode('USD'), 'en_US', decimals: 0); // Output: $1,235
echo MoneyFormatter::format(123456, Currency::fromCode('USD'), 'en_US', decimals: 2); // Output: $1,235.56
echo MoneyFormatter::format(123456, Currency::fromCode('USD'), 'en_US', decimals: -2); // Output: $1,200

// Using Money object
$money = new Money\Money(123456, new Money\Currency('EUR'));
echo MoneyFormatter::format($money, Currency::fromCode('EUR'), 'de_DE'); // Output: 1.234,56 €
```

--------------------------------

### Number Formatting

Source: https://github.com/pelmered/filament-money-field/blob/main/MONEY-FORMATTER.md

Formats a numeric value into a localized numeric string. Supports various input types (int, float, string) and locale-specific formatting, including custom decimal and minor decimal places.

```php
public static function numberFormat(
    null|int|float|string $value,
    string $locale,
    int $decimals = 2,
    int $minorDecimals = 2
): string
```

```php
use Pelmered\LaraPara\MoneyFormatter\MoneyFormatter;

echo MoneyFormatter::numberFormat(1234.56, 'en_US'); // Output: 1,234.56
echo MoneyFormatter::numberFormat('1234.56', 'en_US'); // Output: 1,234.56
echo MoneyFormatter::numberFormat(123456, 'de_DE'); // Output: 1.234,56
echo MoneyFormatter::numberFormat($money->getAmount(), 'sv_SE'); // Output: 1 234,56
echo MoneyFormatter::numberFormat('non-numeric', 'en_US'); // Output: ''

// Different decimals
echo MoneyFormatter::numberFormat(1234.56, 'en_US', decimals: 0); // Output: 1,235
echo MoneyFormatter::numberFormat(1234.56, 'en_US', decimals: 2); // Output: 1,234.56
echo MoneyFormatter::numberFormat(1234.56, 'en_US', decimals: -2); // Output: 1,200

// Different minor decimals
echo MoneyFormatter::numberFormat(123456, 'en_US', minorDecimals: 0); // Output: 123,456
echo MoneyFormatter::numberFormat(123456, 'en_US', minorDecimals: 2); // Output: 1,234.56
echo MoneyFormatter::numberFormat(123456, 'en_US', decimals: 4, minorDecimals: 4); // Output: 12.3456
```

--------------------------------

### Parse Localized Decimal String

Source: https://github.com/pelmered/filament-money-field/blob/main/MONEY-FORMATTER.md

Parses a localized decimal string into an integer representing minor units (e.g., cents). It removes grouping separators before parsing. Handles different locales and currency formats. Throws a ParserException for invalid numeric values.

```php
public static function parseDecimal(
    ?string $moneyString,
    Currency|MoneyCurrency $currency,
    string $locale,
    int $decimals = 2
): string
```

--------------------------------

### Set Decimals Per Field

Source: https://github.com/pelmered/filament-money-field/blob/main/README.md

Override the global decimal or significant digit settings for individual money fields within your Filament forms or tables.

```php
MoneyInput::make('price')->decimals(0);
MoneyEntry::make('price')->decimals(2);
MoneyColumn::make('price')->decimals(-2);
```
Tokens:
Raw