You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Storing Money in the Database](#storing-money-in-the-database)
15
+
-[Usage](#usage)
16
+
-[Casting with a Column as Currency (Recommended)](#casting-with-a-column-as-currency-recommended)
17
+
-[Casting with a Defined Currency](#casting-with-a-defined-currency)
18
+
-[Parsing Values to Money Instances](#parsing-values-to-money-instances)
19
+
-[Validation Rule](#validation-rule)
20
+
-[Testing](#testing)
21
+
-[Changelog](#changelog)
22
+
-[Contributing](#contributing)
23
+
-[Security](#security)
24
+
-[Credits](#credits)
25
+
-[License](#license)
26
+
27
+
## Introduction
28
+
29
+
This package provides a seamless integration of [Brick/Money](https://github.com/brick/money) with Laravel, allowing you to handle monetary values efficiently within your application.
9
30
10
31
## Features
11
32
12
-
- MoneyCast: Cast your model attributes to `Brick\Money\Money`
13
-
- MoneyParse: Parse strings and other types to`Brick\Money\Money`
14
-
- ValidMoney: Money validation rule
33
+
-**MoneyCast**: Cast model attributes to `Brick\Money\Money`.
34
+
-**MoneyParse**: Convert various data types into`Brick\Money\Money` instances.
To customize the default settings, publish the configuration file:
25
48
26
49
```bash
27
50
php artisan vendor:publish --tag="money-config"
28
51
```
29
52
30
-
This is the content of the published config file:
53
+
The default configuration file (`config/money.php`) contains:
31
54
32
55
```php
33
56
return [
34
57
'default_currency' => 'USD',
35
58
];
36
59
```
37
60
61
+
## Storing Money in the Database
62
+
63
+
The recommended way to store money in the database is to use a `bigInteger` column for the amount and a `string` column for the currency. This ensures precision and avoids floating-point errors. Store the amount in the smallest unit of currency (e.g., cents for USD, centimes for EUR). This approach prevents rounding issues and maintains accuracy in calculations.
64
+
65
+
Example migration:
66
+
67
+
```php
68
+
Schema::create('invoices', function (Blueprint $table) {
69
+
$table->id();
70
+
$table->bigInteger('amount'); // Store in cents
71
+
$table->string('currency', 3); // ISO currency code
72
+
$table->timestamps();
73
+
});
74
+
```
75
+
38
76
## Usage
39
77
40
-
### Casting Using a Column as Currency (Recommended)
78
+
### Casting with a Column as Currency (Recommended)
41
79
42
-
If you store the currency in a table column alongside the amount value, you can specify the column name like this:
80
+
If your database stores both the amount and the currency in separate columns, you can specify the currency column like this:
43
81
44
82
```php
45
83
use Elegantly\Money\MoneyCast;
46
84
47
85
/**
48
-
* @property ?Money $price
86
+
* @property ?Money $amount
49
87
* @property ?string $currency
50
88
**/
51
89
class Invoice extends Model {
52
-
53
-
protected $casts = [
54
-
'price' => MoneyCast::class . ':currency'
55
-
];
56
-
90
+
/**
91
+
* @return array<string,string>
92
+
*/
93
+
protected function casts(): array
94
+
{
95
+
return [
96
+
'amount' => MoneyCast::class . ':currency'
97
+
];
98
+
}
57
99
}
58
100
```
59
101
60
-
### Casting Using a Defined Currency
102
+
### Casting with a Defined Currency
61
103
62
-
You can cast your money to a specific currency using the currency code instead of the column name.
104
+
You can also define a specific currency for money casting instead of referencing a column:
63
105
64
106
```php
65
107
use Elegantly\Money\MoneyCast;
@@ -69,37 +111,37 @@ use Elegantly\Money\MoneyCast;
69
111
* @property ?Money $cost
70
112
**/
71
113
class Invoice extends Model {
72
-
73
-
protected $casts = [
74
-
'cost' => MoneyCast::class . ':EUR',
75
-
'price' => MoneyCast::class . ':USD'
76
-
];
77
-
114
+
/**
115
+
* @return array<string,string>
116
+
*/
117
+
protected function casts(): array
118
+
{
119
+
return [
120
+
'cost' => MoneyCast::class . ':EUR',
121
+
'price' => MoneyCast::class . ':USD'
122
+
];
123
+
}
78
124
}
79
125
```
80
126
81
-
### Parsing a Value to a Money Instance
82
-
83
-
You can parse any string/int/float to a money instance using `MoneyParser`.
127
+
### Parsing Values to Money Instances
84
128
85
-
Here are some examples of the expected behavior:
129
+
Convert strings, integers, or floats into `Brick\Money\Money` instances using `MoneyParser`:
86
130
87
131
```php
88
132
use Elegantly\Money\MoneyParser;
89
133
90
134
MoneyParser::parse(null, 'EUR'); // null
91
-
92
135
MoneyParser::parse(110, 'EUR'); // 110.00€
93
136
MoneyParser::parse(100.10, 'EUR'); // 100.10€
94
-
95
137
MoneyParser::parse('', 'EUR'); // null
96
138
MoneyParser::parse('1', 'EUR'); // 1.00€
97
139
MoneyParser::parse('100.10', 'EUR'); // 100.10€
98
140
```
99
141
100
142
### Validation Rule
101
143
102
-
Using `ValidMoney`within Livewire:
144
+
#### Using `ValidMoney`in Livewire
103
145
104
146
```php
105
147
namespace App\Livewire;
@@ -116,7 +158,7 @@ class CustomComponent extends Component
116
158
}
117
159
```
118
160
119
-
Using `ValidMoney`within a form request:
161
+
#### Using `ValidMoney`in Form Requests
120
162
121
163
```php
122
164
namespace App\Http\Requests;
@@ -143,21 +185,23 @@ class CustomFormRequest extends FormRequest
143
185
144
186
## Testing
145
187
188
+
Run the package tests with:
189
+
146
190
```bash
147
191
composer test
148
192
```
149
193
150
194
## Changelog
151
195
152
-
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
196
+
Refer to the [CHANGELOG](CHANGELOG.md) for details on recent updates and modifications.
153
197
154
198
## Contributing
155
199
156
-
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
200
+
Contributions are welcome! See [CONTRIBUTING](CONTRIBUTING.md) for guidelines.
157
201
158
-
## Security Vulnerabilities
202
+
## Security
159
203
160
-
Please review [our security policy](../../security/policy)on how to report security vulnerabilities.
204
+
If you discover any security vulnerabilities, please review our [security policy](../../security/policy) to report them responsibly.
161
205
162
206
## Credits
163
207
@@ -166,4 +210,4 @@ Please review [our security policy](../../security/policy) on how to report secu
166
210
167
211
## License
168
212
169
-
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
213
+
This package is released under the MIT License. See [LICENSE.md](LICENSE.md) for details.
0 commit comments