mirror of
https://github.com/wearepixel/laravel-cart.git
synced 2026-11-14 13:51:44 +00:00
166 lines
4.6 KiB
Markdown
166 lines
4.6 KiB
Markdown
# Upgrade Guide
|
|
|
|
## v2.x to v3.0
|
|
|
|
### Breaking changes
|
|
|
|
#### Constructor signature
|
|
|
|
`Cart` no longer accepts a raw session/database storage object as its first constructor argument. It now requires a `CartDriver` instance. If you were resolving `Cart` directly (not via the service container), update your instantiation:
|
|
|
|
**Before:**
|
|
|
|
```php
|
|
new Cart($sessionStorage, $events, 'cart', $sessionKey, $config);
|
|
```
|
|
|
|
**After:**
|
|
|
|
```php
|
|
use Wearepixel\Cart\Drivers\SessionDriver;
|
|
|
|
new Cart(new SessionDriver($session, $sessionKey), $events, 'cart', $config);
|
|
```
|
|
|
|
Applications that use the service container (the normal case) are unaffected - `CartServiceProvider` handles this automatically.
|
|
|
|
#### Publish tag renamed
|
|
|
|
The config publish tag changed from `config` to `cart-config` to avoid conflicts with other packages:
|
|
|
|
**Before:**
|
|
|
|
```bash
|
|
php artisan vendor:publish --provider="Wearepixel\Cart\CartServiceProvider" --tag=config
|
|
```
|
|
|
|
**After:**
|
|
|
|
```bash
|
|
php artisan vendor:publish --provider="Wearepixel\Cart\CartServiceProvider" --tag=cart-config
|
|
# or simply:
|
|
php artisan cart:install
|
|
```
|
|
|
|
#### CartSession removed
|
|
|
|
`Wearepixel\Cart\CartSession` has been removed. It is replaced by the driver system. If you extended or referenced `CartSession` directly, switch to the appropriate driver (`SessionDriver`, `DatabaseDriver`, etc.).
|
|
|
|
### Non-breaking additions
|
|
|
|
The following are additive and require no changes to existing code:
|
|
|
|
- **Storage drivers:** `SessionDriver`, `DatabaseDriver`, `RedisDriver`, `NullDriver`, `MultiDriver` - configure via `config/cart.php`
|
|
- **CartManager:** resolves drivers by name, accessible via `app('cart.manager')`
|
|
- **First-class objects:** `Coupon`, `TaxRule`, `ShippingRate` abstract base classes - optional, existing raw `CartCondition` usage continues to work
|
|
- **Cart::fake():** returns a `CartFactory` backed by an in-memory `NullDriver` for testing
|
|
- **Assertion methods:** `Cart::assertContains()`, `assertCount()`, `assertTotal()`, etc.
|
|
- **HasCart trait:** Livewire reactive cart state
|
|
- **ShareCartWithInertia:** static class for Inertia middleware integration
|
|
- **Artisan generators:** `cart:install`, `cart:make:coupon`, `cart:make:tax`, `cart:make:shipping`, `cart:make:driver`, `cart:debug`
|
|
|
|
---
|
|
|
|
### Recommended v3 patterns
|
|
|
|
v3 is fully backwards compatible - your existing code will continue to work unchanged. The following patterns are recommended for new code and worth migrating to when you touch existing cart logic.
|
|
|
|
#### 1. Publish the updated config
|
|
|
|
Run the installer to get the new `driver` key and storage configuration in your `config/cart.php`:
|
|
|
|
```bash
|
|
php artisan cart:install
|
|
```
|
|
|
|
The default driver is `session`, so behaviour is identical to v2 unless you change it.
|
|
|
|
#### 2. Replace raw CartCondition arrays with first-class objects
|
|
|
|
Generate typed classes with Artisan instead of constructing arrays inline:
|
|
|
|
```bash
|
|
php artisan cart:make:coupon TenPercentOff
|
|
php artisan cart:make:tax GstTaxRule
|
|
php artisan cart:make:shipping FlatRateShipping
|
|
```
|
|
|
|
**Before:**
|
|
|
|
```php
|
|
$condition = new CartCondition([
|
|
'name' => 'SAVE10',
|
|
'type' => 'coupon',
|
|
'target' => 'subtotal',
|
|
'value' => '-10%',
|
|
]);
|
|
|
|
Cart::condition($condition);
|
|
```
|
|
|
|
**After:**
|
|
|
|
```php
|
|
// app/Cart/Coupons/TenPercentOff.php
|
|
class TenPercentOff extends Coupon
|
|
{
|
|
protected string $code = 'SAVE10';
|
|
protected string $value = '-10%';
|
|
protected string $target = 'subtotal';
|
|
|
|
public function isValid(): bool
|
|
{
|
|
return true;
|
|
}
|
|
}
|
|
|
|
Cart::coupon(new TenPercentOff);
|
|
Cart::tax(new GstTaxRule);
|
|
Cart::shipping(new FlatRateShipping);
|
|
```
|
|
|
|
The same pattern applies to `TaxRule` (implement `isApplicable()`) and `ShippingRate` (implement `isApplicable()`).
|
|
|
|
#### 3. Use Cart::fake() in tests instead of mocking
|
|
|
|
**Before:**
|
|
|
|
```php
|
|
// Mocking the session or binding a fake driver manually
|
|
$this->mock(CartDriver::class, function ($mock) {
|
|
$mock->shouldReceive(...);
|
|
});
|
|
```
|
|
|
|
**After:**
|
|
|
|
```php
|
|
$factory = app('cart')->fake();
|
|
|
|
$factory->withItems(3)->withCondition(new GstTaxRule);
|
|
|
|
$cart = app('cart');
|
|
$cart->assertCount(3);
|
|
$cart->assertConditionApplied('GST');
|
|
$cart->assertTotal(33.00);
|
|
```
|
|
|
|
`Cart::fake()` swaps the driver to an in-memory `NullDriver` for the duration of the test - no session, database, or Redis needed.
|
|
|
|
#### 4. Switch to a persistent driver (optional)
|
|
|
|
If you want cart state to survive beyond a session, update `config/cart.php`:
|
|
|
|
```php
|
|
'driver' => 'database', // or 'redis'
|
|
```
|
|
|
|
For the database driver, publish and run the migration:
|
|
|
|
```bash
|
|
php artisan cart:install
|
|
php artisan migrate
|
|
```
|
|
|
|
See the [Storage Drivers](README.md#storage-drivers) section of the README for full configuration options.
|