README

FlexiCart

A flexible shopping cart package for Laravel with support for session or database storage, conditional pricing, cart merging, rules engine, and custom product attributes.

Table of Contents

• Features
• Installation
• Basic Usage
  • Adding Items
  • Updating Items
  • Removing Items
  • Cart Totals
• Conditions
  • Understanding Conditions
  • Adding Conditions
  • Removing Conditions
  • Non-Taxable Items
  • Tax Conditions and the taxable Flag
• Documentation
• Testing
• Troubleshooting
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

Features

• Flexible Storage: Use session storage (default) or database storage
• Cart Item Conditions: Apply discounts, fees, or any adjustments to items
  • Percentage-based adjustments (e.g., 10% discount)
  • Fixed-amount adjustments (e.g., $5 off, $2 add-on fee)
  • Stack multiple conditions on the same item
• Rules Engine: Advanced promotional rules with cart context access
  • Buy X Get Y deals
  • Threshold-based discounts
  • Tiered volume discounts
  • Quantity-based rules
• Cart Merging: Flexible strategies for merging carts (guest to user, wishlist to cart)
• Event System: Hook into cart lifecycle for analytics, inventory, and integrations
• Custom Product Attributes: Store any item-specific attributes (color, size, etc.)
• Global Cart Conditions: Apply conditions to the cart subtotal or only to taxable items
• Precise Price Handling: Uses Brick/Money for accurate currency calculations
• Taxable Item Support: Mark specific items as taxable or non-taxable
• Easy Integration: Simple API with Laravel Facade

Installation

Requirements

• PHP 8.3 or higher
• Laravel 11.0 or higher
• Brick/Money package (automatically installed)

Install the Package

composer require daikazu/flexicart

Publish Configuration

php artisan vendor:publish --tag="flexicart-config"

Database Storage (Optional)

php artisan vendor:publish --tag="flexicart-migrations"
php artisan migrate

Then update your .env file:

CART_STORAGE=database

Basic Usage

Adding Items to the Cart

use Daikazu\Flexicart\Facades\Cart;

// Add item as array
Cart::addItem([
    'id' => 1,
    'name' => 'Product Name',
    'price' => 29.99,
    'quantity' => 2,
    'attributes' => [
        'color' => 'red',
        'size' => 'large'
    ]
]);

// Add multiple items at once
Cart::addItem([
    [
        'id' => 2,
        'name' => 'Another Product',
        'price' => 15.50,
        'quantity' => 1
    ],
    [
        'id' => 3,
        'name' => 'Third Product',
        'price' => 45.00,
        'quantity' => 3
    ]
]);

Updating Items in the Cart

// Update quantity
Cart::updateItem('item_id', ['quantity' => 5]);

// Update attributes
Cart::updateItem('item_id', [
    'attributes' => [
        'color' => 'blue',
        'size' => 'medium'
    ]
]);

// Update multiple properties
Cart::updateItem('item_id', [
    'quantity' => 3,
    'price' => 25.99,
    'attributes' => ['color' => 'green']
]);

Removing Items from the Cart

// Remove a specific item
Cart::removeItem('item_id');

// Clear all items from the cart
Cart::clear();

// Clear all items and conditions from cart
Cart::reset();

Getting Cart Content and Calculations

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

// Get a specific item
$item = Cart::item('item_id');

// Get cart counts
$totalItems = Cart::count(); // Total quantity of all items
$uniqueItems = Cart::uniqueCount(); // Number of unique items

// Check if cart is empty
$isEmpty = Cart::isEmpty();

// Get cart totals
$subtotal = Cart::subtotal(); // Subtotal before conditions
$total = Cart::total(); // Final total after all conditions
$taxableSubtotal = Cart::getTaxableSubtotal(); // Subtotal of taxable items only

Conditions

Understanding Conditions

Conditions are adjustments that can be applied to cart items or the entire cart:

• Percentage Conditions: Apply percentage-based adjustments (e.g., 10% discount)
• Fixed Conditions: Apply fixed-amount adjustments (e.g., $5 off)
• Tax Conditions: Special conditions for tax calculations

Conditions can target:

• Individual Items: Applied to specific cart items
• Cart Subtotal: Applied to the entire cart subtotal
• Taxable Items: Applied only to items marked as taxable

Adding Conditions

use Daikazu\Flexicart\Conditions\Types\PercentageCondition;
use Daikazu\Flexicart\Conditions\Types\FixedCondition;
use Daikazu\Flexicart\Enums\ConditionTarget;

// Add a 10% discount to the cart
$discount = new PercentageCondition(
    name: '10% Off Sale',
    value: -10, // Negative for discount
    target: ConditionTarget::SUBTOTAL
);
Cart::addCondition($discount);

// Add a $5 shipping fee
$shipping = new FixedCondition(
    name: 'Shipping Fee',
    value: 5.00,
    target: ConditionTarget::SUBTOTAL
);
Cart::addCondition($shipping);

// Add condition to a specific item
$itemDiscount = new PercentageCondition(
    name: 'Item Discount',
    value: -20,
    target: ConditionTarget::ITEM
);
Cart::addItemCondition('item_id', $itemDiscount);

Removing Conditions

// Remove a specific condition from the cart
Cart::removeCondition('10% Off Sale');

// Remove a condition from a specific item
Cart::removeItemCondition('item_id', 'Item Discount');

// Clear all cart conditions
Cart::clearConditions();

Marking Items as Non-Taxable

// Add non-taxable item
Cart::addItem([
    'id' => 4,
    'name' => 'Non-taxable Service',
    'price' => 100.00,
    'quantity' => 1,
    'taxable' => false
]);

// Update existing item to be non-taxable
Cart::updateItem('item_id', ['taxable' => false]);

Tax Conditions and the taxable Flag

Use PercentageTaxCondition or FixedTaxCondition to apply tax. Tax is calculated on a tax base composed of:

1. The subtotal of items whose taxable attribute is true, plus
2. Any conditions (cart-level or item-level) whose taxable flag is true.

Conditions default to taxable: false, which means they do not affect the tax base. Set taxable: true on a condition when its amount should be taxed (e.g. a taxable shipping fee) or when a discount should reduce the tax base.

use Daikazu\Flexicart\Conditions\Types\FixedCondition;
use Daikazu\Flexicart\Conditions\Types\PercentageCondition;
use Daikazu\Flexicart\Conditions\Types\PercentageTaxCondition;

// Non-taxable shipping — added to total, NOT added to the tax base.
$shipping = new FixedCondition(
    name: 'Shipping',
    value: 10.00,
    taxable: false // default
);

// Taxable shipping — added to total AND added to the tax base.
$taxableShipping = new FixedCondition(
    name: 'Shipping',
    value: 10.00,
    taxable: true
);

// Discount that does NOT reduce the tax base (tax is calculated on the pre-discount amount).
$discount = new PercentageCondition(
    name: 'Discount',
    value: -10,
    taxable: false // default
);

// Discount that DOES reduce the tax base by its full amount (tax is calculated on the post-discount amount).
$discountReducingTax = new PercentageCondition(
    name: 'Discount',
    value: -10,
    taxable: true
);

// Apply sales tax. The tax is computed against the tax base described above.
$tax = new PercentageTaxCondition(name: 'Sales Tax', value: 8.25);

Cart::addCondition($shipping);
Cart::addCondition($discount);
Cart::addCondition($tax);

Summary

The same rule applies to item-level conditions: an item condition with taxable: false is included in the item's subtotal but excluded from the tax base.

Documentation

For detailed documentation on specific features, see the following guides:

Testing

composer test

Troubleshooting

Common Issues

Cart data not persisting between requests

• Ensure sessions are properly configured in your Laravel application
• If using database storage, verify migrations have been run
• Check that the CART_STORAGE environment variable is set correctly

Price calculation errors

• Verify that all price values are numeric
• Ensure currency codes are valid ISO codes

Condition not applying correctly

• Verify condition targets are set appropriately
• Check condition order values if multiple conditions exist
• Ensure condition values are properly signed (negative for discounts)

Memory issues with large carts

• Consider implementing cart item limits
• Don't use session storage due to cookie size limits
• Use database storage for better memory management
• Implement cart cleanup for old/abandoned carts

Changelog

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

Future Roadmap

• API endpoints

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Mike Wall
• All Contributors

License

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