Laravel Money Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require cknow/laravel-money
   

   Run php artisan vendor:publish --provider="Cknow\Money\MoneyServiceProvider" to publish the default config.

2. First Use Case: Convert raw amounts to formatted currency strings:

   use Cknow\Money\Money;
   
   // Basic usage
   echo Money::USD(500); // Outputs "$5.00"
   
   // Force decimals (e.g., for accounting)
   echo Money::USD(500, true); // Outputs "$500.00"
   

3. Key Classes:

   • Money: Facade for currency operations.
   • Money\Money: Core class for creating and manipulating money objects.
   • Money\Currency: Handles currency-specific logic.

Where to Look First

• Facade: Money facade in Cknow\Money\Money for quick operations.
• Config: config/money.php for currency settings (e.g., default locale, precision).
• Testing: tests/ directory for usage examples and edge cases.

Implementation Patterns

Core Workflows

1. Creating Money Objects:

   // Static creation
   $amount = Money::USD(1000); // Creates a Money object for $10.00
   
   // Dynamic creation
   $money = new \Cknow\Money\Money(1000, 'USD');
   

2. Currency Conversion:

   $eur = Money::EUR(1000); // €10.00
   $usd = $eur->convert('USD'); // Converts to $11.00 (approx)
   

3. Arithmetic Operations:

   $total = Money::USD(500)->add(Money::USD(300)); // $8.00
   $discount = Money::USD(1000)->subtract(Money::USD(200)); // $8.00
   

4. Formatting:

   // Default formatting
   echo Money::USD(1234.56)->format(); // "$1,234.56"
   
   // Custom formatting (via config)
   echo Money::USD(1234.56)->format('en_US', '€#,##0.00'); // "€1,234.56"
   

5. Database Storage: Use the Money type in Eloquent models:

   use Cknow\Money\Money;
   
   class Order extends Model {
       protected $casts = [
           'amount' => Money::class,
       ];
   }
   

Integration Tips

• Validation: Use the money rule in Laravel’s validator:

  $request->validate([
      'price' => 'required|money:USD',
  ]);
  

• API Responses: Format money in API responses:

  return response()->json(['total' => Money::USD(1000)->format()]);
  

• Middleware: Add currency-specific logic (e.g., enforce USD for admin users):

  public function handle($request, Closure $next) {
      if ($request->user()->isAdmin()) {
          $request->merge(['currency' => 'USD']);
      }
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Precision Handling:

   • MoneyPHP uses integers for cents (e.g., 500 = $5.00). Avoid floating-point arithmetic.
   • Fix: Use Money::USD(500)->divide(2) instead of Money::USD(500) / 2.

2. Currency Conversion Rates:

   • The package uses MoneyPHP’s default rates. For production, override rates in config/money.php:

     'rates' => [
         'USD' => ['EUR' => 0.85, 'GBP' => 0.75],
     ],
     

3. Locale Conflicts:

   • Formatting relies on PHP’s Intl extension. If format() fails, ensure:
     • The locale exists (e.g., en_US).
     • Intl is installed (pecl install intl).
     • Fallback: Use format('en_US', 'custom_pattern') to bypass locale issues.

4. Database Migrations:

   • Store money as integers (e.g., amount_in_cents). Example migration:

     $table->unsignedBigInteger('amount')->comment('Amount in cents');
     

5. Time Zones and Rates:

   • Currency conversion rates are static. For dynamic rates (e.g., forex APIs), extend the Money class or use a service layer.

Debugging

• Dump Money Objects:

  dd(Money::USD(1000)->getAmount(), Money::USD(1000)->getCurrency());
  

• Check Config:

  php artisan config:clear
  

  Then verify config/money.php settings.

Extension Points

1. Custom Formatters: Override the format() method in a service class:

   class CustomMoneyFormatter {
       public function format(Money $money, string $locale = null, string $pattern = null) {
           // Custom logic (e.g., add tax symbols)
           return $money->format($locale, $pattern) . ' (incl. tax)';
       }
   }
   

2. Add New Currencies: Extend the Currency class or use MoneyPHP’s Currency directly:

   $customCurrency = new \Money\Currency('XBT'); // Bitcoin
   $amount = new \Money\Money(1000, $customCurrency);
   

3. Event Listeners: Trigger events for money operations (e.g., money.converted):

   // In EventServiceProvider
   protected $listen = [
       'money.converted' => [YourListener::class],
   ];
   

4. Testing: Mock the Money facade in tests:

   Money::shouldReceive('USD')->andReturn(Money::new(1000, 'USD'));
   

Pro Tips

• Use Traits for Reusability: Create a trait for money-related methods in models:

  trait HandlesMoney {
      public function getFormattedPrice() {
          return Money::USD($this->price_in_cents)->format();
      }
  }
  

• Leverage Collections: Apply money operations to collections:

  $totals = $orders->map->amount->sum(); // Sums all Money objects
  

• Performance: Cache conversion rates if using dynamic sources (e.g., Redis):

  $rate = Cache::remember("currency_rate_{$from}_{$to}", now()->addHours(1), function() use ($from, $to) {
      return Money::getRate($from, $to);
  });