LaraCart 1.1.0 - Laravel Shopping Cart Package

##Upgrade to 1.1 https://github.com/lukepolo/laracart/releases/tag/1.1.0

   subTotal(false, false) now becomes subTotal(false). 
   getPrice(false, false) now becomes  getPrice(false)
   subItemsTotal(false, false) now becomes subItemsTotal(false)

Features

• Coupons
• Session Based System
• Cross Device Support
• Multiple cart instances
• Fees such as a delivery fee
• Taxation on a the item level
• Prices display currency and locale
• Endless item chaining for complex systems
• Totals of all items within the item chains
• Item Model Relation at a global and item level
• Quickly insert items with your own item models

Laravel compatibility

Laravel	laracart
5.x	1.x

Installation

Install the package through Composer. Edit your project's composer.json file by adding:

{
    "require": {
        ........,
        "lukepolo/laracart": "1.1.*"
    }
}

Include Service Providers / Facade in app/config/app.php:

	LukePOLO\LaraCart\LaraCartServiceProvider::class,

Include the Facade :

	'LaraCart' => LukePOLO\LaraCart\Facades\LaraCart::class,

Copy over the configuration file by running the command:

    php artisan vendor:publish --provider='LukePOLO\LaraCart\LaraCartServiceProvider' 

Look through the configuration options and change as needed

Overview

• Usage
• SubItems
• Item Model Relations
• Currency & Locale
• Coupons
• Fees
• Instances
• Cross Device Support
• Exceptions
• Events

Usage

Adding Items

    // Adding an item to the cart
    LaraCart::add(2, 'Shirt', 200, 15.99, [
        'size' => 'XL'
    ]);

    // If you need line items rather than just updating the qty you can do
    LaraCart::addLine(2, 'Shirt', 200, 15.99, [
        'size' => 'XL'
    ]);
    
    // Also you can have your item not taxed
    $item = LaraCart::addLine(2, 'Shirt', 200, 15.99, [
        'size' => 'XL'
        ],
        $taxable = false
    );

Item Hashes

    $item = LaraCart::add(2, 'Shirt', 200, 15.99, [
         'size' => 'XL'
    ]);
     
    $itemHash = $item->getHash();
   
    // That way we can find / remove from the cart
    LaraCart::getItem($itemHash);
    LaraCart::removeItem($item->getHash());

Increment Item's quantity

    // Given we have an item in cart
    $item = LaraCart::add(2, 'Shirt', 200, 15.99, [
         'size' => 'XL'
    ]);

    $itemHash = $item->getHash();

    // We increment the quantity of the item in cart
    LaraCart::increment($itemHash);

    // We decrement the quantity of the item in cart
    LaraCart::decrement($itemHash);

Cart Items

    LaraCart::getItems();
    LaraCart::count($withItemQty = true); // If set to false it will ignore the qty on the items and get the line count
        
    LaraCart::updateItem($itemHash, 'name', 'CheeseBurger w/Bacon');
    LaraCart::updateItem($itemHash, 'qty', 5);
    LaraCart::updateItem($itemHash, 'price', 2.50);
    LaraCart::updateItem($itemHash, 'tax', .045);
    
    // Or if you have the item object already
    $item = LaraCart::add(2, 'Shirt', 200, 15.99, [
        'size' => 'XL'
    ]);
    
    $item->size = 'L';
    
    $item->price($formatted = true); // $4.50 | USD 4.50

    // Search for items in the cart by an option
    $matches = LaraCart::find(['size' => 'XL']);

    // Search for items in the cart by multiple options
    $matches = LaraCart::find(['size' => 'XL', 'name' => 'Shirt']);

Cart Attributes

    // Set or update an attribute's value
    LaraCart::setAttribute('label', "Luke's Cart");
    
    // Get a specific attribute's value
    LaraCart::getAttribute('label');
    
    // Get all the attributes
    LaraCart::getAttributes();
    
    // Remove an attribute
    LaraCart::removeAttribute('label');

Emptying / Destroying the Cart

    // Empty will only empty the contents
    LaraCart::emptyCart()

    // Destroy will remove the entire instance of the cart including coupons / fees etc.
    LaraCart::destroyCart()

Cart Totals

    LaraCart::subTotal($format = true, $withDiscount = true);
    LaraCart::totalDiscount($formatted = false);
    LaraCart::taxTotal($formatted = false);
    LaraCart::total($formatted = false, $withDiscount = true);

SubItems

The reasoning behind sub items is to allow you add additional items without the all the necessary things that a regular item needs. For instance if you really wanted the same item but in a different size and that size costs more, you can add it as a sub item so it calculates in the price.

    $item = \LaraCart::add(2, 'Shirt', 1, 15.99, [
        'size' => 'XXL'
    ]);
    
    $item->addSubItem([
        'description' => 'Extra Cloth Cost', // this line is not required!
        'price' => 3.00
    ]);
    
    $item->subTotal(); // $18.99
    $item->subItemsTotal($formatMoney = true); // $3.00

Item Model Relations

You can set a default model relation to an item by setting it in your config item_model

This will fetch your model based on the items id stored in the cart. - ex. Model::findOrFail($id)

    // returns the associated model
    $item->getModel();

    // The second paramater allows you to relate other models with your item model
    $item->setModel(\LukePOLO\LaraCart\Tests\Models\TestItem::class, array $modelRelations);

You can also can easily insert your items with a simple command when using associated models! You will need to set this up in the config file

    $item = \LaraCart::add($itemID = 123123123);
    $item = \LaraCart::add($itemModel);

Item Model Bindings are also available in the config

    // We will look at the more adavnce part of item options, for instance you can do
    \LukePOLO\LaraCart\CartItem::ITEM_OPTIONS => [
        'your_key' => 'price_relation.value' // this will go to the price relation then get the value!
        'your_other_key' => 'price_relation.another_relation.value' // This also works
    ]

Currency & Locale

LaraCart comes built in with a currency / locale display. To configure just checkout the config.php. You can set to show the locale (USD) or the currency ($)

    $item->price($formatted = true); // $4.50 | USD 4.50
    
    LaraCart::total() // $24.23 | USD 24.23

Coupons

Adding coupons could never be easier, currently there are a set of coupons inside LaraCart coupon folder. To create new types of coupons just create a copy of one of the existing coupons and modify it!

    $coupon = new \LukePOLO\LaraCart\Coupons\Fixed($coupon->CouponCode, $coupon->CouponValue, [
        'description' => $coupon->Description
    ]);
    
    LaraCart::addCoupon($coupon);
    LaraCart::removeCoupon($code);
    
    $fixedCoupon->getValue(); // $2.50
    $percentCoupon->getValue; // 15%
    The $coupon->couponValue 

Coupon and Values Available

| Coupon Type | Description | Class | Example of Value | | -------------------- | --------------------------------------- | | Fixed Amount Off | A fixed amount off of the final total | LukePOLO\LaraCart\Coupons\Fixed | 5 ($5 off) | | Percentage Off | A percetnage off based on the final total | LukePOLO\LaraCart\Coupons\Percentage | .10 (10% off)|

Fees

Fees allow you to add extra charges to the cart for various reasons ex: delivery fees.

    LaraCart::addFee('deliveryFee', 5, $taxable =  false, $options = []);
    LaraCart::removeFee('deliveryFee');

Instances

Instances is a way that we can use multiple carts within the same session. Each following request reuse the last instance of the cart set

    LaraCart::setInstance('yourInstanceName');
    
    // Also you can get all the isntances in the session
    LaraCart::getInstances();

Cross Device Support

LaraCart has a baked in cross device support. You must have the LaraCart database migrations and migrate. You may have to modify the migration based on the connection. Also you must be using the auth manager to check for logins.

To enable just change it in your config!

    'cross_devices' => true        

Exceptions

LaraCart packages can throw the following exceptions:

Exception	Reason
InvalidPrice	When trying to give an item a non currency format
InvalidQuantity	When trying to give an item a non-integer for a quantity
CouponException	When a coupon either is expired or an invalid amount
ModelNotFound	When you try to relate a model that does not exist
InvalidTaxableValue	Either a tax value is invalid or taxable is not a boolean

Events

The cart also has events build in:

Event	Fired
laracart.new	When a new cart is started
laracart.update	When a the cart is updated to the session
laracart.addItem($item)	When a item is added to the cart
laracart.updateItem($item)	When a item is updated
laracart.removeItem($itemHash)	When a item is removed from the cart
laracart.empty($cartInstance)	When a cart is emptied
laracart.destroy($cartInstance)	When a cart is destroyed

License

MIT