deniscsz / laravel-cart

A simple yet customizable Laravel shopping cart API

Laravel Shopping Cart API

A simple yet customizable Laravel shopping cart API. Provides RESTful API endpoints out of the box to help with your next e-commerce build. Designed specifically with single page application (SPA) requirements in mind.

Works best with cart.js for front-end integration.

Table of Contents

Requirements
Installation
Configuration
Usage
Advanced Usage: Checkout Class
License

Requirements

• PHP 8+
• Laravel 8.x

Installation

composer require yabhq/laravel-cart

Configuration

The package publishes some migrations, routes (for optional use) and classes for further customizing your store logistics.

php artisan vendor:publish --provider="Yab\ShoppingCart\ShoppingCartServiceProvider"

Full list of published files:

• database/migrations/2020_12_13_000001_create_carts_table
• database/migrations/2020_12_13_000002_create_cart_items_table
• routes/checkout.php
• config/checkout.php
• app/Logistics/CartLogistics.php
• app/Logistics/ShippingLogistics.php
• app/Logistics/TaxLogistics.php
• app/Logistics/DiscountLogistics.php

Usage

First, simply implement the Purchaseable interface on your product (or other purchaseable) model.

app/Models/Product.php

use Yab\ShoppingCart\Traits\Purchaseable;
use Yab\ShoppingCart\Contracts\Purchaseable as PurchaseableInterface;

class Product extends Model implements PurchaseableInterface
{
    use Purchaseable;
}

Next we should implement the Purchaser interface on the model representing the end customer.

app/Models/Customer.php

use Yab\ShoppingCart\Traits\Purchaser;
use Yab\ShoppingCart\Contracts\Purchaser as PurchaserInterface;

class Customer extends Model implements PurchaserInterface
{
    use Purchaser;
}

If you would like to use the built-in cart API endpoints, you can simply include checkout.php in your existing routes file.

routes/api.php

Route::group(['middleware' => ['example']], function () {
    require base_path('routes/checkout.php');
});

This will add the following routes:

POST /checkouts
GET /checkouts/{checkout}
PUT /checkouts/{checkout}
DELETE /checkouts/{checkout}

POST /checkouts/{checkout}/items
PUT /checkouts/{checkout}/items/{item}
DELETE /checkouts/{checkout}/items/{item}

POST /checkouts/{checkout}/discount

Not every e-commerce store is the same. This package provides several "logistics" classes which allow you to hook into the core package logic and perform some common customizations. For example, you may specify how the tax, shipping and discount amounts are determined:

app/Logistics/TaxLogistics.php

public static function getTaxes(Checkout $checkout) : float

app/Logistics/ShippingLogistics.php

public static function getShippingCost(Checkout $checkout) : float

app/Logistics/DiscountLogistics.php

public static function getDiscountFromCode(Checkout $checkout, string $code) : float

app/Logistics/CartLogistics.php

public static function getPurchaseable(string $type, mixed $id) : mixed
public static function beforeCartItemAdded(Checkout $checkout, mixed $purchaseable, int $qty) : void
public static function hasInfoNeededToCalculateTotal(Checkout $checkout) : bool

The Checkout Class

For more advanced usage, the package comes with a Checkout class which allows you to interact with the shopping cart directly. This may be useful in case you want to implement your own custom controller logic.

Creating or retrieving a checkout instance:

$checkout = Checkout::create();
// or
$checkout = Checkout::findById('uuid-123');

Getting the ID of an existing checkout:

$checkout->id();

Adding a custom field for a checkout:

$checkout->setCustomField('some key', 'some value');

Deleting a checkout:

$checkout->destroy();

Interacting with the underlying cart model and query builder:

// Yab\ShoppingCart\Models\Cart
$checkout->getCart();

// Illuminate\Database\Eloquent\Builder
$checkout->getCartBuilder();

Adding, updating or removing cart items:

// Add 1 qty of product and return the CartItem model
$item = $checkout->addItem($product, 1);

// Override the default unit price for the product
$item = $checkout->addItem($product, 1, 11.95);

// Add custom options to a checkout item
$item = $checkout->addItem(
    purchaseable: $product,
    qty: 1,
    options: [ 'size' => 'medium' ],
);

// Update the quantity of the item to 2
$checkout->updateItem($item->id, 2);

// Remove the item entirely
$checkout->removeItem($item->id);

Optionally set a purchaser entity (class must implement Purchaser interface):

$checkout->setPurchaser($customer);

Getting the shipping, subtotal, taxes and total:

$checkout->getShipping(); // 5.00
$checkout->getSubtotal(); // 110.00
$checkout->getDiscount(); // 10.00
$checkout->getTaxes(); // 13.00
$checkout->getTotal(); // 113.00

License

The MIT License (MIT). Please see License File for more information.