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:
new Cart($sessionStorage, $events, 'cart', $sessionKey, $config);
After:
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:
php artisan vendor:publish --provider="Wearepixel\Cart\CartServiceProvider" --tag=config
After:
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 viaconfig/cart.php - CartManager: resolves drivers by name, accessible via
app('cart.manager') - First-class objects:
Coupon,TaxRule,ShippingRateabstract base classes - optional, existing rawCartConditionusage continues to work - Cart::fake(): returns a
CartFactorybacked by an in-memoryNullDriverfor 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:
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:
php artisan cart:make:coupon TenPercentOff
php artisan cart:make:tax GstTaxRule
php artisan cart:make:shipping FlatRateShipping
Before:
$condition = new CartCondition([
'name' => 'SAVE10',
'type' => 'coupon',
'target' => 'subtotal',
'value' => '-10%',
]);
Cart::condition($condition);
After:
// 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:
// Mocking the session or binding a fake driver manually
$this->mock(CartDriver::class, function ($mock) {
$mock->shouldReceive(...);
});
After:
$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:
'driver' => 'database', // or 'redis'
For the database driver, publish and run the migration:
php artisan cart:install
php artisan migrate
See the Storage Drivers section of the docs for full configuration options.