NAME

Handel::Order - Module for maintaining order contents

SYNOPSIS

my $order = Handel::Order->new({
    id => '12345678-9098-7654-322-345678909876'
});

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

DESCRIPTION

Handel::Order is a component for maintaining simple order records.

While Handel::Order 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 three ways to create a new order object. You can either pass a hashref into new containing all the required values needed to create a new order record or pass a hashref into load containing the search criteria to use to load an existing order or set of orders.

BREAKING API CHANGE: Starting in version 0.17_04, new no longer automatically creates a checkout process for CHECKOUT_PHASE_INITIALIZE. The $noprocess parameter has been renamed to $process. The have the new order automatically run a checkout process, set $process to 1.

NOTE: Starting in version 0.17_02, the cart is no longer required! You can create an order record that isn't associated with a current cart.

NOTE: As of version 0.17_02, Order::subtotal and Order::Item:: total are calculated once only when creating an order from an existing cart. After that order is created, any changes to items price/wuantity/totals and the orders subtotals must be calculated manually and put into the database by the user though their methods.

If the cart key is passed, a new order record will be created from the specified carts contents. The cart key can be a cart id (uuid), a cart object, or a has reference contain the search criteria to load matching carts.

Handel::Order->new(\%data [, $process])

my $order = Handel::Order->new({
    shopper => '10020400-E260-11CF-AE68-00AA004A34D5',
    id => '111111111-2222-3333-4444-555566667777',
    cart => $cartobject
});

my $order = Handel::Order->new({
    shopper => '10020400-E260-11CF-AE68-00AA004A34D5',
    id => '111111111-2222-3333-4444-555566667777',
    cart => '11112222-3333-4444-5555-666677778888'
});

my $order = Handel::Order->new({
    shopper => '10020400-E260-11CF-AE68-00AA004A34D5',
    id => '111111111-2222-3333-4444-555566667777',
    cart => {
        id => '11112222-3333-4444-5555-666677778888',
        type => CART_TYPE_TEMP
    }
});

Handel::Order->load([\%filter, $wantiterator])

my $order = Handel::Order->load({
    id => 'D597DEED-5B9F-11D1-8DD2-00AA004ABD5E'
});

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

my @orders = Handel::Order->load();

In scalar context load returns a Handel::Order 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::Order->load(undef, RETURNAS_ITERATOR);
while (my $item = $iterator->next) {
    print $item->sku;
};

See Handel::Constants for the available RETURNAS options.

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

METHODS

add(\%data)

You can add items to the order by supplying a hashref containing the required name/values or by passing in a newly create Handel::Order::Item object. If successful, add will return a Handel::Order::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.

clear

This method removes all items from the current cart object.

$cart->clear;

copy_cart

When creating a new order from an existing cart, copy_cart will be called to copy the carts contents into the new order object. If you are using custom cart or order subclasses, the default copy_cart will only copy the fields declared in Handel::Cart, ignoring any custom fields you may add.

To fix this, simply subclass Handel::Order and override copy_cart. As its parameters, it will receive the order and cart objects.

package CustomOrder;
use base 'Handel::Order';

sub copy_cart {
    my ($self, $order, $cart) = @_;

    # copy stock fields
    $self->SUPER::copy_cart($order, $cart);

    # now catch the custom ones
    $order->customfield($cart->customfield);
};

copy_cart_items

When creating a new order from an existing cart, copy_cart_items will be called to copy the cart items into the new order object items. If you are using custom cart or order subclasses, the default copy_cart_item will only copy the fields declared in Handel::Cart::Item, ignoring any custom fields you may add.

To fix this, simply subclass Handel::Order and override copy_cart. As its parameters, it will receive the order and cart objects.

package CustomOrder;
use base 'Handel::Order';

__PACKAGE__->cart_class('CustomCart');

sub copy_cart_items {
    my ($self, $order, $cart) = @_;
    my $items = $cart->items(undef, RETURNAS_ITERATOR);

    while (my $item = $items->next) {
        my %copy;

        foreach (CustomCart::Item->columns) {
            next if $_ =~ /^(id|cart)$/i;
            $copy{$_} = $item->$_;
        };

        $copy{'id'} = $self->uuid unless constraint_uuid($copy{'id'});
        $copy{'orderid'} = $order->id;
        $copy{'total'} = $copy{'quantity'}*$copy{'price'};

        $order->add_to__items(\%copy);
    };
};

delete(\%filter)

This method deletes the order 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';
};

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.

cart_class($orderclass)

Gets/Sets the name of the class to use when loading existing cart into the new order. By default, it loads carts using Handel::Cart. While you can set this directly in your application, it's best to set it in a custom subclass of Handel::Order.

package CustomOrder;
use base 'Handel::Order';
__PACKAGE__->cart_class('CustomCart');

item_class($classname)

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

package CustomOrder;
use strict;
use warnings;
use base 'Handel::Order';

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

1;

items([\%filter, [$wantiterator])

You can retrieve all or some of the items contained in the order 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.

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

my @items = $order->items;
...
dosomething(\@items);

When filtering the items in the order in scalar context, a Handel::Order::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 = $order->items({sku => 'SKU1234'}, RETURNAS_ITERATOR);
if ($item->isa('Handel::Order::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 - $order->items((sku -> 'SKU1%'});

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

reconcile($cart)

This method copies the specified carts items into the order only if the item count or the subtotal differ.

The cart key can be a cart id (uuid), a cart object, or a hash reference contain the search criteria to load matching carts.

billtofirstname

Gets/sets the bill to first name

billtolastname

Gets/sets the bill to last name

billtoaddress1

Gets/sets the bill to address line 1

billtoaddress2

Gets/sets the bill to address line 2

billtoaddress3

Gets/sets the bill to address line 3

billtocity

Gets/sets the bill to city

billtostate

Gets/sets the bill to state/province

billtozip

Gets/sets the bill to zip/postal code

billtocountry

Gets/sets the bill to country

billtodayphone

Gets/sets the bill to day phone number

billtonightphone

Gets/sets the bill to night phone number

billtofax

Gets/sets the bill to fax number