readme.md 6.33 KB
Newer Older
Thorsten Buss's avatar
Thorsten Buss committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
# PHP MoneyDataType - use Money as that what it is - an amount with currency

A simple Money Datatype Implementation

## Main Features

* Contains amount AND currency as package
* calculate with the amount
* format with the currency
* parse string to money datatype


##INSTALLATION

Install the package through [Composer](http://getcomposer.org/). Edit your project's `composer.json` file by adding:

	"require": {
		"bussnet/money-datatype": "*"
	}

	then run:  $ composer update

or execute

    composer require "bussnet/money-datatype"

## Usage

### Manual Currency Attributes 
```php

	$a = [
		'code' => 'EUR',
		'iso' => 978,
		'name' => 'Euro',
		'symbol_left' => '',
		'symbol_right' => '€',
		'decimal_place' => 2,
		'decimal_mark' => ',',
		'thousands_separator' => '.',
		'unit_factor' => 100
	];
	$c = new \Bnet\Money\Currency('EUR', $a);

```

### Currency with ArrayRepository 
```php

	$repository = new ArrayRepository([
		'EUR' => [
			'code' => 'EUR',
			'iso' => 978,
			'name' => 'Euro',
			'symbol_left' => '',
			'symbol_right' => '€',
			'decimal_place' => 2,
			'decimal_mark' => ',',
			'thousands_separator' => '.',
			'unit_factor' => 100
		]
	]);
	\Bnet\Money\Currency::registerCurrencyRepository($repository);

	$c = new \Bnet\Money\Currency('EUR');

```

### Currency with CallbackRepository 
```php

	$repository = new \Bnet\Money\Repositories\CallbackRepository(function($code) {
		// request the data from Database and return it 
	});
	\Bnet\Money\Currency::registerCurrencyRepository($repository);

	$c = new \Bnet\Money\Currency('EUR');

```

81
### Use the Money Object 
Thorsten Buss's avatar
Thorsten Buss committed
82 83 84 85 86 87 88 89 90 91 92 93
```php

	// assign own currency
	$m = new Money(123456, 'EUR');
	$m = new Money(123456, new Currency('EUR'));
	
	// use systemwide default currency
	$m = new Money(123456);

	// int 123456
	$m->amount();
	
94
	// string "1234.56"
Thorsten Buss's avatar
Thorsten Buss committed
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
	$m->normalize();
	
	// 1234,56€
	$m->format();

	// 1.234,56€ (with thousand mark)
	$m->format(true);
	
	// 1.234,56 EUR (with thousand mark ans code instead of sign)
	$m->format(true, true);
	
	// EUR 1.234,56 (with thousand mark ans code instead of sign swap before/after part)
	$m->format(true, true, true);
	
	// 1234,56€ with html spans arround the parts
	$m->html(/* use the same params as format() above */);
111 112 113 114 115 116 117 118 119 120 121 122 123 124

	// return [
    // 	  'amount' => $this->amount(),
    // 	  'number' => $this->normalize(),
    // 	  'format' => $this->format(),
    // 	  'currency' => $this->currency->code,
    // ];
    $m->toArray();
	
	// toArray() as JsonString
	$m->toJson();
		
	// alias for format()
	$m->render();
Thorsten Buss's avatar
Thorsten Buss committed
125 126 127 128 129 130 131 132
	
	// parse Moneystrings -> 123456 cents
	$m = Money::parse('1.234,56');
	// +/- sign before is allowed, currency sign is not allowed
	// the first ./, is interpreted as thousand mark, the second as decimal makr - more than two are not allowed

```

133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
### Calucations/Checks with the Money Object 
```php

	// bool - same currency
	$m->isSameCurrency(Money $otherMoney);
	
	// 0=equal, 1=$m>$o, -1=$m<$o
	$m->compare(Money $o);

	// no explanation needed
	$m->equals(Money $other);
	$m->greaterThan(Money $o);
	$m->greaterThanOrEqual(Money $o);
	$m->lessThan(Money $o);
	$m->lessThanOrEqual(Money $o);
	$m->isZero();
	$m->isPositive();
	$m->isNegative();
	
	// ALL MATH OPERATIONS ARE ASSERTING THE SAME CURRENCY !!!
	
	// add amount and return new obj
	$m->add(Money $o);
	
	// substruct amount and return new obj
	$m->subtract(Money $o);
	
	// multiply amount with multiplier and return new obj
	$m->multiply($multiplier);
	
	// divide amount by divisor and return new obj
	$m->divide($divisor, $roundingMode = PHP_ROUND_HALF_UP);
	
	// allocate the amount in count($ratios) parts with 
	// the weight of the valiue of $ratios and return Money[]
	$m->allocate(array $ratios);
		
	// has this MoneyObj TaxCalculation (TaxedMoney)
	$m->hasTax();
	
```


### Use the TaxedMoney Object
 
The **TaxedMoney** Class contains a amount (gross OR net) and a tax percentage.
On creation you define if the given amount is net or gross and if the default return value
(for amount() and calucations) is net or gross.

There are MoneyGross and MoneyNet as simpler representations for a TaxedMoney Object
with the static methods ::fromGross() and ::fromNet().

Examples:
```php

	use Bnet\Money\MoneyNet;
	use Bnet\Money\MoneyGross;
	
	// 10EUR is the Net and 19% Tax
	$m = MoneyGross::fromNet(1000, 19, 'EUR');
	// return the net: 1000 -> 10EUR
	$m->amountWithoutTax();

	// both return the gross: 1190 -> 11,90EUR
	$m->amount();
	$m->amountWithTax();

	// all calucaltions with this object are with the **gross**,
	// cause this is the default amount
	// so you can replace any Money Obj ex.: in a Cart, with a TaxedMoneyObj
	// and check with the hasTax() method if you can show the Net/Gross

```
Thorsten Buss's avatar
Thorsten Buss committed
206

Thorsten Buss's avatar
Thorsten Buss committed
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
### Use the CurrencyUpdater
 
Download and parse a CurrencyFile and save it with a Closure

Examples:
```php

		$updater = new \Bnet\Money\Updater\CurrencyUpdater();

		$updater->update_currency_table(function($item) use($db) {
			$db->save($item);
		});

```

Thorsten Buss's avatar
Thorsten Buss committed
222 223
## Changelog

224 225
**0.1.7
- FIX: make $tax from TaxedMoney public to access the tax 
226 227
**0.1.5
- FIX: calculation with TaxedMoney are now correct 
Thorsten Buss's avatar
Thorsten Buss committed
228 229
**0.1.4
- add CurrencyUpdater to download and parse a file and save the data with a Closure 
230 231 232 233 234 235 236 237 238
**0.1.3
- add TaxedMoney for use MoneyObject with Tax 
**0.1.2
- add some math and compare methods to Money and Currency
- add __toString, toArray, toJson methods
- add static Calling of Currency
**0.1.1
- add default currency repository for easier usage in small environments
**0.1.0
Thorsten Buss's avatar
Thorsten Buss committed
239 240 241 242 243 244 245 246 247
- create the basic functionality, prepared with Array and Callback CurrencyRepository

## License

The MoneyDatatype Package is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT)

### Disclaimer

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR, OR ANY OF THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.