Using The Cart

Using The Cart

The Cart provides shopping cart functionality for your e-commerce application. It handles storing product items in the user's session and manages the cart state. The cart object is available via the cart() function in your templates.

Example:

<nav class="topmenu">
   <a href="/t/categories/board-games">Board Games</a>
   <a href="/cart">Cart
     @if(cart()->isNotEmpty()
       [{{ cart()->itemCount() }}]
     @endif
   </a>
</nav>

Cart Data

The following information can be returned from the cart:

  • cart()->itemCount() - the number of products in the cart (sum of the quantity of products)
  • cart()->total() - the total value of the cart (excl. shipping fees and other checkout adjustments)
  • cart()->getState() - is either NULL (when the shopper hasn't made any cart interaction) or an enum with possible values of active, checkout, abandoned.
  • cart()->isEmpty() - returns whether the cart for the current session is empty
  • cart()->isNotEmpty() - is the opposite of isEmpty()

Cart Items

The cart()->getItems() method returns a collection of all products currently in the cart with their quantities and prices. If the cart is empty, an empty collection is returned.

Example:

<div>
  @if(cart()->isEmpty())
      Your cart is empty
  @else
      @foreach(cart()->getItems() as $item)
          <article>
              <a href="{{ url_of($item->product) }}">{{ product_title($item->product) }}</a>
              |
              {{ $item->quantity }} x {{ format_price($item->price) }}
              |
              {{ format_price($item->total) }}
          </article>
      @endforeach
  @endif
<div>

Cart Item Data

Each cart item has the following data:

  • id - to be used to update/delete the cart item
  • product - the product or master product variant object, each having:
    • sku - Stock Keeping Unit ID of the product
    • id - Mind that a simple product and a master product variant can possibly have the same id but still represent different entries!
    • price - the price of the product (without line adjustments like discounts)
    • name - it's available, but use the product_title($product) helper instead!
  • price - numeric the price of the item (with line adjustments like discounts)
  • quantity - the quantity of the item
  • total - the total of the item (quantity × price)
  • configuration() - either an array or null with custom item configuration
  • hasConfiguration() - returns true if the item has a configuration, false otherwise
  • doesntHaveConfiguration() - the opposite of hasConfiguration()

Adding An Item

To add items to the cart, submit a POST request to the URL returned by the add_to_cart_url() helper. This helper generates the appropriate "add to cart" URL depending on the type of the product.

For the full payload spec, see the Add Product to Cart Endpoint.

The add_to_cart_url() function requires the $product parameter, which must be either a master product variant or a simple product.

Example usage in a form:

<form action="{{ add_to_cart_url($product) }}" method="post" class="mb-4">
    @csrf

    <span class="mr-2 font-weight-bold text-primary btn-lg">
        {{ format_price($product->price) }}
    </span>
    <button type="submit" class="btn btn-success btn-lg"
        @if(!$product->price) disabled @endif>
        {{ __('Add to cart') }}
    </button>
</form>

When you add the same product twice, the quantity of the given product will be increased after the second time, unless you POST force_new_item=1 as a hidden field, like this:

<form action="{{ add_to_cart_url($product) }}" method="post">
    @csrf

    <input type="hidden" name="force_new_item" value="1">

    <button type="submit">Add to cart</button>
</form>

Updating An Item

The quantity of an item can be updated by using the Update Cart Item Endpoint:

@foreach(cart()->getItems() as $item)
    <form action="{{ route('shop.cart.update', $item) }}" method="post">
        @csrf
        <input type="hidden" name="_method" value="PUT">    
        <input type="text" name="qty" value="{{ $item->getQuantity() }}">

        <button type="submit">Update the quantity</button>
    </form>
@endforeach

Deleting An Item

To delete an item from the cart, send a DELETE request to the Delete Cart Item Endpoint:

@foreach(cart()->getItems() as $item)
    <form action="{{ route('shop.cart.delete', $item) }}" method="post">
        @csrf
        <input type="hidden" name="_method" value="DELETE">

        <button type="submit">Remove from the cart</button>
    </form>
@endforeach

Item Configuration

It is possible to pass an item configuration, which holds additional information for the given item.

<form action="{{ add_to_cart_url($product) }}" method="post">
    @csrf

    <input type="hidden" name="configuration[extra_bacon]" value="1">
    <input type="hidden" name="configuration[extra_cheese]" value="1">
    <input type="hidden" name="configuration[no_pickles]" value="1">

    <button type="submit">Add to cart</button>
</form>

When adding the same product to the cart with differing configuration, then the backend will always create a new cart item instead of increasing the quantity of the existing item.

Configuration can be useful when the certain aspects of the product can be customized without price change or an additional product.

Subitems

A sub-cart-item is basically a child element of another cart item. It lets you attach extra things that logically belong to the main item but also are separate products in the cart. Think of it as “add-ons” or “components” of a parent item.

It can be used when you want to:

  • group options, extras, or bundled items under a main product;
  • to help production to know if certain products need to be assembled or packed together.

Subitems are also fully fledged cart items with price, quantity, etc, and therefore they must represent a product that has a price.

Examples:

  1. Pizza with Toppings:
    • Large Margherita Pizza – $12
      • Extra Cheese – $2
      • Olives – $1
    • Medium Buffala Pizza – $11
      • Sauce Picante – $1
  2. Customizable Laptop
    • Laptop Base Model – $1000
      • 32GB RAM Upgrade – $150
      • Windows 11 Pro – $79
  3. Gift Wrapping
    • The Big Cat Book – $20
      • Gift Wrap - Green Kitten Motif – $3
    • History of Motorcycles Book Hard Cover – $35
      • Gift Wrap - Harley-Davidson Motif – $4

To add an item as a subitem of another, you need to pass the parent_id field in the add to cart payload:

<form action="{{ add_to_cart_url($product) }}" method="post">
    @csrf

    <input type="hidden" name="parent_id" value="{{ $item->id }}">

    {{ product_title($product) }}

    <button type="submit">Add as an option to {{ product_title($item->product) }}</button>
</form>