Handel::Cart(3)

NAME
Handel::Cart - Module for maintaining shopping cart contents

SYNOPSIS
    use Handel::Cart;

    my $cart = Handel::Cart->create({
        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 component for maintaining simple shopping cart data.

CONSTRUCTOR

  create

Arguments: \%data [, \%options]

Creates a new shopping cart object containing the specified data.

    my $cart = Handel::Cart->create({
        shopper => '10020400-E260-11CF-AE68-00AA004A34D5',
        name    => 'My Shopping Cart'
    });

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

The following options are available:

storage
    A storage object to use to create a new cart object. Currently, this storage object must have the same columns as the default storage object for the current cart class.

METHODS

  add

Arguments: \%data | $item

Adds a new item to the current shopping cart and returns an instance of the item class specified in cart object storage. You can either pass the item data as a hash reference:

    my $item = $cart->add({
        shopper  => '10020400-E260-11CF-AE68-00AA004A34D5',
        sku      => 'SKU1234',
        quantity => 1,
        price    => 1.25
    });

or pass an existing cart item:

    my $wishlist = Handel::Cart->search({
        shopper => '10020400-E260-11CF-AE68-00AA004A34D5',
        type    => CART_TYPE_SAVED
    })->first;

    $cart->add(
        $wishlist->items({sku => 'ABC-123'})->first
    );

When passing an existing cart item to add, all columns in the source item will be copied into the destination item if the column exists in both the destination and source, and the column isn't the primary key or the foreign key of the item relationship.

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

  clear
Deletes all items from the current cart.

    $cart->clear;

  count
Returns the number of items in the cart object.

    my $numitems = $cart->count;

  delete

Arguments: \%filter

Deletes the item matching the supplied filter from the current cart.

    $cart->delete({
        sku => 'ABC-123'
    });

  destroy

Arguments: \%filter

Deletes entire shopping carts (and their items) from the database. When called as an object method, this will delete all items from the current cart object and deletes the cart object itself. "filter" will be ignored.

    $cart->destroy;

When called as a class method, this will delete all carts matching "filter".

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

A Handel::Exception::Argument exception will be thrown if "filter" is not a HASH reference.

  items

Arguments: \%filter [, \%options]

Loads the current carts items matching the specified filter and returns a Handel::Iterator in scalar context, or a list of items in list context.

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

    my @items = $cart->items;

By default, the items returned as Handel::Cart::Item objects. To return something different, set "item_class" in the local "storage" object.

The following options are available:

order_by
    Order the items by the column(s) and order specified. This option uses the SQL style syntax:

        my $items = $cart->items(undef, {order_by => 'sku ASC'});

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

  search

Arguments: \%filter [, \%options]

Loads existing carts matching the specified filter and returns a Handel::Iterator in scalar context, or a list of carts in list context.

    my $iterator = Handel::Cart->search({
        shopper => 'D597DEED-5B9F-11D1-8DD2-00AA004ABD5E',
        type    => CART_TYPE_SAVED
    });

    while (my $cart = $iterator->next) {
        print $cart->id;
    };

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

The following options are available:

storage
    A storage object to use to load cart objects. Currently, this storage object must have the same columns as the default storage object for the current cart class.

order_by
    Order the items by the column(s) and order specified. This option uses the SQL style syntax:

        my $carts = Handel::Cart->search(undef, {order_by => 'name ASC'});

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

  save
Marks the current shopping cart type as "CART_TYPE_SAVED".

    $cart->save

  restore

Arguments: \%filter [, $mode]
Arguments: $cart [, $mode]

Copies (restores) items from a cart, or a set of carts back into the current shopping cart. You may either pass in a hash reference containing the search criteria of the shopping cart(s) to restore:

    $cart->restore({
        shopper => 'D597DEED-5B9F-11D1-8DD2-00AA004ABD5E',
        type    => CART_TYPE_SAVED
    });

or you can pass in an existing "Handel::Cart" object or subclass.

    my $wishlist = Handel::Cart->search({
        id   => 'D597DEED-5B9F-11D1-8DD2-00AA004ABD5E',
        type => CART_TYPE_SAVED
    })->first;

    $cart->restore($wishlist);

For either method, you may also specify the mode in which the cart should be restored. The following modes are available:

"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 has the more up to date price.

"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::Item" object or subclass.

COLUMNS
The following methods are mapped to columns in the default cart schema. These methods may or may not be available in any subclasses, or in situations where a custom schema is being used that has different column names.

  id
Returns the id of the current cart.

    print $cart->id;

See "id" in Handel::Schema::Cart for more information about this column.

  shopper

Arguments: $shopper

Gets/sets the id of the shopper the cart should be associated with.

    $cart->shopper('11111111-1111-1111-1111-111111111111');
    print $cart->shopper;

See "shopper" in Handel::Schema::Cart for more information about this column.

  type

Arguments: $type

Gets/sets the type of the current cart. Currently the two types allowed are:

"CART_TYPE_TEMP"
    The cart is temporary and may be purged during any [external] 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.

    $cart->type(CART_TYPE_SAVED);
    print $cart->type;

See "type" in Handel::Schema::Cart for more information about this column.

  name

Arguments: $name

Gets/sets the name of the current cart.

    $cart->name('My Naw Cart');
    print $cart->name;

See "name" in Handel::Schema::Cart for more information about this column.

  description

Arguments: $description

Gets/sets the description of the current cart.

    $cart->description('New Cart');
    print $cart->description;

See "description" in Handel::Schema::Cart for more information about this column.

  subtotal
Returns the current total price of all the items in the cart object as a stringified Handel::Currency object. This is equivalent to:

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

SEE ALSO
Handel::Cart::Item, Handel::Schema::Cart, Handel::Constants

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