Nova Money Field Laravel Package

Getting Started

The v1.5.1 release adds first-class support for moneyphp/money v4 and cknow/laravel-money. That means the package can now accept and return Money value objects from either library instead of forcing you to convert to raw integers or strings at the boundary.

Start by checking the installed constraints:

composer show moneyphp/money cknow/laravel-money

If you are on Money v3, this release is the upgrade path, but you should treat it as a coordinated dependency bump (see Gotchas). If you are already on v4 or using cknow/laravel-money, you can pass those objects into the package's money-aware APIs directly.

Look first at:

1. The package service provider and any bindings for money/currency services.
2. The config file (config/...php after publishing) for default currency, locale, and formatter settings.
3. The package's money adapter or cast classes — these are the integration points for both libraries.
4. The package test suite for examples of constructing Money objects the supported way.

A good first use case is persisting and formatting a monetary amount on a model:

use Money\Money;

$price = Money::USD(1999); // 19.99 USD in minor units

$order->price = $price;    // if the package provides a money cast
$order->save();

echo $order->price->format(); // via the package or cknow/laravel-money helper

If you only need formatting in Blade, cknow/laravel-money gives you helpers such as Money::USD(1999)->format(). If you need domain logic (arithmetic, allocation, currency conversion), keep moneyphp/money objects in your domain layer and let the package handle persistence and presentation.

Implementation Patterns

Use one Money library per layer. A practical split is:

• moneyphp/money in domain services, actions, and value objects.
• cknow/laravel-money in controllers, Blade views, and anything that needs locale-aware formatting.

Both are now supported, but mixing both freely inside the same class makes type hints noisy. Pick an adapter boundary (a cast, a DTO, or a formatter service) and convert there.

Model casts for persistence. Store amounts as integer minor units plus a currency column, and use a cast to hydrate a Money object:

protected $casts = [
    'price' => MoneyCast::class, // package-provided or your own
];

If the package does not ship a cast for your use case, write one that implements CastsAttributes and delegates to the package's money adapter. Keep the database representation stable even if you later change Money major versions.

Validation and form requests. Validate the raw input as an integer or decimal string, then construct the Money object in a form request or DTO, not in the model:

$data = $request->validated();

$money = Money::USD((int) $data['amount']);

Validate currency separately against your supported list. Do not let arbitrary currency codes reach the Money constructor without a check — moneyphp/money will throw on malformed or unsupported currencies, and that should be a 422, not a 500.

Actions and services. Type-hint Money\Money in domain methods. Because both libraries are supported, avoid type-hinting the cknow/laravel-money wrapper in domain code; use it only at the edges.

final class ApplyDiscount
{
    public function __invoke(Money $price, int $percent): Money
    {
        return $price->multiply($percent / 100);
    }
}

Serialization. Money objects do not serialize cleanly to JSON by default. In API resources, output primitives explicitly:

return [
    'amount' => $this->price->getAmount(),
    'currency' => $this->price->getCurrency()->getCode(),
    'formatted' => $this->price->format(),
];

Queues and jobs. Pass primitives or a DTO with amount and currency into queued jobs, then reconstruct the Money object inside handle(). Serializing Money objects directly across queue boundaries is fragile and version-sensitive.

Testing. Use factories and helper methods to build Money objects consistently. Assert on getAmount() and getCurrency()->getCode() rather than on formatted strings, which depend on locale and formatter configuration.

Gotchas and Tips

Money v4 is a breaking major version. The v1.5.1 support is for v4, not v3. If other dependencies pin moneyphp/money:^3.0, Composer will either fail to resolve or force an older version of this package. Run composer why-not moneyphp/money ^4.0 before upgrading and expect to bump or replace any package that still requires v3.

Check the constructor and factory signatures. Money v4 changed several APIs compared with v3. Constructors, currency instantiation, and some arithmetic helpers differ. If you have custom code that builds Money objects, run the test suite and grep for direct new Money(...) calls — prefer Money::USD() or Money::of() style factories where available.

cknow/laravel-money version compatibility. The wrapper's own release line determines which moneyphp/money major it supports. Confirm the installed wrapper version supports v4 before relying on its helpers; otherwise you will get a mixed v3/v4 install or a class-not-found error at runtime.

Minor units and floating point. Never pass floats into Money constructors. Use integer minor units or decimal strings. A value like 19.99 cast to float and multiplied can produce 1998 instead of 1999. Validate and normalize at the input boundary.

Currency mismatch exceptions. Arithmetic between Money objects with different currencies throws. This is correct behavior, but it often surfaces as a 500 in checkout flows. Guard conversions explicitly and make currency a required part of your DTOs.

Formatter configuration. Default currency, locale, and decimal precision usually live in the package config. After publishing, clear config cache (php artisan config:clear) — a stale cached config is a common reason formatted output ignores your settings in production but works locally.

Debugging Money objects. dd($money) shows the amount and currency but not always the formatted value. Use getAmount(), getCurrency()->getCode(), and the package/formatter's format() method separately to isolate whether the problem is storage, arithmetic, or presentation.

Extension points. If you need custom behavior, the usual places are a custom cast, a formatter binding in the service provider, or a wrapper service around the package's money adapter. Keeping your own adapter interface means a future Money v5 bump only touches one class.

Blade and API output drift. Formatting in Blade via cknow/laravel-money and returning raw minor units in your API is a common source of confusion for front-end consumers. Document which representation each endpoint returns, and keep the formatted value as a presentation-only field.