jamesdb/cart

A framework agnostic shopping cart package.

Shopping Cart

, _(*1)

A framework agnostic shopping cart package., _(*2)

Install

Via Composer, _(*3)

$ composer require jamesdb/cart

Notes

Money Value Objects

This package uses moneyphp/money (an implementation of Martin Fowler's money pattern). Floats are avoided due to them being ill-suited for monetary values. More information can be found in the links below:, _(*4)

• http://martinfowler.com/eaaCatalog/money.html
• http://culttt.com/2014/05/28/handle-money-currency-web-applications/

Due to this when dealing with monetary values you will need to represent them as integers instead of floats., _(*5)

An example of this can be found below., _(*6)

use jamesdb\Cart\CartItem;

$item = new CartItem([
    ...
    'price' => 1099, // Instead of £10.99 or $10.99 etc.
    ...
]);

Setting Up

To setup a cart instance you need to pass an identifier and storage implementation to the cart constructor., _(*7)

The currency defaults to 'GBP', if you want to change this you will need to pass your currency of choice into the setCurrency method as shown below., _(*8)

A custom formatter callback can be setup via setFormatterCallback, see moneyphp formatters for more information., _(*9)

use jamesdb\Cart\Cart;
use jamesdb\Cart\Storage\NativeSessionDriver;
use Money\Currencies\ISOCurrencies;
use Money\Currency;
use Money\Formatter\DecimalMoneyFormatter;

$cart = new Cart('cart', new NativeSessionDriver);
$cart->setCurrency(new Currency('GBP'));

$cart->setFormatterCallback(function ($money) {
    $currencies = new ISOCurrencies();
    $moneyFormatter = new DecimalMoneyFormatter($currencies);

    return $moneyFormatter->format($money); // outputs in decimal format.
});

Any storage implementation can be used as long as it implements the jamesdb\Cart\Storage\StorageInterface., _(*10)

Usage

Adding Items

CartItem implements ArrayAccess and uses the __set and __get magic methods to assign and access properties., _(*11)

Added items will return a rowid., _(*12)

use jamesdb\Cart\Cart;
use jamesdb\Cart\CartItem;

$cart = new Cart(...);

/**
 * Assign properties via __set.
 */
$item1 = new CartItem();
$item1->id = 2731;
$item1->name = 'Product';
$item1->price = 1099;
$item1->quantity = 1;

$cart->add($item1);

/**
 * ----------
 */

/**
 * Assign properties via ArrayAccess.
 */
$item2 = new CartItem([
    'id' => 2731,
    'name' => 'Product',
    'price' => 1099,
    'quantity' => 1
]);

$cart->add($item2)

Updating Items

You can either use the cart update method or access the properties directly on the CartItem., _(*13)

Attempting to update an item that doesn't exist in the cart will result in a CartItemUpdateException being thrown., _(*14)

$cart->update('rowid', ['name' => 'Renamed Product']);

/**
 * ----------
 */

$cartItem = $cart->find('rowid');
$cartItem->name = 'Renamed Product';

Removing Items

Attempting to remove an item that doesn't exist in the cart will result in a CartItemRemoveException being thrown., _(*15)

$cart->remove('rowid');

Clear the Cart

$cart->clear();

Accessing a specific Item

To access a specific item use the cart getItem method., _(*16)

If an item can't be found the method will return null., _(*17)

$cart->getItem('rowid');

Accessing all Items

$cart->getItems();

Filtering Items

The cart can be filtered by any supplied key and value with the filter method., _(*18)

// Return all items with a quantity of 2.
$cart->filter('quantity', 2);

// Return all items with a price of 1000.
$cart->filter('price', 1000);

Accessing Item counts

The getTotalUniqueItems method will return an item count excluding quantities., _(*19)

$cart->getTotalUniqueItems();

The getTotalItems method will return an item count including quantities., _(*20)

$cart->getTotalItems();

A convenience method isEmpty is built into the cart, this proxies through to the getTotalUniqueItems with a === 0 check., _(*21)

$cart->isEmpty();

Accessing prices

Get the overall price including tax with the getTotalPrice method., _(*22)

$cart->getTotalPrice();

Occasionally dealing with tax isn't required, in this case you can use the getTotalPriceExcludingTax method., _(*23)

$cart->getTotalPriceExcludingTax();

Get the total cart tax., _(*24)

$cart->getTax();

Events

League\Event is built into the cart and provides a number of events that can be emitted, this allows you to easily hook into certain key points during the carts lifecycle., _(*25)

You can subscribe to these events by attaching listeners to the cart via addEventListener., _(*26)

All events have built in methods to retrieve the item triggering the event and the cart itself., _(*27)

$cart->addEventListener('cart.add', function ($event) {
    $item = $event->getItem();
    $cart = $event->getCart();

    ...
});

cart.add

$cart->addEventListener('cart.add', function ($event) {});

cart.update

$cart->addEventListener('cart.update', function ($event) {});

cart.remove

$cart->addEventListener('cart.remove', function ($event) {});