Getting Started

Minimal Setup

Installation:
```
composer require akaunting/laravel-money
```
Add the service provider to config/app.php (auto-discovered in Laravel ≥5.5).
Publish Config:
```
php artisan vendor:publish --tag=money
```
This generates config/money.php with default currencies (USD, EUR, etc.) and formatting rules.

First Use Case: Format a value in a Blade template:

// In a controller
$amount = \Akaunting\Money\Money::USD(1234.56);
return view('invoice', ['amount' => $amount]);

// In Blade
{{ $amount->format() }} // Outputs: $1,234.56

Key Initial Steps

Check config/money.php: Verify default currencies and formatting (e.g., decimal_separator, thousands_separator).

Test Basic Formatting:

\Akaunting\Money\Money::USD(1000)->format(); // "$1,000.00"
\Akaunting\Money\Money::EUR(1000)->format(); // "1.000,00 €"

Currency Conversion (requires config/money.php setup):

$usd = \Akaunting\Money\Money::USD(100);
$eur = $usd->convertTo('EUR'); // Uses rates from config

Implementation Patterns

Core Workflows

Formatting Values

Basic Usage:

$money = \Akaunting\Money\Money::USD(1234.567);
$money->format(); // "$1,234.57" (rounded to 2 decimals)

Custom Formatting: Override defaults in config/money.php:

'formats' => [
    'USD' => [
        'decimal_separator' => ',',
        'thousands_separator' => ' ',
        'prefix' => '$ ',
        'suffix' => '',
    ],
],

Then:

\Akaunting\Money\Money::USD(1000)->format(); // "$ 1 000,00"

Currency Conversion

Static Conversion:

\Akaunting\Money\Money::convert(100, 'USD', 'EUR'); // Uses rates from config

Dynamic Conversion:

$usd = \Akaunting\Money\Money::USD(100);
$eur = $usd->convertTo('EUR'); // Returns new Money object

Update Rates: Manually update config/money.php or fetch from an API (e.g., ExchangeRate-API).

Working with Collections

Format a Collection:

$amounts = collect([100, 200, 300])->map(fn($amount) => \Akaunting\Money\Money::USD($amount));
$formatted = $amounts->map->format(); // ["$100.00", "$200.00", ...]

Summing in Different Currencies:

$total = $amounts->sum(); // Throws exception if currencies differ
$totalUSD = $amounts->map->convertTo('USD')->sum();

Database Integration

Store Raw Values: Store the amount (integer) and currency (string) separately in the DB.

$money = \Akaunting\Money\Money::USD(1234);
$amount = $money->getAmount(); // 1234
$currency = $money->getCurrency()->getCode(); // "USD"

Retrieve and Reconstruct:

$money = new \Akaunting\Money\Money($amount, new \Akaunting\Money\Currency($currency));

API Responses

Consistent Formatting: Use a formatter in your API responses:

return response()->json([
    'amount' => $money->format(),
    'currency' => $money->getCurrency()->getSymbol(),
]);

Integration Tips

Laravel Cashier: Use akaunting/laravel-money to format subscription amounts:
```
$user->subscriptions->first()->price->format();
```
Localization: Combine with Laravel’s localization for dynamic currency symbols:
```
$money->getCurrency()->getSymbol(); // "€" for EUR
```

Validation: Validate monetary values in forms:

use Akaunting\Money\Validator;

Validator::make(['amount' => $request->amount], [
    'amount' => 'required|numeric|min:0',
]);

Gotchas and Tips

Common Pitfalls

Currency Rates Not Updated
- Issue: Conversion results are stale if rates in config/money.php aren’t updated.
- Fix: Fetch rates dynamically from an API (e.g., European Central Bank). Example:
```
$rates = json_decode(file_get_contents('https://api.exchangerate-api.com/v4/latest/USD'), true);
// Update config/money.php or cache the rates.
```
Decimal Precision Errors
- Issue: Floating-point arithmetic can cause rounding errors (e.g., 100 * 0.3 ≠ 30).
- Fix: Always use integers for amount and handle conversion manually:
```
$money = \Akaunting\Money\Money::USD(100 * 100); // Store as cents
$money->format(2); // Format to 2 decimal places
```
Time Zone and Date Formatting Conflicts
- Issue: If using intl extensions elsewhere, formatting may behave inconsistently.
- Fix: Stick to the package’s built-in formatters and avoid mixing with NumberFormatter.

Case-Sensitive Currency Codes

Issue: USD ≠ usd or UsD.

Fix: Always use uppercase codes:

$money = \Akaunting\Money\Money::USD(100); // Correct
$money = new \Akaunting\Money\Money(100, new \Akaunting\Money\Currency('usd')); // Throws exception

Negative Values

Issue: Negative amounts may not format as expected (e.g., ($100.00) vs -$100.00).

Fix: Customize the prefix or suffix in config/money.php:

'formats' => [
    'USD' => [
        'prefix' => function($amount) {
            return $amount >= 0 ? '$' : '($';
        },
        'suffix' => function($amount) {
            return $amount >= 0 ? '' : ')';
        },
    ],
],

Debugging Tips

Check Config: Dump the config to verify settings:
```
dd(config('money'));
```

Inspect Currency Object:

$money->getCurrency()->getName(); // "US Dollar"
$money->getCurrency()->getSymbol(); // "$"

Enable Logging: Add debug logs for conversion rates:

\Log::debug('Conversion rate for EUR: ' . $money->getCurrency()->getRate());

Extension Points

Custom Formatters Extend the Akaunting\Money\Formatter\FormatterInterface to create custom formatters:

namespace App\Money;

use Akaunting\Money\Formatter\FormatterInterface;

class CustomFormatter implements FormatterInterface {
    public function format($amount, $currency) {
        // Custom logic (e.g., scientific notation for large amounts)
        return number_format($amount, 2, ',', ' ') . ' ' . $currency->getSymbol();
    }
}

'formatters' => [
    'custom' => \App\Money\CustomFormatter::class,
],

Usage:

$money->format('custom');

Dynamic Currency Loading Load currencies dynamically from a database:

$currency = new \Akaunting\Money\Currency(
    $dbCurrencyCode,
    $dbCurrencyName,
    $dbSymbol,

Laravel Money Laravel Package