Product Display Page

Overview

A Product Display Page (PDP) is the page where customers view a single product, select options like size or color, see pricing and images, and add items to their cart. This guide walks through building a PDP using Lunar’s models and facades. The examples below use standard Laravel controllers and Blade templates. The same concepts apply whether the storefront is built with Livewire, Inertia, or a headless API.

Resolving a Product from a URL

Lunar’s Url model provides slug-based lookups for products, removing the need to expose database IDs in URLs.

Define the Route

use App\Http\Controllers\ProductController;

Route::get('/products/{slug}', [ProductController::class, 'show'])->name('products.show');

Resolve the Product

use Lunar\Core\Facades\StorefrontSession;
use Lunar\Core\Models\Product;
use Lunar\Core\Models\Url;

class ProductController extends Controller
{
    public function show(string $slug)
    {
        $url = Url::where('slug', $slug)
            ->where('element_type', (new Product)->getMorphClass())
            ->firstOrFail();

        $channel = StorefrontSession::getChannel();
        $customerGroups = StorefrontSession::getCustomerGroups();

        $product = Product::where('id', $url->element_id)
            ->whereVisible()
            ->channel($channel)
            ->customerGroup($customerGroups)
            ->with([
                'variants.prices.currency',
                'variants.values.option',
                'variants.images',
                'media',
                'brand',
                'productOptions.values',
            ])
            ->firstOrFail();

        return view('products.show', compact('product'));
    }
}

Eager loading relationships in a single query avoids N+1 performance issues. The with() call above loads everything needed to render the full PDP.

The whereVisible() scope restricts the query to products in the published state, and the channel()/customerGroup() scopes ensure that a product not scheduled for the current channel or customer group returns a 404 rather than rendering. See the Storefront Session reference for how to manage these values.

Displaying Product Information

Product Name and Description

A product’s name, description, and short_description are real, translatable database columns. Use the translate() method to retrieve them for the current locale.

$product->translate('name');        // Returns the name for the current locale
$product->translate('description'); // Returns the description for the current locale

In a Blade template:

<h1>{{ $product->translate('name') }}</h1>
<div>{!! $product->translate('description') !!}</div>

@if($product->brand)
    <p>{{ $product->brand->name }}</p>
@endif

Custom Attributes

Any custom attributes defined on the product type are accessible with the attr() method. For example, if the product type includes a “Material” attribute:

$product->attr('material'); // e.g. "Premium Leather"

Product Images

Lunar uses Spatie MediaLibrary for image management. Products store images in the images media collection, with zoom, large, and medium conversions registered by default.

{{-- Primary / thumbnail image --}}
<img src="{{ $product->getFirstMediaUrl('images', 'large') }}" alt="{{ $product->translate('name') }}">

{{-- All product images --}}
<div class="gallery">
    @foreach($product->getMedia('images') as $image)
        <img
            src="{{ $image->getUrl('medium') }}"
            alt="{{ $image->getCustomProperty('alt', $product->translate('name')) }}"
        >
    @endforeach
</div>

The available conversion sizes depend on the media definitions configured in config/lunar/media.php. See the Media reference for details on customizing conversions.

Variant Selection

Most products have at least one variant. When a product offers multiple variants (different sizes, colors, etc.), the storefront needs to let customers select the variant they want.

Understanding the Data Structure

Each variant is associated with one or more ProductOptionValue records. For example, a T-shirt might have:

Product Options: Color, Size
Product Option Values: Blue, Red (for Color); S, M, L (for Size)
Variants: Blue/S, Blue/M, Blue/L, Red/S, Red/M, Red/L

Building an Option Selector

Option and value names are plain translatable fields (not attribute data), so they are read with translate().

@foreach($product->productOptions as $option)
    <div>
        <label>{{ $option->translate('name') }}</label>

        <select name="options[{{ $option->id }}]">
            @foreach($option->values as $value)
                <option value="{{ $value->id }}">
                    {{ $value->translate('name') }}
                </option>
            @endforeach
        </select>
    </div>
@endforeach

Mapping Option Values to Variants

To determine which variant corresponds to a given set of option selections, build a lookup map and pass it to the frontend.

$variantOptionMap = $product->variants->map(function ($variant) {
    return [
        'id' => $variant->id,
        'option_value_ids' => $variant->values->pluck('id')->sort()->values()->all(),
        'sku' => $variant->sku,
        'enabled' => $variant->enabled,
        'selling_policy' => $variant->selling_policy->value,
        'stock_available' => $variant->stock_available,
    ];
});

Pass this as JSON to JavaScript for client-side variant resolution:

<script>
    const variants = @json($variantOptionMap);

    function findVariant(selectedValueIds) {
        const sorted = [...selectedValueIds].sort((a, b) => a - b);

        return variants.find(variant => {
            return JSON.stringify(variant.option_value_ids) === JSON.stringify(sorted);
        });
    }
</script>

Single-Variant Products

When a product has only one variant, option selectors are unnecessary. Handle this in the template:

@if($product->variants->count() > 1)
    {{-- Show option selectors --}}
@endif

<input type="hidden" name="variant_id" value="{{ $product->variants->first()->id }}">

Pricing

Pricing in Lunar is resolved through the Pricing facade, which accounts for the current currency, customer group, and quantity.

Displaying the Price

The Pricing facade accepts a resolved StorefrontContext, which carries the currency and customer groups for the current browsing session, so the returned price matches the browsing context. StorefrontSession::context() builds that context from the active session.

use Lunar\Core\Facades\Pricing;
use Lunar\Core\Facades\StorefrontSession;

$variant = $product->variants->first();

$pricing = Pricing::for($variant)
    ->using(StorefrontSession::context())
    ->get();

The get() method returns a Lunar\Core\DataObjects\PricingResponse with the following properties:

Property	Type	Description
`matched`	`Lunar\Core\Models\Price`	The best matching price for the given context
`base`	`Lunar\Core\Models\Price`	The base price (min quantity of 1, no customer group)
`priceBreaks`	`Collection`	All available quantity break prices
`customerGroupPrices`	`Collection`	Prices specific to customer groups

Each of matched/base/an entry in priceBreaks is a Price model. Its price and list_price columns are plain integers in the currency’s lowest denomination; format them with the model’s own format() method, or resolve tax-aware values with priceIncTax(), priceExTax(), and listPriceIncTax().

Formatting Prices in Blade

@php
    $pricing = \Lunar\Core\Facades\Pricing::for($product->variants->first())
        ->using(\Lunar\Core\Facades\StorefrontSession::context())
        ->get();
    $price = $pricing->matched;
@endphp

<p class="price">
    {{ $price->format('price') }}
</p>

@if($price->list_price)
    <p class="compare-price">
        <s>{{ $price->format('list_price') }}</s>
    </p>
@endif

list_price is the list price (RRP) shown for comparison — show it struck through when it is set.

Tax-Inclusive and Tax-Exclusive Prices

If prices need to be shown both inclusive and exclusive of tax, use the helper methods on the Price model, which each return a PriceValue:

<p>{{ $price->priceIncTax()->format() }} inc. tax</p>
<p>{{ $price->priceExTax()->format() }} ex. tax</p>

See the Pricing reference for more on configuring whether prices are stored inclusive or exclusive of tax.

Price Breaks

If the product offers quantity-based pricing, display the available tiers:

@if($pricing->priceBreaks->count() > 1)
    <table>
        <thead>
            <tr>
                <th>Quantity</th>
                <th>Price</th>
            </tr>
        </thead>
        <tbody>
            @foreach($pricing->priceBreaks as $break)
                <tr>
                    <td>{{ $break->min_quantity }}+</td>
                    <td>{{ $break->format('price') }}</td>
                </tr>
            @endforeach
        </tbody>
    </table>
@endif

Stock and Availability

Each variant tracks its own inventory through a set of stock rollup columns (stock_on_hand, stock_available, stock_reserved, and so on), and an enabled flag gates whether it can be sold at all.

@php
    $variant = $product->variants->first();
@endphp

@if(! $variant->enabled)
    <span class="out-of-stock">Unavailable</span>
@elseif($variant->canBeFulfilledAtQuantity(1))
    <span class="in-stock">In Stock</span>
@else
    <span class="out-of-stock">Out of Stock</span>
@endif

The selling_policy field on a variant is a Lunar\Core\Enums\SellingPolicy case that controls how it may be sold relative to its stock:

Case	Value	Behavior
`SellingPolicy::Always`	`always`	Can always be purchased, even when stock reaches zero (backorders allowed)
`SellingPolicy::InStock`	`in_stock`	Can only be purchased up to `stock_available`
`SellingPolicy::InStockOrOnBackorder`	`in_stock_or_on_backorder`	Can be purchased up to `stock_available` plus the `backorder` allowance

Use canBeFulfilledAtQuantity() to verify a specific quantity can be fulfilled before adding to cart, and getTotalInventory() to read the effective sellable quantity under the current policy:

$variant->canBeFulfilledAtQuantity(3); // Returns true or false
$variant->getTotalInventory();         // Effective sellable quantity for the current policy

Adding to Cart

Lunar provides a CartSession facade for managing the active cart. The Cart model exposes an add() verb that the storefront calls directly.

The Add-to-Cart Form

<form method="POST" action="{{ route('cart.add') }}">
    @csrf
    <input type="hidden" name="variant_id" value="{{ $product->variants->first()->id }}">

    <label for="quantity">Quantity</label>
    <input type="number" name="quantity" id="quantity" value="1" min="1">

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

The Controller

use Lunar\Core\Facades\CartSession;
use Lunar\Core\Models\ProductVariant;

class CartController extends Controller
{
    public function add(Request $request)
    {
        $request->validate([
            'variant_id' => 'required|exists:lunar_product_variants,id',
            'quantity' => 'required|integer|min:1',
        ]);

        $variant = ProductVariant::findOrFail($request->variant_id);

        $cart = CartSession::current();

        $cart->add($variant, $request->quantity);

        return redirect()->back()->with('message', 'Item added to cart.');
    }
}

The Route

Route::post('/cart/add', [CartController::class, 'add'])->name('cart.add');

Lunar supports product associations for cross-sells, upsells, and alternate products. Display these on the PDP to encourage additional purchases.

use Lunar\Core\Models\ProductAssociation;

$crossSells = $product->associations()
    ->crossSell()
    ->with('target.variants.prices.currency', 'target.media')
    ->get()
    ->pluck('target');

$upSells = $product->associations()
    ->upSell()
    ->with('target.variants.prices.currency', 'target.media')
    ->get()
    ->pluck('target');

@if($crossSells->isNotEmpty())
    <h2>You might also like</h2>
    <div class="product-grid">
        @foreach($crossSells as $related)
            <a href="{{ route('products.show', $related->defaultUrl?->slug) }}">
                <img src="{{ $related->getFirstMediaUrl('images', 'medium') }}" alt="{{ $related->translate('name') }}">
                <p>{{ $related->translate('name') }}</p>
            </a>
        @endforeach
    </div>
@endif

See the Associations reference for more on association types.

Variant-Specific Images

When variants have their own images (for example, showing a different image per color), swap the displayed image based on the selected variant.

$variantImageMap = $product->variants->mapWithKeys(function ($variant) use ($product) {
    $thumbnail = $variant->getThumbnail();

    return [
        $variant->id => $thumbnail
            ? $thumbnail->getUrl('large')
            : $product->getFirstMediaUrl('images', 'large'),
    ];
});

Pass this map to JavaScript alongside the variant option map:

<script>
    const variantImages = @json($variantImageMap);

    function onVariantChange(variantId) {
        if (variantImages[variantId]) {
            document.querySelector('.product-image').src = variantImages[variantId];
        }
    }
</script>

Putting It All Together

Here is a complete controller that prepares all the data a PDP needs:

<?php

namespace App\Http\Controllers;

use Lunar\Core\Facades\Pricing;
use Lunar\Core\Facades\StorefrontSession;
use Lunar\Core\Models\Product;
use Lunar\Core\Models\Url;

class ProductController extends Controller
{
    public function show(string $slug)
    {
        $url = Url::where('slug', $slug)
            ->where('element_type', (new Product)->getMorphClass())
            ->firstOrFail();

        $context = StorefrontSession::context();

        $product = Product::where('id', $url->element_id)
            ->whereVisible()
            ->channel($context->channel)
            ->customerGroup($context->customerGroups)
            ->with([
                'variants.prices.currency',
                'variants.values.option',
                'variants.images',
                'media',
                'brand',
                'productOptions.values',
                'associations.target.variants.prices.currency',
                'associations.target.media',
            ])
            ->firstOrFail();

        $defaultVariant = $product->variants->first();

        $pricing = Pricing::for($defaultVariant)
            ->using($context)
            ->get();

        $variantOptionMap = $product->variants->map(function ($variant) use ($context) {
            $variantPricing = Pricing::for($variant)
                ->using($context)
                ->get();

            return [
                'id' => $variant->id,
                'sku' => $variant->sku,
                'option_value_ids' => $variant->values->pluck('id')->sort()->values()->all(),
                'enabled' => $variant->enabled,
                'stock_available' => $variant->stock_available,
                'price' => $variantPricing->matched->format('price'),
                'image' => $variant->getThumbnailImage(),
            ];
        });

        $crossSells = $product->associations
            ->where('type', 'cross-sell')
            ->pluck('target');

        return view('products.show', [
            'product' => $product,
            'defaultVariant' => $defaultVariant,
            'pricing' => $pricing,
            'variantOptionMap' => $variantOptionMap,
            'crossSells' => $crossSells,
        ]);
    }
}

Next Steps

Review the Products reference for the full list of model fields, relationships, and scopes.
Review the Pricing reference for custom price formatters and additional formatting options.
Review the Media reference for image conversion configuration.
Review the Storefront Session reference to manage channel, currency, and customer group context.

​Overview

​Resolving a Product from a URL

​Define the Route

​Resolve the Product

​Displaying Product Information

​Product Name and Description

​Custom Attributes

​Product Images

​Variant Selection

​Understanding the Data Structure

​Building an Option Selector

​Mapping Option Values to Variants

​Single-Variant Products

​Pricing

​Displaying the Price

​Formatting Prices in Blade

​Tax-Inclusive and Tax-Exclusive Prices

​Price Breaks

​Stock and Availability

​Adding to Cart

​The Add-to-Cart Form

​The Controller

​The Route

​Related Products

​Variant-Specific Images

​Putting It All Together

​Next Steps

Overview

Resolving a Product from a URL

Define the Route

Resolve the Product

Displaying Product Information

Product Name and Description

Custom Attributes

Product Images

Variant Selection

Understanding the Data Structure

Building an Option Selector

Mapping Option Values to Variants

Single-Variant Products

Pricing

Displaying the Price

Formatting Prices in Blade

Tax-Inclusive and Tax-Exclusive Prices

Price Breaks

Stock and Availability

Adding to Cart

The Add-to-Cart Form

The Controller

The Route

Related Products

Variant-Specific Images

Putting It All Together

Next Steps