A small package use to create and manage carts (such as shopping, recently viewed, compared items...) in Laravel application.
Look at one of the following topics to learn more about Laravel Cart
Currently, Laravel Cart have two branchs compatible with Laravel 4.x and 5.x as follow:
| Branch | Laravel version |
|---|---|
| v1.0 | 4.x |
| v2.0 | 5.x |
Note: This documentation is use for Laravel 5+. If you use Laravel 4.x, you should read at here
You can install this package through Composer.
- First, at the root of your application directory, run the following command:
$ composer require jackiedo/cart:2.*
If you are using Laravel 5.4 or earlier, you must perform these two steps:
- The second step is add the service provider. Open
config/app.php, and add a new item to theproviderssection:
'Jackiedo\Cart\CartServiceProvider',
Note: From Laravel 5.1, you should write as
Jackiedo\Cart\CartServiceProvider::class,
- And the final step is add the following line to the
aliasessection in fileconfig/app.php:
'Cart' => 'Jackiedo\Cart\Facades\Cart',
Note: From Laravel 5.1, you should write as
'Cart' => Jackiedo\Cart\Facades\Cart::class,
Laravel Cart has a facade with name is Jackiedo\Cart\Facades\Cart. You can do any cart operation through this facade:
Example:
<?php YourNamespace;
use Jackiedo\Cart\Facades\Cart;
class YourClass
{
...
$variable = Cart::doSomething();
...
}Laravel Cart supports multiple instances of the cart. This is useful for using different carts for different management purposes, such as shopping cart, recently viewed, compared items...
Whenever you create a cart, you should name it so that it can be distinguished from other carts. You can set name for an instance of the cart by calling Cart::instance($name). From this point of time, the active instance of the cart will have a specified name, so whenever you perform a cart operation, you must specify a specific cart.
$cart = Cart::instance('shopping');If you want to switch between instances, you just call Cart::instance($otherName) again, and you're working with the other instance.
// Create new instance of the cart with named is `shopping`
$cart = Cart::instance('shopping');
// Perform a something with this instance
$cart->doSomething();
// Switch to `compared_items` cart and do something
Cart::instance('wishlist')->doSomething();
// Do another thing also with `compared_items` cart
Cart::doAnother();
// Switch to `recently_viewed` cart and do something
Cart::instance('recently_viewed')->doSomething();
// Go back to work with `shopping` cart
Cart::instance('shopping')->doSomething();
...Note:
- There is always a default cart name called
default, so when you're not using theinstancemethod, exampleCart::doSomething();, is the same asCart::instance('default')->doSomething(); - Keep in mind that the current cart stays in the last set instance for as long as you don't set a different one during script execution.
You can easily get current cart instance name by calling getInstance() method.
$cartName = Cart::getInstance();Adding an item to the cart is really simple, you just use the add() method, which accepts a variety of parameters.
/**
* Add an item to the cart
*
* @param string|int $id Associated model or Unique ID of item before insert to the cart
* @param string $title Name of item
* @param int $qty Quantities of item want to add to the cart
* @param float $price Price of one item
* @param array $options Array of additional options, such as 'size' or 'color'
*
* @return Jackiedo\Cart\CartItem
*/
Cart::add($id, $title[, $qty = 1[, $price = 0[, $options = array()]]]);Example:
// Add an article to the `recently_viewed` cart
$recentlyViewed = Cart::instance('recently_viewed')->add('AID0782000', 'An example article');
// Add an product to the `shopping` cart
$shoppingCartItem = Cart::instance('shopping')->add(37, 'Polo T-shirt for men', 5, 17.5, ['color' => 'red', 'size' => 'M']);The result of this method is an instance of Jackiedo\Cart\CartItem class (extended from Illuminate\Support\Collection) and has structured as follows:
{
hash : "6afbeca78618c01954c98fbd473fd176",
id : 37,
title : "Polo T-shirt for men",
qty : 5,
price : 17.5,
subtotal : 87.5,
options : {
color : "red",
size : "M"
},
associated : null
}
So, you can access it's property by method get() of Laravel Collection instance.
Example:
// Get title of the cart item
$cartItemTitle = $shoppingCartItem->get('title'); // Polo T-shirt for menBut with some enhancements to this CartItem class, you can more easily access entity attributes in a more succinct way:
Example:
// Get title of the cart item
$cartItemTitle = $shoppingCartItem->title; // Polo T-shirt for men
// Get sub total price of this cart item
$cartItemTitle = $shoppingCartItem->subtotal; // 87.5
// Get color option of this cart item
$cartItemTitle = $shoppingCartItem->options->color; // red
...Note: In the visible attributes of each cart item returned from the cart, there is an important type of information, called a hash. The hash of the cart item is used to distinguish items with different attributes in the cart. So with the same item, when you add to the cart with different attributes, you will have cart items with different hash.
Update the specified cart item with given quantity or attributes. To do this, you need hash information of cart item and then use the update() method.
/**
* Update an item in the cart with the given ID.
*
* @param string $itemHash The unique identifier of the cart item
* @param int|array $attributes New quantity of item or array of new attributes to update
*
* @return Jackiedo\Cart\CartItem|null
*/
Cart::update($itemHash, $quantity);
Cart::update($itemHash, $attributes);Example:
$itemHash = "6afbeca78618c01954c98fbd473fd176";
// Update title and options
$cartItem = Cart::instance('shopping')->update($itemHash, ['title' => 'New item title', 'options' => ['color' => 'yellow']]);
// or only update quantity
$cartItem = Cart::instance('shopping')->update($itemHash, 10);
// the hash of cart item will be changed
$newItemHash = $cartItem->hash;Note: You can only update the
title,qty,priceandoptionsattributes. Whenever you update cart item's info, the hash of cart item can be changed.
Get the specified cart item with given hash of cart item
/**
* Get an item in the cart by its ID.
*
* @param string $itemHash The unique identifier of the cart item
*
* @throws Jackiedo\Cart\Exceptions\CartInvalidHashException
*
* @return Jackiedo\Cart\CartItem
*/
Cart::get($itemHash);Example:
$item = Cart::instance('shopping')->get('c2bb42b0b2a16eb1fb477b68822448de');{
hash : "c2bb42b0b2a16eb1fb477b68822448de",
id : 37,
title : "New item title",
qty : 5,
price : 17.5,
subtotal : 87.5,
options : {
color : "yellow",
size : "M"
},
associated : null
}
Get all the cart items in the cart.
/**
* Get cart content
*
* @return \Illuminate\Support\Collection
*/
Cart::all();Example:
$items = Cart::instance('shopping')->all();And the results may have the following structure:
{
c2bb42b0b2a16eb1fb477b68822448de: {
hash : "c2bb42b0b2a16eb1fb477b68822448de",
id : 37,
title : "Polo T-shirt for men",
qty : 1,
price : 17.5,
subtotal : 17.5,
options : {
color : "yellow",
size : "L"
},
associated : null
},
6afbeca78618c01954c98fbd473fd176: {
hash : "6afbeca78618c01954c98fbd473fd176",
id : 37,
title : "Polo T-shirt for men",
qty : 5,
price : 17.5,
subtotal : 87.5,
options : {
color : "red",
size : "M"
},
associated : null
}
}
Returns the total price of all items in the cart.
/**
* Get the total price of all items in the cart.
*
* @return float
*/
Cart::total();Example:
$total = Cart::instance('shopping')->total();Return the number of unique items in the cart.
/**
* Get number of items in the cart.
*
* @return int
*/
Cart::countItems();Example:
Cart::instance('shopping')->add(37, 'Polo T-shirt for men', 5, 100.00, ['color' => 'red', 'size' => 'M']);
Cart::add(37, 'Polo T-shirt for men', 1, 100.00, ['color' => 'red', 'size' => 'M']);
Cart::add(37, 'Polo T-shirt for men', 5, 100.00, ['color' => 'red', 'size' => 'M']);
Cart::add(127, 'Another example product', 15, 100.00, ['color' => 'green', 'size' => 'S']);
$items = Cart::countItems(); // 2 (Polo T-shirt for men, Another example product)Return the number of quantities for all items in the cart.
/**
* Get quantities of all items in the cart.
*
* @return int
*/
Cart::countQuantities();Example:
Cart::instance('shopping')->add(37, 'Polo T-shirt for men', 5, 100.00, ['color' => 'red', 'size' => 'M']);
Cart::add(37, 'Polo T-shirt for men', 1, 100.00, ['color' => 'red', 'size' => 'M']);
Cart::add(37, 'Polo T-shirt for men', 5, 100.00, ['color' => 'red', 'size' => 'M']);
Cart::add(127, 'Another example product', 15, 100.00, ['color' => 'green', 'size' => 'S']);
$quantities = Cart::countQuantities(); // 26To search cart items in the cart, you must provide array of the cart item's attributes
/**
* Search the cart items with given filter
*
* @param Closure|array $filter A closure or an array with item's attributes
* @param boolean $allScope Indicates that the results returned must satisfy
* all the conditions of the filter at the same time
* or that only parts of the filter.
*
* @return Illuminate\Support\Collection;
*/
Cart::search($filter[, $allScope = true]);Note: The
$allScopeparameter use to indicates that the results returned must satisfy all the conditions of the filter at the same time or that only parts of the filter.
Example:
// Get all cart items that have color is red
$items = Cart::instance('shopping')->search([
'options' => [
'color' => 'red'
]
]);
// Get all cart items that have title is [Polo T-shirt for men] AND size is [L]
$items = Cart::instance('shopping')->search([
'title' => 'Polo T-shirt for men',
'options' => [
'size' => 'L'
]
]);
// Get all cart items that have id is [10], OR size is [M]
$items = Cart::instance('shopping')->search([
'id' => 10,
'options' => [
'size' => 'M'
]
], false);Remove the specified cart item by its hash.
/**
* Remove an cart item with the given hash out of the cart.
*
* @param string $itemHash The unique identifier of the cart item
*
* @return Jackiedo\Cart\Cart
*/
Cart::remove($itemHash);Example:
Cart::instance('shopping')->remove('6afbeca78618c01954c98fbd473fd176');Clean a specified cart with given cart instance name.
/**
* Remove all items in the cart
*
* @return Jackiedo\Cart\Cart
*/
Cart::destroy()Example:
Cart::instance('shopping')->destroy();You need to know that all result of cart content (response by methods such as Cart::all(), Cart::search()), every cart item (response by methods such as Cart::add(), Cart::get(), Cart::update()) and cart item's options (is property of one cart item) are return a Laravel Collection, so all methods you can call on a Laravel Collection are also available on them.
Example:
$count = Cart::instance('shopping')->all()->count();And another example (group by attribute):
$groupByTitle = Cart::instance('shopping')->all()->groupBy('title');And may be you will see:
{
Polo neck T-shirt for men: [
{
hash : "c2bb42b0b2a16eb1fb477b68822448de",
id : 37,
title : "Polo neck T-shirt for men",
qty : 5,
price : 17.5,
subtotal : 87.5,
options : {
color : "yellow",
size : "M"
},
associated : null
},
{
hash : "6afbeca78618c01954c98fbd473fd176",
id : 37,
title : "Polo neck T-shirt for men",
qty : 10,
price : 17.5,
subtotal : 175,
options : {
color : "red",
size : "M"
},
associated : null
}
]
}
A special feature of Laravel Cart is association an Eloquent model with the cart item in the cart. Let's say you have a Product model in your application. With this feature, you can tell the cart that an item in the cart, is associated to a instance Product model. That way, you can access your instance of model right from instance of CartItem!
To be ready for this, Laravel Cart has one interface (with namespace is Jackiedo\Cart\Contracts\UseCartable) and one trait (with namespace is Jackiedo\Cart\Traits\CanUseCart). The rest is you just apply for your Eloquent model.
It's easily to do this. Your Eloquent model just only need implements the UseCartable interface and use the CanUseCart trait.
<?php namespace App;
use Illuminate\Database\Eloquent\Model;
use Jackiedo\Cart\Contracts\UseCartable; // Interface
use Jackiedo\Cart\Traits\CanUseCart; // Trait
class Product extends Model implements UseCartable {
use CanUseCart;
...
}If your model implemented the UseCartable interface and you uses your model to add the item to the cart, it will associate automatically.
/**
* Add an item to the cart
*
* @param object $model The UseCartable instance
* @param int $qty Quantities of instance want to add to the cart
* @param array $options Array of additional options, such as 'size' or 'color'
*
* @return Jackiedo\Cart\CartItem
*/
Cart::add($model[, int $qty = 1[, array $options = array()]]);Example:
// Get your model
$product = Product::find(1);
// Add 5 items of this product to the cart
$cartItem = Cart::instance('shopping')->add($product, 5);
// Or you can do this by another way
$cartItem = $product->addToCart('shopping', 5);And the result will be:
{
hash : "3fbdcdad4cbcee36f36ee15d89505d54",
id : 1,
title : "Polo neck T-shirt for men",
qty : 5,
price : 17.5,
subtotal : 87.5,
options : {
color : "red",
size : "M"
},
associated : "App\Product"
}
Please, notice the associated attribute of the cart item. Do you see the value is App\Product? Wow! now you can be able to directly access your model from this cart item instance through model property. Example:
return $cartItem->model->name; // Get name of your productWhen your model implemented the UseCartable interface and you uses your model to add the item to the cart, Laravel Cart will get automatically attributes title, price in your Eloquent model to use for inserting item to the cart.
But if your Eloquent model doesn't have these attributes (for example, your model field used to store product's name is not a title but name), you need to reconfigure it so that automatic information retrieval is done correctly. You can do this easily by placing your Eloquent model in two attributes:
<?php namespace App;
use Illuminate\Database\Eloquent\Model;
use Jackiedo\Cart\Contracts\UseCartable;
use Jackiedo\Cart\Traits\CanUseCart;
class Product extends Model implements UseCartable {
use CanUseCart;
protected $cartTitleField = 'name'; // Your correctly field for product's title
protected $cartPriceField = 'unit_price'; // Your correctly field for product's price
...
}/**
* Determine the UseCartable item has in the cart
*
* @param string|null $cartInstance The cart instance name
* @param array $options Array of additional options, such as 'size' or 'color'
*
* @return boolean
*/
public function hasInCart($cartInstance = null, array $options = []);
/**
* Get all the UseCartable item in the cart
*
* @param string|null $cartInstance The cart instance name
*
* @return Illuminate\Support\Collection
*/
public function allFromCart($cartInstance = null);
/**
* Get the UseCartable items in the cart with given additional options
*
* @param string|null $cartInstance The cart instance name
* @param array $options Array of additional options, such as 'size' or 'color'
*
* @return Illuminate\Support\Collection
*/
public function searchInCart($cartInstance = null, array $options = []);Example:
$product = Product::find(1);
return ($product->hasInCart('shopping')) ? 'Yes' : 'No';At the above, we knew how to do a searching for items in the cart. And because informations of each cart item is a Laravel Collection, so that you can easily building a custom searching with placing a Closure into Cart::search() method. Laravel Cart will use this Closure with filter() method of Collection. Example:
$results = Cart::instance('shopping')->search(function ($cartItem) {
return $cartItem->hash === 1 && $cartItem->associated === "Product";
});You can refer to Collection on the Laravel homepage.
In version 2.x of this package, it's possibly to use dependency injection to inject an instance of the Cart class into your controller or other class. Example:
<?php namespace App\Http\Controllers;
use App\Http\Controllers\Controller;
use App\Http\Requests;
use App\Product;
use Illuminate\Http\Request;
use Jackiedo\Cart\Cart;
class TestCartController extends Controller {
protected $cart;
public function __construct(Cart $cart)
{
$this->cart = $cart;
}
public function content()
{
$cart = $this->cart->instance('shopping')->all();
}
public function add()
{
$product = Product::find(1);
$cartItem = $this->cart->instance('shopping')->add($product, 5);
}
}The Laravel Cart package has events build in. Currently, there are eight events available for you to listen for.
| Event Name | Fired | Parameters |
|---|---|---|
| cart.adding | When an item is being added to the cart. | ($cartItem, $cart); |
| cart.added | When an item was added to the the cart. | ($cartItem, $cart); |
| cart.updating | When an item in the cart is being updated. | ($cartItem, $cart); |
| cart.updated | When an item in the cart was updated. | ($cartItem, $cart); |
| cart.removing | When an item is being removed from the cart. | ($cartItem, $cart); |
| cart.removed | When an item was removed from the cart. | ($cartItem, $cart); |
| cart.destroying | When a cart is being destroyed. | ($cart); |
| cart.destroyed | When a cart was destroyed. | ($cart); |
For example, we can listen events through the Event facade.
<?php
use Illuminate\Support\Facades\Event;
...
Event::listen('cart.adding', function($cartItem, $cart){
if ($cart->getInstance() == 'shopping') {
...
}
});
...Note:
- The parameters of events are actual entities. Be careful when working with them. It is possible to change the values in the cart.
- See more about Laravel Events here.
The Laravel Cart package will throw exceptions if something goes wrong. This way it's easier to debug your code using the Laravel Cart package or to handle the error based on the type of exceptions. The Laravel Cart packages can throw the following exceptions:
| Exception | Reason |
|---|---|
| CartInvalidArgumentException | When you missed or entered invalid argument (such as title, qty...). |
| CartInvalidHashException | When the hash information you provided doesn't exists in the current cart. |
| CartInvalidAssociatedException | When the associated class doesn't exists. |
| CartInvalidModelException | When the associated model of the cart item row doesn't exists. |
MIT © Jackie Do
Hopefully, this package is useful to you.
