Currency Class

Overview

The Currency class represents a currency with all its properties including symbol, code, decimal places, and formatting rules. It wraps the underlying Brick\Money\Currency class and adds Laravel-specific features and customization options.

Creating Currency Objects

of() - Create from Code

Create a Currency instance from a currency code or Brick\Money\Currency object.

use Devhammed\LaravelBrickMoney\Currency;

// Create from ISO code
$usd = Currency::of('USD');
$eur = Currency::of('EUR');
$jpy = Currency::of('JPY');

// Case-insensitive
$usd = Currency::of('usd');
$usd = Currency::of('Usd');

Method Signature

public static function of(BrickCurrency|string $currency): static

currency

BrickCurrency|string

required

Currency code (e.g., “USD”, “EUR”) or Brick\Money\Currency instance

The currency code is automatically converted to uppercase and trimmed. If the currency is not found in the configured currencies, an UnknownCurrencyException is thrown.

Currency Properties

Basic Information

Access fundamental currency properties.

$usd = Currency::of('USD');

// Get currency code
echo $usd->getCode();
// Output: "USD"

// Get currency name
echo $usd->getName();
// Output: "US Dollar"

// Get ISO numeric code
echo $usd->getNumericCode();
// Output: 840

// Get currency symbol
echo $usd->getSymbol();
// Output: "$"

$usd = Currency::of('USD');

$usd->getCode();        // "USD"
$usd->getName();        // "US Dollar"
$usd->getNumericCode(); // 840
$usd->getSymbol();      // "$"

$eur = Currency::of('EUR');

$eur->getCode();        // "EUR"
$eur->getName();        // "Euro"
$eur->getNumericCode(); // 978
$eur->getSymbol();      // "€"

$gbp = Currency::of('GBP');

$gbp->getCode();        // "GBP"
$gbp->getName();        // "Pound Sterling"
$gbp->getNumericCode(); // 826
$gbp->getSymbol();      // "£"

$jpy = Currency::of('JPY');

$jpy->getCode();        // "JPY"
$jpy->getName();        // "Yen"
$jpy->getNumericCode(); // 392
$jpy->getSymbol();      // "¥"

Formatting Properties

Control how currency amounts are displayed.

Symbol Positioning

$usd = Currency::of('USD');

// Check if symbol comes before amount
echo $usd->isSymbolFirst();
// Output: true ($ comes before: $100.00)

// Check if there's a space between symbol and amount
echo $usd->isSymbolSpaced();
// Output: false (no space: $100.00)

Currency formatting examples

USD: $100.00 - symbol first, no space
EUR: 100.00 € - symbol last, space before
GBP: £100.00 - symbol first, no space
CAD: $100.00 - symbol first, no space

Decimal Formatting

$usd = Currency::of('USD');

// Get number of decimal places
echo $usd->getDecimalPlaces();
// Output: 2 (USD uses 2 decimal places)

// Get decimal separator
echo $usd->getDecimalSeparator();
// Output: "." (period for USD)

USD/EUR
JPY
BHD

$usd = Currency::of('USD');

$usd->getDecimalPlaces();    // 2
$usd->getDecimalSeparator(); // "."

// Formats as: 1,234.56

$jpy = Currency::of('JPY');

$jpy->getDecimalPlaces();    // 0
$jpy->getDecimalSeparator(); // "."

// Formats as: 1,234 (no decimals)

$bhd = Currency::of('BHD');

$bhd->getDecimalPlaces();    // 3
$bhd->getDecimalSeparator(); // "."

// Formats as: 1,234.567 (3 decimals)

Thousand Separator

$usd = Currency::of('USD');

// Get digit grouping size
echo $usd->getThousandPlaces();
// Output: 3 (groups of 3 digits)

// Get thousand separator character
echo $usd->getThousandSeparator();
// Output: "," (comma for USD)

Method Reference

getCode()

string

Returns the ISO 4217 currency code (e.g., “USD”, “EUR”)

getName()

string

Returns the full currency name (e.g., “US Dollar”)

getNumericCode()

int

Returns the ISO 4217 numeric code (e.g., 840 for USD)

getSymbol()

string

Returns the currency symbol (e.g., ”$”, ”€”, ”£”)

isSymbolFirst()

bool

Returns true if symbol appears before the amount

isSymbolSpaced()

bool

Returns true if there should be a space between symbol and amount

getDecimalPlaces()

int

Returns the number of decimal places (e.g., 2 for USD, 0 for JPY)

getDecimalSeparator()

string

Returns the decimal separator character (e.g., ”.” or ”,”)

getThousandPlaces()

int

Returns the digit grouping size (typically 3)

getThousandSeparator()

string

Returns the thousand separator character (e.g., ”,”, ”.”, or ” “)

Currency Comparison

Check if two currencies are the same.

$usd1 = Currency::of('USD');
$usd2 = Currency::of('usd');
$eur = Currency::of('EUR');

// Compare currencies by their codes
if ($usd1->is($usd2)) {
    echo "Same currency";
}
// Output: "Same currency"

if (!$usd1->is($eur)) {
    echo "Different currencies";
}
// Output: "Different currencies"

Method Signature

public function is(Currency $currency): bool

Currencies are considered equal if their currency codes match. Case and whitespace differences are handled during creation.

Underlying Brick Currency

Access the wrapped Brick\Money\Currency instance.

$currency = Currency::of('USD');

// Get the underlying Brick\Money\Currency
$brickCurrency = $currency->getCurrency();

// Use Brick Money methods directly
echo $brickCurrency->getCurrencyCode();
// Output: "USD"

echo $brickCurrency->getDefaultFractionDigits();
// Output: 2

String Conversion

Currency objects can be cast to strings.

$usd = Currency::of('USD');

echo $usd;
// Output: "USD"

echo (string) $usd;
// Output: "USD"

$message = "Price in {$usd}";
echo $message;
// Output: "Price in USD"

JSON Serialization

Currencies can be serialized to JSON with all their properties.

$usd = Currency::of('USD');

// Convert to array
$array = $usd->toArray();
print_r($array);
/* Output:
[
    'name' => 'US Dollar',
    'code' => 'USD',
    'numeric_code' => 840,
    'symbol' => '$',
    'symbol_first' => true,
    'symbol_spaced' => false,
    'decimal_places' => 2,
    'decimal_separator' => '.',
    'thousand_places' => 3,
    'thousand_separator' => ','
]
*/

// Convert to JSON
echo $usd->toJson();
/* Output:
{
    "name": "US Dollar",
    "code": "USD",
    "numeric_code": 840,
    "symbol": "$",
    "symbol_first": true,
    "symbol_spaced": false,
    "decimal_places": 2,
    "decimal_separator": ".",
    "thousand_places": 3,
    "thousand_separator": ","
}
*/

Custom JSON Serialization

Customize how currencies are serialized to JSON globally.

use Devhammed\LaravelBrickMoney\Currency;

// Set custom serializer
Currency::jsonSerializer(function ($currency) {
    return [
        'code' => $currency->getCode(),
        'symbol' => $currency->getSymbol(),
    ];
});

$usd = Currency::of('USD');
echo $usd->toJson();
// Output: {"code":"USD","symbol":"$"}

Method Signature

public static function jsonSerializer(?Closure $callback = null): Closure

callback

Closure

default:"null"

Optional callback that receives Currency instance and returns array for serialization

Managing Available Currencies

Get or set the list of available currencies.

use Devhammed\LaravelBrickMoney\Currency;

// Get all available currencies
$currencies = Currency::currencies();

// Check if a currency exists
if (isset($currencies['USD'])) {
    echo "USD is available";
}

// Custom currency configuration
Currency::currencies([
    'USD' => [
        'name' => 'US Dollar',
        'numeric_code' => 840,
        'symbol' => '$',
        'symbol_first' => true,
        'symbol_spaced' => false,
        'decimal_places' => 2,
        'decimal_separator' => '.',
        'thousand_places' => 3,
        'thousand_separator' => ',',
    ],
    'EUR' => [
        'name' => 'Euro',
        'numeric_code' => 978,
        'symbol' => '€',
        'symbol_first' => false,
        'symbol_spaced' => true,
        'decimal_places' => 2,
        'decimal_separator' => ',',
        'thousand_places' => 3,
        'thousand_separator' => '.',
    ],
]);

Method Signature

public static function currencies(?array $currencies = null): array

By default, currencies are loaded from the config/brick-money.php configuration file. You can override this at runtime if needed.

Currency Configuration Structure

Each currency in the configuration must have these properties:

[
    'CODE' => [
        'name' => string,              // Full currency name
        'numeric_code' => int,         // ISO 4217 numeric code
        'symbol' => string,            // Currency symbol
        'symbol_first' => bool,        // Symbol before amount?
        'symbol_spaced' => bool,       // Space between symbol and amount?
        'decimal_places' => int,       // Number of decimal places
        'decimal_separator' => string, // Decimal separator character
        'thousand_places' => int,      // Digit grouping size
        'thousand_separator' => string // Thousand separator character
    ]
]

Laravel Integration

Array and JSON Contracts

Currency implements Laravel’s Arrayable and Jsonable contracts.

use Devhammed\LaravelBrickMoney\Currency;

$currency = Currency::of('USD');

// Works with Laravel responses
return response()->json(['currency' => $currency]);

// Works with collections
$currencies = collect(['USD', 'EUR', 'GBP'])
    ->map(fn($code) => Currency::of($code));

foreach ($currencies as $currency) {
    echo $currency->getName();
}

Macros

Extend Currency with custom methods using Laravel’s Macroable trait.

use Devhammed\LaravelBrickMoney\Currency;

// Define a macro
Currency::macro('isCrypto', function () {
    return in_array($this->getCode(), ['BTC', 'ETH', 'USDT']);
});

// Use the macro
$btc = Currency::of('BTC');
if ($btc->isCrypto()) {
    echo "This is a cryptocurrency";
}

Common Currency Examples

Major World Currencies

// US Dollar
$usd = Currency::of('USD');
// Symbol: $, Position: Before, Decimals: 2
// Format: $1,234.56

// Euro
$eur = Currency::of('EUR');
// Symbol: €, Position: After (with space), Decimals: 2
// Format: 1.234,56 €

// British Pound
$gbp = Currency::of('GBP');
// Symbol: £, Position: Before, Decimals: 2
// Format: £1,234.56

// Japanese Yen
$jpy = Currency::of('JPY');
// Symbol: ¥, Position: Before, Decimals: 0
// Format: ¥1,234

Special Decimal Places

// Bahraini Dinar - 3 decimal places
$bhd = Currency::of('BHD');
echo $bhd->getDecimalPlaces(); // 3
// Format: BD 1,234.567

// Chilean Peso - 0 decimal places
$clp = Currency::of('CLP');
echo $clp->getDecimalPlaces(); // 0
// Format: $1,234

Different Separators

// Switzerland - apostrophe as thousand separator
$chf = Currency::of('CHF');
echo $chf->getThousandSeparator(); // "'"
// Format: CHF 1'234.56

// France - space as thousand separator
$eur = Currency::of('EUR');
echo $eur->getThousandSeparator(); // " "
// Format: 1 234,56 €

Getting Started

Core Concepts

Eloquent Integration

HTTP Integration

Views

Advanced

API Reference

Overview

Creating Currency Objects

of() - Create from Code

Method Signature

Currency Properties

Basic Information

Formatting Properties

Symbol Positioning

Decimal Formatting

Thousand Separator

Method Reference

Currency Comparison

Method Signature

Underlying Brick Currency

String Conversion

JSON Serialization

Custom JSON Serialization

Method Signature

Managing Available Currencies

Method Signature

Currency Configuration Structure

Laravel Integration

Array and JSON Contracts

Macros

Common Currency Examples

Next Steps

Money Class

Configuration

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Eloquent Integration

HTTP Integration

Views

Advanced

API Reference

​Overview

​Creating Currency Objects

​of() - Create from Code

​Method Signature

​Currency Properties

​Basic Information

​Formatting Properties

​Symbol Positioning

​Decimal Formatting

​Thousand Separator

​Method Reference

​Currency Comparison

​Method Signature

​Underlying Brick Currency

​String Conversion

​JSON Serialization

​Custom JSON Serialization

​Method Signature

​Managing Available Currencies

​Method Signature

​Currency Configuration Structure

​Laravel Integration

​Array and JSON Contracts

​Macros

​Common Currency Examples

​Next Steps

Money Class

Configuration

Build docs developers (and LLMs) love

Overview

Creating Currency Objects

of() - Create from Code

Method Signature

Currency Properties

Basic Information

Formatting Properties

Symbol Positioning

Decimal Formatting

Thousand Separator

Method Reference

Currency Comparison

Method Signature

Underlying Brick Currency

String Conversion

JSON Serialization

Custom JSON Serialization

Method Signature

Managing Available Currencies

Method Signature

Currency Configuration Structure

Laravel Integration

Array and JSON Contracts

Macros

Common Currency Examples

Next Steps