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\Facades\StorefrontSession;
use Lunar\Models\Product;
use Lunar\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)
            ->where('status', 'published')
            ->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 channel() and customerGroup() scopes ensure that a product not published to 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

Product names and descriptions are stored as attribute data. Use the attr() method to retrieve translated values.

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

In a Blade template:

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

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

Custom Attributes

Any custom attributes defined on the product type are accessible in the same way. 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.

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

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

The available conversion sizes (large, medium, zoom, etc.) 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

@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,
        'stock' => $variant->stock,
        'purchasable' => $variant->purchasable,
    ];
});

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 an optional currency and customer group. Pass these from StorefrontSession so the returned price matches the browsing context.

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

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

$pricing = Pricing::for($variant)
    ->currency(StorefrontSession::getCurrency())
    ->customerGroups(StorefrontSession::getCustomerGroups())
    ->get();

The get() method returns a PricingResponse with the following properties:

Property	Type	Description
`matched`	`Lunar\Models\Price`	The best matching price for the given context
`base`	`Lunar\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

Formatting Prices in Blade

@php
    $pricing = \Lunar\Facades\Pricing::for($product->variants->first())
        ->currency(\Lunar\Facades\StorefrontSession::getCurrency())
        ->customerGroups(\Lunar\Facades\StorefrontSession::getCustomerGroups())
        ->get();
    $price = $pricing->matched;
@endphp

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

@if($price->compare_price?->value)
    <p class="compare-price">
        <s>{{ $price->compare_price->formatted() }}</s>
    </p>
@endif

Tax-Inclusive and Tax-Exclusive Prices

If prices are stored inclusive of tax, use the helper methods on the Price model to show both:

<p>{{ $price->priceIncTax()->formatted() }} inc. tax</p>
<p>{{ $price->priceExTax()->formatted() }} 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->price->formatted() }}</td>
                </tr>
            @endforeach
        </tbody>
    </table>
@endif

Stock and Availability

Each variant tracks its own inventory. Display stock status to help customers make purchasing decisions.

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

@if($variant->purchasable === 'always')
    <span class="in-stock">Available</span>
@elseif($variant->stock > 0)
    <span class="in-stock">In Stock</span>
@else
    <span class="out-of-stock">Out of Stock</span>
@endif

The purchasable field on a variant controls its availability:

Value	Behavior
`always`	Can always be purchased, even when stock reaches zero (backorders allowed)
`in_stock`	Can only be purchased when `stock` is greater than zero

Use canBeFulfilledAtQuantity() to verify a specific quantity can be fulfilled before adding to cart:

$variant->canBeFulfilledAtQuantity(3); // Returns true or false

Adding to Cart

Lunar provides a CartSession facade for managing the active cart. Use it to add variants to the cart from the PDP.

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\Facades\CartSession;
use Lunar\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\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->attr('name') }}">
                <p>{{ $related->attr('name') }}</p>
            </a>
        @endforeach
    </div>
@endif

See the Products 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 Illuminate\Http\Request;
use Lunar\Facades\Pricing;
use Lunar\Facades\StorefrontSession;
use Lunar\Models\Product;
use Lunar\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();
        $currency = StorefrontSession::getCurrency();

        $product = Product::where('id', $url->element_id)
            ->where('status', 'published')
            ->channel($channel)
            ->customerGroup($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)
            ->currency($currency)
            ->customerGroups($customerGroups)
            ->get();

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

            return [
                'id' => $variant->id,
                'sku' => $variant->sku,
                'option_value_ids' => $variant->values->pluck('id')->sort()->values()->all(),
                'stock' => $variant->stock,
                'purchasable' => $variant->purchasable,
                'price' => $variantPricing->matched->price->formatted(),
                '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