/ 
Handel-0.24
River stage one • 2 direct dependents • 2 total dependents
/ Handel::Cart

NAME

Handel::Cart - Module for maintaining shopping cart contents

SYNOPSIS

use Handel::Cart;

my $cart = Handel::Cart->new({
    shopper => 'D597DEED-5B9F-11D1-8DD2-00AA004ABD5E'
});

$cart->add({
    sku      => 'SKU1234',
    quantity => 1,
    price    => 1.25
});

my $iterator = $cart->items;
while (my $item = $iterator->next) {
    print $item->sku;
    print $item->price;
    print $item->total;
};
$item->subtotal;

DESCRIPTION

Handel::Cart is quick and dirty component for maintaining simple shopping cart data.

While Handel::Cart subclasses Class::DBI, it is strongly recommended that you not use its methods unless it's absolutely necessary. Stick to the documented methods here and you'll be safe should I decide to implement some other data access mechanism. :-)

CONSTRUCTOR

There are two ways to create a new cart object. You can either pass a hashref into new containing all the required values needed to create a new shopping cart record or pass a hashref into load containing the search criteria to use to load an existing shopping cart.

Handel::Cart->new(\%data)
my $cart = Handel::Cart->new({
    shopper => '10020400-E260-11CF-AE68-00AA004A34D5',
    name    => 'My Shopping Cart'
});
Handel::Cart->load([\%filter, $wantiterator])
my $cart = Handel::Cart->load({
    id => 'D597DEED-5B9F-11D1-8DD2-00AA004ABD5E'
});

You can also omit \%filter to load all available carts.

my @carts = Handel::Cart->load();

In scalar context load returns a Handel::Cart object if there is a single result, or a Handel::Iterator object if there are multiple results. You can force load to always return an iterator even if only one cart exists by setting the $wantiterator parameter to RETURNAS_ITERATOR.

my $iterator = Handel::Cart->load(undef, RETURNAS_ITERATOR);
while (my $item = $iterator->next) {
    print $item->sku;
};

See Handel::Contstants for the available RETURNAS options.

A Handel::Exception::Argument exception is thrown if the first parameter is not a hashref.

METHODS

item_class($classname)

Sets the name of the class to be used when returning or creating cart items. While you can set this directly in your application, it's best to set it in a custom subclass of Handel::Cart.

package CustomCart;
use strict;
use warnings;
use base 'Handel::Cart';

__PACKAGE__->item_class('CustomCart::CustomItem';

1;

Adding Cart Items

You can add items to the shopping cart by supplying a hashref containing the required name/values or by passing in a newly create Handel::Cart::Item object. If successful, add will return a Handel::Cart::Item object reference.

Yes, I know. Why a hashref and not just a hash? So I can add new params later if need be. Oh yeah, and "Because I Can". :-P

$cart->add(\%data)
my $item = $cart->add({
    shopper  => '10020400-E260-11CF-AE68-00AA004A34D5',
    sku      => 'SKU1234',
    quantity => 1,
    price    => 1.25
});
$cart->add($object)
my $item = Handel::Cart::Item->new({
    sku      => 'SKU1234',
    quantity => 1,
    price    => 1.25
});
...
$cart->add($item);

A Handel::Exception::Argument exception is thrown if the first parameter isn't a hashref or a Handel::Cart::Item object.

Fetching Cart Items

You can retrieve all or some of the items contained in the cart via the items method. In a scalar context, items returns an iterator object which can be used to cycle through items one at a time. In list context, it will return an array containing all items.

$cart->items()
my $iterator = $cart->items;
while (my $item = $iterator->next) {
    print $item->sku;
};

my @items = $cart->items;
...
dosomething(\@items);
$cart->items(\%filter [, $wantiterator])

When filtering the items in the shopping cart in scalar context, a Handel::Cart::Item object will be returned if there is only one result. If there are multiple results, a Handel::Iterator object will be returned instead. You can force items to always return a Handel::Iterator object even if only one item exists by setting the $wantiterator parameter to RETURNAS_ITERATOR.

my $item = $cart->items({sku => 'SKU1234'}, RETURNAS_ITERATOR);
if ($item->isa('Handel::Cart::Item)) {
    print $item->sku;
} else {
    while ($item->next) {
        print $_->sku;
    };
};

See the RETURNAS constants in Handel::Constants for other options.

In list context, filtered items return an array of items just as when items is called without a filter specified.

my @items - $cart->items((sku -> 'SKU1%'});

A Handel::Exception::Argument exception is thrown if parameter one isn't a hashref or undef.

Removing Cart Items

$cart->clear()

This method removes all items from the current cart object.

$cart->clear;
$cart->delete(\%filter)

This method deletes the cart item(s) matching the supplied filter values and returns the number of items deleted.

if ( $cart->delete({id => '8D4B0BE1-C02E-11D2-A33D-00A0C94B8D0E'}) ) {
    print 'Item deleted';
};

Removing the Entire Cart

$cart->destroy(\%filter)
Handel::Cart->destroy(\%filter)

When called used as an instance method, this will delete all items from the current cart instance and delete the cart container. filter will be ignored.

When called as a package method, this will delete all carts matching filter. A Handel::Exception::Argument exception will be thrown is filter is not a HASH reference.

Saving Your Cart

By default every shopping cart created is considered temporary (CART_TYPE_TEMP) and could be deleted by cleanup processes at any time after the defined inactivity period. This could also be considered characteristic of whether the shopper id is from a temporary part of where it's used, or whether it is generated and stored within a customer profile assigned during authentication.

By saving your shopping cart, you are marking it as CART_TYPE_SAVED and it should be left alone by any cleanup processes and available to that shopper at any time.

For all intents and purposes, a saved cart is a wishlist. At some point in the future they may be treated differently.

$cart->save()

Restoring A Previously Saved Cart

There are two basic ways to restore a previously saved shopping cart into the current shopping cart object. You may either pass in a hashref containing the search criteria of the shopping cart(s) to restore or you can pass in an existing Handel::Cart object.

$cart->restore(\%search, [$mode])
$cart->restore($object, [$mode])

For either method, you may also specify the mode in which the cart should be restored. $mode can be one of the following:

CART_MODE_REPLACE

All items in the current cart will be deleted before the saved cart is restored into it. This is the default if no mode is specified.

CART_MODE_MERGE

If an item with the same SKU exists in both the current cart and the saved cart, the quantity of each will be added together and applied to the same sku in the current cart. Any price differences are ignored and we assume that the price in the current cart is more up to date.

CART_MODE_APPEND

All items in the saved cart will be appended to the list of items in the current cart. No effort will be made to merge items with the same SKU and duplicates will be ignored.

A Handel::Exception::Argument exception is thrown if the first parameter isn't a hashref or a Handel::Cart object.

Misc. Methods

$cart->count()

Returns the number of items in the cart object.

my $numitems = $cart->count;
$cart->description([$description])

Returns/sets the description of the current cart.

$cart->name([$name])

Returns/set the name of the current cart.

$cart->subtotal()

Returns the current total price of all the items in the cart object. This is equivalent to:

my $iterator = $cart->items;
while (my $item = $iterator->next) {
    $subtotal += $item->quantity*$item->price;
};

Starting in version 0.12, subtotal now returns a stringified Handel::Currency object. This can be used to format the price, and hopefully to convert it's currency to another locale in the future.

$cart->type()

Returns the type of the current cart. Currently the two types are

CART_TYPE_TEMP

The cart is temporary and may be purges during any cleanup process after the designated amount of inactivity.

CART_TYPE_SAVED

The cart should be left untouched by any cleanup process and is available to the shopper at any time.

SEE ALSO

Handel::Constants

AUTHOR

Christopher H. Laco
CPAN ID: CLACO
claco@chrislaco.com
http://today.icantfocus.com/blog/