README

A flexible and easy-to-use Laravel shopping cart package that supports both database and session storage. Perfect for e-commerce applications that need to handle both guest and authenticated user shopping experiences.

Features

Flexible Storage: Database, session, or hybrid storage options
Multi-User Support: Seamlessly handles guest and authenticated users
Easy-to-Use Facade: Simple, intuitive API
Item Management: Add, remove, increase/decrease quantities
Calculations: Automatic totals and item counts
Well Tested: Comprehensive test coverage with Pest
Laravel 12 Ready: Built for the latest Laravel version
Clean Code: Uses Rector and Pint for code quality

Installation

You can install the package via composer:

composer require hnooz/laravel-shopping-cart

Publish and Run Migrations

Publish the migration file and run migrations:

php artisan vendor:publish --tag="laravel-cart-migrations"
php artisan migrate

Publish Configuration (Optional)

If you want to customize the configuration:

php artisan vendor:publish --tag="laravel-cart-config"

Configuration

The package comes with sensible defaults, but you can customize the behavior by publishing the config file:

return [
    /*
    |--------------------------------------------------------------------------
    | Cart Storage Driver
    |--------------------------------------------------------------------------
    |
    | This option controls the default cart storage driver that will be used
    | to store cart items. You may set this to any of the storage options
    | listed below.
    |
    | Supported: "database", "session", "both"
    |
    */
    'driver' => env('CART_DRIVER', 'both'),

    /*
    |--------------------------------------------------------------------------
    | Cart Database Connection
    |--------------------------------------------------------------------------
    |
    | This is the database connection that will be used to store cart items
    | when using the "database" or "both" storage driver.
    |
    */
    'connection' => env('CART_DB_CONNECTION', null),

    /*
    |--------------------------------------------------------------------------
    | Cart Items Table
    |--------------------------------------------------------------------------
    |
    | This is the table that will be used to store cart items when using
    | the "database" or "both" storage driver.
    |
    */
    'table' => 'cart_items',

    /*
    |--------------------------------------------------------------------------
    | Session Key
    |--------------------------------------------------------------------------
    |
    | This is the session key that will be used to store cart items when
    | using the "session" or "both" storage driver.
    |
    */
    'session_key' => 'shopping_cart',
];

Usage

Basic Operations

use Hnooz\LaravelCart\Facades\Cart;

// Add items to cart
Cart::add('product-1', 'iPhone 14', 999.99, 1);
Cart::add('product-2', 'MacBook Pro', 1999.99, 2, ['color' => 'Space Gray']);

// Remove an item
Cart::remove('product-1');

// Increase item quantity
Cart::increase('product-2', 1); // Adds 1 more MacBook Pro

// Decrease item quantity
Cart::decrease('product-2', 1); // Removes 1 MacBook Pro

// Get all cart items
$items = Cart::all();

// Get item count
$count = Cart::count(); // Total quantity of all items

// Get cart total
$total = Cart::total(); // Total price of all items

// Clear entire cart
Cart::clear();

Working with Item Options

You can store additional data with each cart item:

Cart::add('shirt-001', 'Cotton T-Shirt', 29.99, 2, [
    'size' => 'L',
    'color' => 'Blue',
    'customization' => 'Custom text on back'
]);

$items = Cart::all();
foreach ($items as $item) {
    echo $item['name'] . ' - Size: ' . $item['options']['size'];
}

Storage Drivers

Session Storage

Best for simple applications or when you don't need persistent carts:

// In config/cart.php or .env
'driver' => 'session'
// or
CART_DRIVER=session

Database Storage

Best for when you need persistent carts and user account integration:

// In config/cart.php or .env
'driver' => 'database'
// or
CART_DRIVER=database

Hybrid Storage (Recommended)

Uses session for guests and database for authenticated users:

// In config/cart.php or .env
'driver' => 'both'
// or
CART_DRIVER=both

Guest to User Cart Migration

When a guest user logs in, their session cart can be easily migrated:

// In your authentication logic
use Hnooz\LaravelCart\Facades\Cart;

// After user login
if (session()->has('shopping_cart')) {
    // Cart items are automatically available
    // The package handles the transition seamlessly
}

API Reference

`Cart::add(string $id, string $name, float $price, int $quantity = 1, array $options = [])`

Adds an item to the cart. If the item already exists, the quantity will be increased.

Parameters:

$id - Unique identifier for the item
$name - Display name of the item
$price - Price per unit
$quantity - Quantity to add (default: 1)
$options - Additional data array (default: [])

`Cart::remove(string $id)`

Removes an item completely from the cart.

`Cart::increase(string $id, int $quantity = 1)`

Increases the quantity of an existing item.

`Cart::decrease(string $id, int $quantity = 1)`

Decreases the quantity of an existing item. Minimum quantity is 1.

`Cart::clear()`

Removes all items from the cart.

`Cart::all()`

Returns all cart items as an array.

`Cart::count()`

Returns the total quantity of all items in the cart.

`Cart::total()`

Returns the total price of all items in the cart.

Advanced Usage

Using the Contract

You can type-hint the contract in your classes:

use Hnooz\LaravelCart\Contracts\CartInterface;

class CheckoutService
{
    public function __construct(
        protected CartInterface $cart
    ) {}

    public function processOrder()
    {
        $items = $this->cart->all();
        $total = $this->cart->total();
        
        // Process order...
        
        $this->cart->clear();
    }
}

Custom Cart Implementation

You can create your own cart implementation by implementing the CartInterface:

use Hnooz\LaravelCart\Contracts\CartInterface;

class CustomCartManager implements CartInterface
{
    // Implement all required methods...
}

// In a service provider
$this->app->bind(CartInterface::class, CustomCartManager::class);

Testing

The package comes with comprehensive tests. To run the tests:

composer test

Code Quality

The package uses several tools to maintain code quality:

# Run Pint for style fix
composer style-fix

# Run rector for code improvements
composer rector-dry
composer rector-fix

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

License

The MIT License (MIT). Please see License File for more information.

hnooz / laravel-shopping-cart

Maintainers

Details