Extending Carts - Lunar PHP

The cart system is extended by swapping action contracts in the container, and by registering pipeline steps and validators for its calculation and validation lists.

Overview

Every operation Lunar\Core\Models\Cart performs — adding a line, setting a shipping option, creating an order — is a one-line delegation from a verb method on the model to an action contract resolved from the container. Swapping behavior means binding a different implementation of that contract in a service provider; the verb picks it up automatically.

public function add(Purchasable $purchasable, int $quantity = 1, array $meta = [], bool $refresh = true): Cart
{
    // ...
    app(AddsOrUpdatesPurchasable::class)->execute($this, $purchasable, $quantity, $meta);

    return $refresh ? $this->refresh()->recalculate() : $this;
}

Cart action contracts

Lunar\Core\ActionServiceProvider’s $actions map is the canonical list of swappable action seams. The cart-related entries, each a Lunar\Core\Contracts\Actions\Carts\* interface bound to its Lunar\Core\Actions\Carts\* default implementation:

Contract	Default implementation
`AddsAddress`	`AddAddress`
`AddsOrUpdatesPurchasable`	`AddOrUpdatePurchasable`
`AssociatesUser`	`AssociateUser`
`CalculatesLine`	`CalculateLine`
`CalculatesLineSubtotal`	`CalculateLineSubtotal`
`CreatesOrder`	`CreateOrder`
`GeneratesFingerprint`	`GenerateFingerprint`
`GetsExistingCartLine`	`GetExistingCartLine`
`MergesCart`	`MergeCart`
`RemovesPurchasable`	`RemovePurchasable`
`SetsShippingOption`	`SetShippingOption`
`UpdatesCartLine`	`UpdateCartLine`

Rebind a contract from a consumer’s own service provider:

use Lunar\Core\Contracts\Actions\Carts\AddsOrUpdatesPurchasable;

public function register(): void
{
    $this->app->bind(AddsOrUpdatesPurchasable::class, MyAddsOrUpdatesPurchasable::class);
}

Config-string class substitution (config('lunar.*', SomeClass::class)) is not used for these seams — the contract is bound in the container, and a consumer swaps it there. Do not add a config key to point at a custom class.

Calculation pipelines

Cart totals are calculated by running the cart through an ordered list of pipeline classes, and cart lines through a second list. Both lists live in config/lunar/cart.php, as ordered lists rather than single-implementation swaps:

'pipelines' => [
    'cart' => [
        Lunar\Core\Pipelines\Cart\CalculateLines::class,
        Lunar\Core\Pipelines\Cart\ApplyShipping::class,
        Lunar\Core\Pipelines\Cart\CalculateShippingSubTotal::class,
        Lunar\Core\Pipelines\Cart\ApplyDiscounts::class,
        Lunar\Core\Pipelines\Cart\CalculateTax::class,
        Lunar\Core\Pipelines\Cart\Calculate::class,
    ],

    'cart_lines' => [
        Lunar\Core\Pipelines\CartLine\GetUnitPrice::class,
    ],
],

Add a pipe by appending a class to the relevant array. A cart pipe implements handle(Cart $cart, Closure $next): mixed; a cart line pipe implements the same shape against CartLine.

<?php

namespace App\Pipelines\Cart;

use Closure;
use Lunar\Core\Models\Cart;

class CustomCartPipeline
{
    public function handle(Cart $cart, Closure $next): mixed
    {
        // ...

        return $next($cart);
    }
}

Pipes run in the order listed, top to bottom.

Validators

Cart::add(), updateLine(), remove(), addAddress(), setShippingOption(), and createOrder() each run a list of validators, configured the same way, in config/lunar/cart.php:

'validators' => [
    'add_to_cart' => [
        Lunar\Core\Validation\CartLine\CartLineQuantity::class,
        Lunar\Core\Validation\CartLine\CartLineStock::class,
        Lunar\Core\Validation\CartLine\CartLineAvailability::class,
    ],
    'update_cart_line' => [/* ... */],
    'remove_from_cart' => [],
    'set_shipping_option' => [
        Lunar\Core\Validation\Cart\ShippingOptionValidator::class,
    ],
    'order_create' => [
        Lunar\Core\Validation\Cart\ValidateCartForOrderCreation::class,
    ],
],

A validator extends Lunar\Core\Validation\BaseValidator:

<?php

namespace App\Validation\CartLine;

use Lunar\Core\Validation\BaseValidator;

class CartLineQuantity extends BaseValidator
{
    public function validate(): bool
    {
        $quantity = $this->parameters['quantity'] ?? 0;

        if (! $condition) {
            return $this->fail('cart', 'Something went wrong');
        }

        return $this->pass();
    }
}

'validators' => [
    'add_to_cart' => [
        // ...
        App\Validation\CartLine\CartLineQuantity::class,
    ],
],

If validation fails, Lunar\Core\Exceptions\Carts\CartException is thrown. Errors are accessed the same way as Laravel’s own validation responses:

try {
    $cart->setShippingOption($option);
} catch (\Lunar\Core\Exceptions\Carts\CartException $e) {
    $e->errors()->all();
}

Cart line modifiers

A cart line unit price and subtotal can be adjusted just after it is calculated, using a Lunar\Core\Modifiers\CartLineModifier:

<?php

namespace App\Modifiers;

use Closure;
use Lunar\Core\Models\CartLine;
use Lunar\Core\Modifiers\CartLineModifier;

class MyCartLineModifier extends CartLineModifier
{
    public function subtotalled(CartLine $cartLine, Closure $next): CartLine
    {
        // Adjust $cartLine->subTotal, ->unitPrice, ...

        return $next($cartLine);
    }
}

CartLineModifier also exposes calculating() and calculated() hooks. Register an instance with the Lunar\Core\Modifiers\CartLineModifiers collection, resolved from the container:

use App\Modifiers\MyCartLineModifier;
use Lunar\Core\Modifiers\CartLineModifiers;

public function boot(): void
{
    app(CartLineModifiers::class)->add(new MyCartLineModifier);
}

Lunar\Core\Modifiers\CartModifier and its CartModifiers collection are also registered in the container, but nothing in core currently runs a cart through them — only CartLineModifier (via CalculateLineSubtotal) and the shipping equivalent, ShippingModifier (see Extending Shipping), are wired into a live calculation step. Do not rely on CartModifier for cart-level hooks until it is dispatched somewhere in core.

Overriding order creation

Cart::createOrder() delegates to Contracts\Carts\CreatesOrder, which in turn runs the order through the pipeline configured in config/lunar/orders.php. See Extending Orders for the order-side pipeline and action contracts.

​Overview

​Cart action contracts

​Calculation pipelines

​Validators

​Cart line modifiers

​Overriding order creation

Overview

Cart action contracts

Calculation pipelines

Validators

Cart line modifiers

Overriding order creation