Skip to main content
The package provides automatic JSON serialization for both Money and Currency objects with sensible defaults. You can customize the serialization format to match your API requirements.

​
Default Serialization

​
Money Object

By default, Money objects serialize to JSON with the following structure: 
{
    "amount": "100",
    "value": "1.00",
    "currency": {
        "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": ","
    }
}
​
amount
string
The amount in minor units (cents) as a string
​
value
string
The amount in major units (dollars) as a string
​
currency
object
The complete currency information object (see Currency Object below)

​
Currency Object

By default, Currency objects serialize to JSON with the following structure: 
{
    "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": ","
}
​
name
string
The full name of the currency (e.g., “US Dollar”)
​
code
string
The ISO 4217 currency code (e.g., “USD”)
​
numeric_code
integer
The ISO 4217 numeric currency code (e.g., 840 for USD)
​
symbol
string
The currency symbol (e.g., ”$”)
​
symbol_first
boolean
Whether the symbol appears before the amount when formatting
​
symbol_spaced
boolean
Whether there should be a space between the symbol and amount
​
decimal_places
integer
The number of decimal places for the currency
​
decimal_separator
string
The character used to separate decimal places (e.g., ”.” or ”,”)
​
thousand_places
integer
The number of digits per thousand group
​
thousand_separator
string
The character used to separate thousands (e.g., ”,” or ” “)

​
Custom Serialization

​
Customizing Money Serialization

You can customize how Money objects are serialized using the Money::jsonSerializer() method: 
use Devhammed\LaravelBrickMoney\Money;

Money::jsonSerializer(fn(Money $money) => [
    'amount' => (string) $money->getAmount(),
    'currency' => $money->getCurrency()->getCode(),
]);
This will produce a simplified JSON structure: 
{
    "amount": "1.00",
    "currency": "USD"
}

​
Customizing Currency Serialization

You can customize how Currency objects are serialized using the Currency::jsonSerializer() method: 
use Devhammed\LaravelBrickMoney\Currency;

Currency::jsonSerializer(fn(Currency $currency) => [
    'name' => $currency->getName(),
    'code' => $currency->getCode(),
]);
This will produce: 
{
    "name": "US Dollar",
    "code": "USD"
}

​
Common Serialization Patterns

​
Minimal Format

For a minimal API response with just essential data: 
use Devhammed\LaravelBrickMoney\Money;
use Devhammed\LaravelBrickMoney\Currency;

Money::jsonSerializer(fn(Money $money) => [
    'amount' => (string) $money->getAmount(),
    'currency' => $money->getCurrency()->getCode(),
]);

Currency::jsonSerializer(fn(Currency $currency) => $currency->getCode());
Result: 
{
    "price": {
        "amount": "99.99",
        "currency": "USD"
    },
    "currency": "USD"
}

​
Formatted Display

Include formatted strings for display purposes: 
use Devhammed\LaravelBrickMoney\Money;

Money::jsonSerializer(fn(Money $money) => [
    'amount' => (string) $money->getAmount(),
    'formatted' => $money->format(),
    'currency' => $money->getCurrency()->getCode(),
    'symbol' => $money->getCurrency()->getSymbol(),
]);
Result: 
{
    "price": {
        "amount": "99.99",
        "formatted": "$99.99",
        "currency": "USD",
        "symbol": "$"
    }
}

​
Minor Units Only

For APIs that work exclusively with minor units (cents): 
use Devhammed\LaravelBrickMoney\Money;

Money::jsonSerializer(fn(Money $money) => [
    'amount_cents' => (string) $money->getMinorAmount(),
    'currency_code' => $money->getCurrency()->getCode(),
]);
Result: 
{
    "price": {
        "amount_cents": "9999",
        "currency_code": "USD"
    }
}

​
Detailed Format

For comprehensive API responses with additional metadata: 
use Devhammed\LaravelBrickMoney\Money;

Money::jsonSerializer(fn(Money $money) => [
    'amount' => [
        'value' => (string) $money->getAmount(),
        'minor' => (string) $money->getMinorAmount(),
        'formatted' => $money->format(),
    ],
    'currency' => [
        'code' => $money->getCurrency()->getCode(),
        'name' => $money->getCurrency()->getName(),
        'symbol' => $money->getCurrency()->getSymbol(),
        'decimal_places' => $money->getCurrency()->getDecimalPlaces(),
    ],
]);
Result: 
{
    "price": {
        "amount": {
            "value": "99.99",
            "minor": "9999",
            "formatted": "$99.99"
        },
        "currency": {
            "code": "USD",
            "name": "US Dollar",
            "symbol": "$",
            "decimal_places": 2
        }
    }
}

​
Registration

Register your custom serializers in a service provider, typically AppServiceProvider: 
namespace App\Providers;

use Devhammed\LaravelBrickMoney\Money;
use Devhammed\LaravelBrickMoney\Currency;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Customize Money serialization
        Money::jsonSerializer(fn(Money $money) => [
            'amount' => (string) $money->getAmount(),
            'currency' => $money->getCurrency()->getCode(),
            'formatted' => $money->format(),
        ]);
        
        // Customize Currency serialization
        Currency::jsonSerializer(fn(Currency $currency) => [
            'code' => $currency->getCode(),
            'symbol' => $currency->getSymbol(),
        ]);
    }
}
Don’t forget to register your custom provider in config/app.php if you create a dedicated serializer provider.

​
Implementation Details

The serialization logic is implemented through Laravel’s Arrayable, Jsonable, and JsonSerializable interfaces:

​
Money Implementation

Money.php
class Money implements Arrayable, Jsonable, JsonSerializable, Stringable
{
    protected static Closure $jsonSerializer;
    
    public static function jsonSerializer(?Closure $callback = null): Closure
    {
        if ($callback !== null) {
            static::$jsonSerializer = $callback;
        }

        return static::$jsonSerializer ??= fn (Money $money) => [
            'amount' => (string) $money->getMinorAmount(),
            'value' => (string) $money->getAmount(),
            'currency' => $money->getCurrency(),
        ];
    }
    
    public function toArray(): array
    {
        return static::jsonSerializer()($this);
    }
    
    public function toJson($options = 0): string
    {
        return (string) json_encode($this->toArray(), $options);
    }
    
    public function jsonSerialize(): array
    {
        return $this->toArray();
    }
}

​
Currency Implementation

Currency.php
class Currency implements Arrayable, Jsonable, JsonSerializable, Stringable
{
    protected static Closure $jsonSerializer;
    
    public static function jsonSerializer(?Closure $callback = null): Closure
    {
        if ($callback !== null) {
            static::$jsonSerializer = $callback;
        }

        return static::$jsonSerializer ??= fn (Currency $currency) => [
            'name' => $currency->getName(),
            'code' => $currency->getCode(),
            'numeric_code' => $currency->getNumericCode(),
            'symbol' => $currency->getSymbol(),
            'symbol_first' => $currency->isSymbolFirst(),
            'symbol_spaced' => $currency->isSymbolSpaced(),
            'decimal_places' => $currency->getDecimalPlaces(),
            'decimal_separator' => $currency->getDecimalSeparator(),
            'thousand_places' => $currency->getThousandPlaces(),
            'thousand_separator' => $currency->getThousandSeparator(),
        ];
    }
    
    public function toArray(): array
    {
        return static::jsonSerializer()($this);
    }
    
    public function toJson($options = 0): string
    {
        return (string) json_encode($this->toArray(), $options);
    }
    
    public function jsonSerialize(): array
    {
        return $this->toArray();
    }
}

​
API Response Examples

​
Controller Usage

class ProductController extends Controller
{
    public function show(Product $product)
    {
        return response()->json([
            'id' => $product->id,
            'name' => $product->name,
            'price' => $product->price, // Money instance
            'currency' => $product->currency, // Currency instance
        ]);
    }
}
Response:
{
    "id": 1,
    "name": "Product Name",
    "price": {
        "amount": "9999",
        "value": "99.99",
        "currency": {
            "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": ","
        }
    },
    "currency": {
        "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": ","
    }
}

​
Next Steps

Request Macros

Extract Money and Currency from requests

Validation Rules

Validate money and currency inputs

Build docs developers (and LLMs) love

Get started for freeTalk to us