Lunar Livewire Starter Kit

https://github.com/lunarphp/livewire-starter-kit
Admin
A starter kit providing a reference example of a classic e-commerce store to demonstrate...
Tokens:44,479
Snippets:422
Trust Score:9.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Set up environment and start Docker containers

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/README.md

Copy the Docker environment example file and start the demo store using Docker Compose. Requires Docker installed locally. The demo store will be available at http://localhost after the containers are up.

```bash
cp .env.docker.example .env
docker-compose up
```

--------------------------------

### Set Up Lunar After Lando Start

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/LANDO.md

Runs the necessary setup commands after starting Lando: installs dependencies, copies the environment file, runs migrations, installs Lunar, seeds the database, and links storage.

```sh
lando composer install
cp .env.lando.example .env
lando artisan migrate
lando artisan lunar:install
lando artisan db:seed
lando artisan storage:link
```

--------------------------------

### Start Lando Environment

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/LANDO.md

Initializes the Lando development environment. Requires Lando to be installed beforehand.

```sh
lando start
```

--------------------------------

### Example: rules() drives validation for both save actions

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Shows how to instantiate CheckoutPage and call rules() to get the validation rules array. The resulting array contains keys like 'shipping.first_name', 'billing.city', 'shippingIsBilling', and 'chosenShipping'.

```php
// Example: rules() drives validation for both save actions
$rules = (new CheckoutPage)->rules();
// contains: 'shipping.first_name' => 'required', 'billing.city' => 'required',
//           'shippingIsBilling' => 'boolean', 'chosenShipping' => 'required'
```

--------------------------------

### Example: GET /checkout with payment_intent triggers mount()

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Illustrates a GET request to /checkout with payment_intent and payment_intent_client_secret parameters, which causes mount() to attempt Stripe payment confirmation before rendering.

```php
// GET /checkout?payment_intent=pi_123&payment_intent_client_secret=xxx
// -> mount() attempts to confirm the Stripe payment before rendering
```

--------------------------------

### Basic usage of <x-product-price> with product and variant

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-price.md

Blade usage examples for the component. Shows basic usage with a product, explicit variant usage, and how the component view exposes $price for formatting.

```blade
{{-- Basic usage --}}
<x-product-price :product="$product" />

{{-- With an explicit variant (e.g. the selected option variant) --}}
<x-product-price :variant="$this->variant" />

{{-- The component view exposes $price --}}
{{ $price?->price->formatted() }}
```

--------------------------------

### GET /

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/endpoints.md

Renders the home page with a sale collection and a random collection. No authentication required.

```APIDOC
## GET /

### Description
Renders the home page with a sale collection and a random collection.

### Method
GET

### Endpoint
/

### Parameters
None

### Response
#### Success Response (200)
HTML page (view: livewire.home, layout: layouts.storefront)

#### Response Example
(HTML content)
```

--------------------------------

### GET /products/{slug}

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/endpoints.md

Displays a product page based on the provided slug. Returns 404 if no default URL exists for the slug.

```APIDOC
## GET /products/{slug}

### Description
Displays a product page based on the provided slug. Returns 404 if no default URL exists for the slug.

### Method
GET

### Endpoint
/products/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - URL slug of the product

### Response
#### Success Response (200)
HTML page (view: livewire.product-page)

#### Error Response (404)
HTML error page when no default URL exists for the slug
```

--------------------------------

### ProductPrice constructor resolving matched price

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-price.md

Constructor for the ProductPrice component. Resolves the variant as $variant ?: $product->variants->first(), runs it through Lunar\Facades\Pricing::for(...)->get(), and stores the matched Price on $this->price. Throws a PHP Error when both $product and $variant are null; undefined behavior when the product has no variants.

```php
/**
 * Create a new component instance.
 *
 * @return void
 */
public function __construct($product = null, $variant = null)
{
        $this->price = Pricing::for(
            $variant ?: $product->variants->first()
        )->get()->matched;
}
```

--------------------------------

### Eager loading for downstream computed properties

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/fetches-urls.md

Non-trivial example showing how eager loading drives computed properties downstream. After this call, $this->url->element is the fully loaded Product with media, base prices, currency, priceable, and option relations.

```php
// Non-trivial: eager loading drives the computed properties downstream
$this->url = $this->fetchUrl(
    $slug,
    (new Product)->getMorphClass(),
    [
        'element.media',
        'element.variants.basePrices.currency',
        'element.variants.basePrices.priceable',
        'element.variants.values.option',
    ]
);
// $this->url->element is now the fully loaded Product
```

--------------------------------

### Route definition and Blade link for product.view

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-page.md

Route binding for the ProductPage component at GET /products/{slug} with name 'product.view'. The Blade link uses the product's default URL slug.

```php
// Route usage
Route::get('/products/{slug}', ProductPage::class)->name('product.view');

// Blade link: <a href="{{ route('product.view', $product->defaultUrl->slug) }}">
```

--------------------------------

### GET /search

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/endpoints.md

Performs a search using the provided term and displays paginated results. Returns no results when Scout driver is null.

```APIDOC
## GET /search

### Description
Performs a search using the provided term and displays paginated results. Returns no results when Scout driver is null.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **term** (string) - Optional - Search term

### Response
#### Success Response (200)
HTML page (view: livewire.search-page) with search results paginated by 50
```

--------------------------------

### GET /checkout/success

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/endpoints.md

Displays the success page when the session cart has a completed order. Redirects to home otherwise.

```APIDOC
## GET /checkout/success

### Description
Displays the success page when the session cart has a completed order. Redirects to home otherwise.

### Method
GET

### Endpoint
/checkout/success

### Parameters
None

### Response
#### Success Response (200)
HTML page (view: livewire.checkout-success-page) when the session cart has a completedOrder

#### Redirect Response (302)
Redirect to / otherwise
```

--------------------------------

### GET /checkout

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/endpoints.md

Displays the checkout page when a cart exists. Redirects to home if no cart, and to success page after payment authorization.

```APIDOC
## GET /checkout

### Description
Displays the checkout page when a cart exists. Redirects to home if no cart, and to success page after payment authorization.

### Method
GET

### Endpoint
/checkout

### Parameters
#### Query Parameters
- **payment_intent** (string) - Optional - Stripe PaymentIntent ID
- **payment_intent_client_secret** (string) - Optional - Stripe client secret

### Response
#### Success Response (200)
HTML page (view: livewire.checkout-page, layout: layouts.checkout) when a cart exists

#### Redirect Response (302)
Redirect to / when no cart exists

#### Redirect Response (302)
Redirect to checkout-success.view after successful payment authorization
```

--------------------------------

### GET /collections/{slug}

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/endpoints.md

Displays a collection page based on the provided slug. Returns 404 if no matching collection URL exists.

```APIDOC
## GET /collections/{slug}

### Description
Displays a collection page based on the provided slug. Returns 404 if no matching collection URL exists.

### Method
GET

### Endpoint
/collections/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - URL slug of the collection

### Response
#### Success Response (200)
HTML page (view: livewire.collection-page)

#### Error Response (404)
HTML error page when no matching collection URL exists
```

--------------------------------

### GET /api/user

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/endpoints.md

Returns the authenticated user's data as JSON. Requires a valid Sanctum bearer token in the Authorization header.

```APIDOC
## GET /api/user

### Description
Returns the authenticated user's data as JSON. Requires a valid Sanctum bearer token in the Authorization header.

### Method
GET

### Endpoint
/api/user

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **id** (integer) - User ID
- **name** (string) - User name
- **email** (string) - User email
- **email_verified_at** (timestamp) - Email verification timestamp
- **created_at** (timestamp) - Creation timestamp
- **updated_at** (timestamp) - Update timestamp

#### Response Example
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "email_verified_at": "2023-01-01T00:00:00.000000Z",
  "created_at": "2023-01-01T00:00:00.000000Z",
  "updated_at": "2023-01-01T00:00:00.000000Z"
}

#### Error Response (401)
Unauthenticated request.
```

--------------------------------

### In-component form with per-field errors

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-address.md

Example form inside the component that submits via wire:submit="save" and displays per-field validation errors using @error directives.

```blade
{{-- In-component form with per-field errors --}}
<form wire:submit="save">
    <input type="text" wire:model="address.first_name" />
    @error('address.first_name') <span>{{ $message }}</span> @enderror
    <input type="text" wire:model="address.postcode" />
    @error('address.postcode') <span>{{ $message }}</span> @enderror
    <button type="submit">Save</button>
</form>
```

--------------------------------

### Header search form using route search.view

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/search-page.md

Blade form in components/header/search.blade.php that submits a GET request to the search route with the term query parameter. The input value is bound to the $term property.

```blade
{{-- Usage: the header search box (components/header/search.blade.php) --}}
<form action="{{ route('search.view') }}">
    <input type="search" name="term" value="{{ $term }}" />
    <button type="submit">Search</button>
</form>
```

--------------------------------

### mount($slug) method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-page.md

Resolves the product by slug via fetchUrl and initializes selectedOptionValues. Throws NotFoundHttpException (404) when the slug has no default URL.

```php
public function mount($slug): void
```

--------------------------------

### mount() method with fetchUrl and abort(404)

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/collection-page.md

Resolves the collection from the URL slug using fetchUrl() with eager loads for thumbnail, product variants' base prices, and default URLs. Aborts with a 404 if no default URL matches.

```php
public function mount(string $slug): void
{
    $this->url = $this->fetchUrl(
        $slug,
        (new CollectionModel)->getMorphClass(),
        [
            'element.thumbnail',
            'element.products.variants.basePrices',
            'element.products.defaultUrl',
        ]
    );

    if (! $this->url) {
        abort(404);
    }
}
```

--------------------------------

### mount() method

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/shipping-options.md

Pre-selects the shipping option from the cart's stored shipping_option identifier.

```php
public function mount(): void
{
    // ...
}
```

--------------------------------

### __construct($product = null, $variant = null)

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-price.md

Constructor for the ProductPrice component. Resolves the matched price for a product or variant and stores it in the public $price property.

```APIDOC
## Constructor: __construct($product = null, $variant = null)

### Description
Creates a new component instance and resolves the matched price for the given product or variant.

### Method
Constructor

### Parameters
- **$product** (mixed, expected `Lunar\Models\Product`) - Optional - Product whose first variant is priced when $variant is not given.
- **$variant** (mixed, expected `Lunar\Models\ProductVariant`) - Optional - Explicit variant to price; takes precedence over $product.

### Behavior
Resolves the variant as `$variant ?: $product->variants->first()`, runs it through `Lunar\Facades\Pricing::for(...)->get()`, and stores `->matched` (the matched `Lunar\Models\Price`) on `$this->price`.

### Returns
void (constructor)

### Throws
PHP `Error` when both $product and $variant are null (member access on null); undefined behavior when the product has no variants (`Pricing::for(null)`).

### Example
```blade
{{-- Basic usage --}}
<x-product-price :product="$product" />

{{-- With an explicit variant (e.g. the selected option variant) --}}
<x-product-price :variant="$this->variant" />

{{-- The component view exposes $price --}}
{{ $price?->price->formatted() }}
```
```

--------------------------------

### render() method

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/shipping-options.md

Returns the view for the component.

```php
public function render(): View
{
    return view('livewire.components.shipping-options');
}
```

--------------------------------

### RouteServiceProvider boot(): Load API and web routes

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/service-providers.md

Loads routes/api.php under the 'api' middleware group and prefix, and routes/web.php under the 'web' middleware group.

```php
public function boot(): void
{
    $this->configureRateLimiting();

    $this->routes(function () {
        Route::middleware('api')
            ->prefix('api')
            ->group(base_path('routes/api.php'));

        Route::middleware('web')
            ->group(base_path('routes/web.php'));
    });
}
```

--------------------------------

### Switch to CustomProduct via ModelManifest

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/models.md

Uncomment in boot() to swap the Product contract to App\Models\CustomProduct, which uses the same 'products' table.

```php
// To switch the app to the custom model, uncomment in boot():
\Lunar\Facades\ModelManifest::replace(
    \Lunar\Models\Contracts\Product::class,
    \App\Models\CustomProduct::class,
);
```

--------------------------------

### render(): View

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-price.md

Renders the component's view. Returns the view instance for the 'components.product-price' view.

```APIDOC
## Method: render(): View

### Description
Returns the view for the component.

### Method
render

### Parameters
None.

### Returns
`Illuminate\View\View`

### Example
```php
public function render(): View
{
    return view('components.product-price');
}
```
```

--------------------------------

### mount() guard implementation

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-success-page.md

Full mount() method that resolves the cart, redirects to '/' if no completed order, sets the order, and forgets the cart session. This is the only protection for the page.

```php
// Non-trivial: the guard in mount() is the only protection for this page.
// A visitor who lands here without a completed order (e.g. refreshed
// after CartSession::forget(), or navigated directly) is sent back home:
public function mount(): void
{
    $this->cart = CartSession::current();
    if (! $this->cart || ! $this->cart->completedOrder) {
        $this->redirect('/');
        return;
    }
    $this->order = $this->cart->completedOrder;
    CartSession::forget();
}
```

--------------------------------

### mount(): void method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-success-page.md

Declares the mount method for the CheckoutSuccessPage Livewire component. Called automatically when the component is instantiated.

```php
public function mount(): void
```

--------------------------------

### save() method

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/shipping-options.md

Validates, sets the shipping option, and dispatches the selectedShippingOption event.

```php
public function save(): void
{
    $this->validate();

    $option = $this->shippingOptions->first(fn ($option) => $option->getIdentifier() == $this->chosenOption);

    CartSession::setShippingOption($option);

    $this->dispatch('selectedShippingOption');
}
```

--------------------------------

### determineCheckoutStep(): void

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Derives the current checkout step from cart state: shipping address exists → step 2 (or 3 if a shipping option is selected); billing address exists → step 4. Picks a default chosenShipping from shippingOptions when needed.

```APIDOC
## determineCheckoutStep(): void

### Description
Derives `currentStep` from cart state: shipping address exists → step 2 (or 3 if a shipping option is selected); billing address exists → step 4. Picks a default `chosenShipping` from `shippingOptions` when needed.

### Method
`determineCheckoutStep`

### Returns
`void`
```

--------------------------------

### rules() method

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/shipping-options.md

Returns validation rules for the chosenOption property.

```php
public function rules(): array
{
    return ['chosenOption' => 'required'];
}
```

--------------------------------

### DatabaseSeeder run method calling all seeders

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/seeders.md

Orchestrates the seeding pipeline by calling each seeder in order. Order is significant: collections, attributes, and taxes must exist before products, and products before customers and orders.

```php
public function run(): void
{
    $this->call(CollectionSeeder::class);
    $this->call(AttributeSeeder::class);
    $this->call(TaxSeeder::class);
    $this->call(ProductSeeder::class);
    $this->call(CustomerSeeder::class);
    $this->call(ShippingSeeder::class);
    $this->call(OrderSeeder::class);
}
```

--------------------------------

### AppServiceProvider boot(): Add ShippingModifier and replace Product contract

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/service-providers.md

Adds the shipping modifier to the pipeline and replaces the Lunar Product contract implementation with App\Models\Product. The commented line shows an alternative custom product class.

```php
public function boot(ShippingModifiers $shippingModifiers): void
{
    $shippingModifiers->add(
        ShippingModifier::class
    );

    \Lunar\Facades\ModelManifest::replace(
        \Lunar\Models\Contracts\Product::class,
        \App\Models\Product::class,
        // \App\Models\CustomProduct::class,
    );
}
```

--------------------------------

### Run database seeders with artisan db:seed

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/seeders.md

Use `php artisan db:seed` to run the DatabaseSeeder (all seeders) or `--class=ProductSeeder` to run a single seeder. The Docker entry point runs `php artisan db:seed` during first-boot provisioning.

```bash
php artisan db:seed                       # DatabaseSeeder (all)
php artisan db:seed --class=ProductSeeder # single seeder
```

--------------------------------

### getImageProperty() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-page.md

Computed property returning the current product image, resolved in priority order: variant images first, then media flagged primary, then first image. Accessible as $this->image.

```php
public function getImageProperty(): ?Media
```

--------------------------------

### getShippingOptionsProperty() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Returns the available shipping options for the current cart via ShippingManifest::getOptions.

```php
public function getShippingOptionsProperty(): Collection
```

--------------------------------

### getImagesProperty() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-page.md

Computed property returning all media items of the product ordered by their media-library order_column. Accessible as $this->images.

```php
public function getImagesProperty(): Collection
```

--------------------------------

### saveShippingOption(): void

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Finds the ShippingOption whose getIdentifier() equals $this->chosenShipping, calls CartSession::setShippingOption($option), refreshes the cart, and recomputes the step.

```APIDOC
## saveShippingOption(): void

### Description
Finds the `ShippingOption` whose `getIdentifier()` equals `$this->chosenShipping`, calls `CartSession::setShippingOption($option)`, refreshes the cart, and recomputes the step.

### Method
`saveShippingOption`

### Returns
`void`

### Throws
- `ValidationException` when `chosenShipping` is empty (rule `required`).
```

--------------------------------

### Blade usage and option list

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/shipping-options.md

Blade template for rendering the component and the option list with save button.

```blade
{{-- Usage --}}
<livewire:components.shipping-options />

{{-- Option list with save --}}
@foreach ($this->shippingOptions as $option)
    <label>
        <input type="radio" wire:model="chosenOption" value="{{ $option->getIdentifier() }}" />
        {{ $option->getDescription() }} — {{ $option->getPrice()->formatted() }}
    </label>
@endforeach
<button wire:click="save">Continue</button>
```

--------------------------------

### SearchPage render method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/search-page.md

Method signature for the render() method that returns view('livewire.search-page'). The full implementation is not shown; only the signature is provided in the source.

```php
public function render(): View
```

--------------------------------

### SearchPage getResultsProperty method

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/search-page.md

Computed property that performs a Scout search over App\Models\Product and paginates results (50 per page). Accessible as $this->results in Blade. With default SCOUT_DRIVER=null the null engine returns an empty result set; with Meilisearch it returns matched products.

```php
public function getResultsProperty(): LengthAwarePaginator
{
    return Product::search($this->term)->paginate(50);
}
```

--------------------------------

### Blade usage pattern for option selectors and image

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-page.md

Usage pattern where option selectors update selectedOptionValues, and the variant/image follow. The select uses wire:model to bind to the selectedOptionValues array keyed by option id.

```blade
{{-- Usage pattern: option selectors update selectedOptionValues, variant/image follow --}}
<select wire:model="selectedOptionValues.{{ $option['option']->id }}">
    @foreach ($option['values'] as $value)
        <option value="{{ $value->id }}">{{ $value->translate('name') }}</option>
    @endforeach
</select>

<img src="{{ $this->image?->getUrl() }}" />
```

--------------------------------

### Usage in livewire/home.blade.php for saleCollection

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/home.md

Blade usage that checks if the sale collection exists and renders the <x-collection-sale> component with the collection.

```blade
{{-- Usage in livewire/home.blade.php --}}
@if ($this->saleCollection)
    <x-collection-sale :collection="$this->saleCollection" />
@endif
```

--------------------------------

### 404 error handling for unknown collection slug

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/collection-page.md

Illustrates that an unknown slug triggers abort(404) in mount(), resulting in a 404 response before rendering.

```php
// Error handling: an unknown slug produces a 404 before rendering
// GET /collections/does-not-exist -> 404 (abort(404) in mount)
```

--------------------------------

### getProductOptionsProperty() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-page.md

Computed property returning options grouped by product_option_id, each as ['option' => ProductOption, 'values' => Collection]. Accessible as $this->productOptions.

```php
public function getProductOptionsProperty(): Collection
```

--------------------------------

### getShippingOptionsProperty() method

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/shipping-options.md

Computed property returning available shipping options for the current cart.

```php
public function getShippingOptionsProperty(): Collection
{
    return ShippingManifest::getOptions(
        CartSession::current()
    );
}
```

--------------------------------

### getCountriesProperty() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Returns the two allowed shipping/billing countries (GBR, USA) as a Collection of Lunar\Models\Country.

```php
public function getCountriesProperty(): Collection
```

--------------------------------

### addToCart() method implementation

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/add-to-cart.md

Validates the quantity, checks stock availability, adds the purchasable to the cart via CartSession::manager()->add(), and dispatches the 'add-to-cart' browser event. If stock is insufficient, adds an error and returns without mutating the cart.

```php
public function addToCart(): void
{
    $this->validate();

    if ($this->purchasable->stock < $this->quantity) {
        $this->addError('quantity', 'The quantity exceeds the available stock.');

        return;
    }

    CartSession::manager()->add($this->purchasable, $this->quantity);
    $this->dispatch('add-to-cart');
}
```

--------------------------------

### getSaleCollectionImagesProperty()

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/home.md

Returns null when there is no sale collection. Otherwise takes up to 4 random products from the sale collection, maps them to their thumbnail, and chunks the result into pairs (Collection::chunk(2)) for a 2-column display. No declared return type.

```php
public function getSaleCollectionImagesProperty()
{
    if (! $this->getSaleCollectionProperty()) {
        return null;
    }

    $collectionProducts = $this->getSaleCollectionProperty()
        ->products()->inRandomOrder()->limit(4)->get();

    $saleImages = $collectionProducts->map(function ($product) {
        return $product->thumbnail;
    });

    return $saleImages->chunk(2);
}
```

--------------------------------

### saveAddress(string $type): void

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Validates the address rules for the given type ('shipping' or 'billing'), then sets the corresponding address on the cart. For shipping with shippingIsBilling true, it copies the shipping address to billing. Finally calls determineCheckoutStep().

```APIDOC
## saveAddress(string $type): void

### Description
Validates the address rules for `$type`, then calls `$this->cart->setBillingAddress($address)` / `$this->cart->setShippingAddress($address)`. For `shipping` with `shippingIsBilling` true, it copies the shipping address to billing (fills an existing billing address with shipping data, or creates one from fillable attributes). Finally calls `determineCheckoutStep()`.

### Method
`saveAddress`

### Parameters
- **$type** (string) - Required - `'shipping'` or `'billing'`

### Returns
`void`

### Throws
- `ValidationException` when the address rules fail.

### Usage Example
```blade
{{-- Shipping form submits with the shipping/billing copy flag --}}
<form wire:submit="saveAddress('shipping')">
    <input type="text" wire:model="shipping.first_name" />
    <input type="checkbox" wire:model="shippingIsBilling" />
    <button type="submit">Continue</button>
</form>
```

### Error Handling
```php
// Error handling: Livewire fills the component's error bag
// and the blade form can render messages per field
@error('shipping.postcode') <span>{{ $message }}</span> @enderror
```
```

--------------------------------

### Guarded usage of <x-product-price> with variant check

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-price.md

Blade usage that only renders the component when a variant exists, mirroring the guard the source lacks. Falls back to a 'Price on request' span otherwise.

```blade
{{-- Non-trivial: only render when a variant exists, mirroring the guard the source lacks --}}
@if ($product->variants->count())
    <x-product-price :product="$product" />
@else
    <span>Price on request</span>
@endif
```

--------------------------------

### getVariantProperty() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-page.md

Computed property returning the first product variant whose values ids are all contained in selectedOptionValues. Accessible as $this->variant.

```php
public function getVariantProperty(): ProductVariant
```

--------------------------------

### Blade usage of $this->collection with product links

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/collection-page.md

Shows how to display the collection name and link to products using the product.view route in the livewire/collection-page.blade.php view.

```blade
{{-- Usage in livewire/collection-page.blade.php — products link to product.view --}}
<h1>{{ $this->collection->translateAttribute('name') }}</h1>
@foreach ($this->collection->products as $product)
    <a href="{{ route('product.view', $product->defaultUrl->slug) }}">
        <x-product-card :product="$product" />
    </a>
@endforeach
```

--------------------------------

### Cart component handleAddToCart() method

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/cart.md

Listener for the add-to-cart event. Re-maps lines and sets linesVisible to true to open the drawer.

```php
public function handleAddToCart(): void
```

--------------------------------

### Usage in a Livewire component with mount

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/fetches-urls.md

Shows how to consume the trait in a Livewire component. The mount method calls fetchUrl with a morph class and eager loads 'element.variants.basePrices'. If no URL is found, abort(404) is called. The result is stored on the public $url property.

```php
use App\Traits\FetchesUrls;

class MyComponent extends Component
{
    use FetchesUrls;

    public function mount(string $slug): void
    {
        $this->url = $this->fetchUrl($slug, (new Product)->getMorphClass(), [
            'element.variants.basePrices',
        ]);

        if (! $this->url) {
            abort(404); // or handle gracefully
        }
    }
}
```

--------------------------------

### getProductProperty() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-page.md

Computed property returning $this->url->element, the Lunar\Models\Product resolved in mount(). Accessible as $this->product.

```php
public function getProductProperty(): Product
```

--------------------------------

### Results pagination and empty state in Blade

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/search-page.md

Blade template that iterates over $this->results, renders product cards, displays pagination links using Livewire's tailwind theme, and shows an empty state message when no products are found.

```blade
{{-- Results pagination uses Livewire's WithPagination tailwind theme --}}
@foreach ($this->results as $product)
    <x-product-card :product="$product" />
@endforeach
{{ $this->results->links() }}

{{-- Empty state when the null Scout engine is active or nothing matched --}}
@if ($this->results->isEmpty())
    <p>No products found for "{{ $term }}".</p>
@endif
```

--------------------------------

### Catch errors in consumer code (PHP and Blade)

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/errors.md

Shows how to handle 404 pages, Livewire validation, per-field Blade errors, and custom reporting in app/Exceptions/Handler.php. The validate() call throws ValidationException on failure. The reportable() closure can inspect Throwable instances, e.g., NotFoundHttpException.

```php
// 404 pages
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

// Livewire validation: handle in the component or via error bag
public function save()
{
    $validated = $this->validate(); // throws ValidationException on failure
}

// In Blade — surface per-field errors
@error('quantity')
    <span class="text-red-600">{{ $message }}</span>
@enderror

// Custom reporting in app/Exceptions/Handler.php
$this->reportable(function (Throwable $e) {
    // e.g. if ($e instanceof NotFoundHttpException) { ... }
});
```

--------------------------------

### determineCheckoutStep method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Public method that derives currentStep from cart state: shipping address exists → step 2 (or 3 if a shipping option is selected); billing address exists → step 4. Picks a default chosenShipping from shippingOptions when needed. Returns void.

```php
public function determineCheckoutStep(): void
```

--------------------------------

### Blade loop for saleCollectionImages

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/home.md

Blade template that iterates over the sale collection images (chunks of two) and renders them in a 2-column grid.

```blade
@foreach ($this->saleCollectionImages ?? [] as $chunk)
    <div class="grid grid-cols-2 gap-4">
        @foreach ($chunk as $image)
            <img src="{{ $image?->getUrl() }}" />
        @endforeach
    </div>
@endforeach
```

--------------------------------

### checkout method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Public method that authorizes payment and redirects to checkout-success.view. Both branches redirect to the success route; there is no error branch. Returns RedirectResponse via Livewire redirect().

```php
public function checkout()
```

--------------------------------

### RouteServiceProvider configureRateLimiting(): Define api rate limiter

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/service-providers.md

Defines the 'api' rate limiter: 60 requests per minute, keyed by authenticated user id or IP address.

```php
protected function configureRateLimiting(): void
{
    RateLimiter::for('api', function (Request $request) {
        return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
    });
}
```

--------------------------------

### checkout()

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Authorizes the payment for the cart and redirects to the checkout success view. Both branches redirect to the success route; there is no error branch.

```APIDOC
## checkout()

### Description
Authorizes `Payments::cart($this->cart)->withData(['payment_intent_client_secret' => ..., 'payment_intent' => ...])->authorize()`. If `$payment->success` → redirect to `checkout-success.view` and return. Otherwise falls through to the final `return redirect()->route('checkout-success.view');` — i.e. **both branches redirect to the success route**; there is no error branch.

### Method
`checkout`

### Returns
`RedirectResponse` (via Livewire `redirect()`).

### Usage Example
```blade
{{-- Offline payment path --}}
<form wire:submit="checkout">
    <button type="submit">Submit Order</button>
</form>
```
```

--------------------------------

### Product options shape — ProductPage::getProductOptionsProperty()

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/types.md

Each element of the returned Collection contains an option and its values. getProductOptionValuesProperty() returns flattened values; $selectedOptionValues maps option id to first value id.

```php
[
    'option' => $values->first()->option,   // Lunar\Models\ProductOption
    'values' => $values,                    // Collection of ProductOptionValue
]
```

--------------------------------

### Product search using replaced model

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/models.md

SearchPage uses the replaced Product model through Lunar's Product class, resolving to App\Models\Product.

```php
// SearchPage uses the replaced model through Lunar's Product class
return Product::search($this->term)->paginate(50); // resolves App\Models\Product
```

--------------------------------

### saveShippingOption method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Public method that finds the ShippingOption whose getIdentifier() equals chosenShipping, calls CartSession::setShippingOption, refreshes the cart, and recomputes the step. Throws ValidationException when chosenShipping is empty.

```php
public function saveShippingOption(): void
```

--------------------------------

### getShippingAddressProperty() method

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/shipping-options.md

Computed property returning the cart's shipping address.

```php
public function getShippingAddressProperty()
{
    return CartSession::getCart()->shippingAddress;
}
```

--------------------------------

### Route usage comment for checkout-success

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-success-page.md

Comment block describing the route usage and the guard behavior for direct visits to /checkout/success.

```php
// Route usage — the page itself guards against direct visits
// GET /checkout/success with no completed order -> 302 redirect to /
```

--------------------------------

### getProductOptionValuesProperty() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/product-page.md

Computed property returning every option value across all variants as a flat collection. Accessible as $this->productOptionValues.

```php
public function getProductOptionValuesProperty(): Collection
```

--------------------------------

### hydrate() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Refreshes the cart from CartSession::current() on every subsequent Livewire request to keep cart totals in sync.

```php
public function hydrate(): void
```

--------------------------------

### getCollectionsProperty() method

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/navigation.md

Computed property that returns all Lunar collections eager-loaded with their default URL, arranged as a nested tree using Kalnoy nested-set. Accessible as $this->collections.

```php
public function getCollectionsProperty()
{
    return Collection::with(['defaultUrl'])->get()->toTree();
}
```

--------------------------------

### Menu rendering blade template

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/navigation.md

Blade template that iterates over $this->collections to render menu links. Uses wire:navigate for SPA navigation and translates the collection name attribute.

```blade
{{-- Menu rendering (desktop + mobile both iterate $this->collections) --}}
@foreach ($this->collections as $collection)
    <a href="{{ route('collection.view', $collection->defaultUrl->slug) }}" wire:navigate>
        {{ $collection->translateAttribute('name') }}
    </a>
@endforeach
```

--------------------------------

### Route definition and Blade link for collection.view

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/collection-page.md

Shows the route that maps /collections/{slug} to CollectionPage and a Blade link using the route helper with the collection's default URL slug.

```php
// Route usage — Laravel passes the {slug} path segment into mount()
Route::get('/collections/{slug}', CollectionPage::class)->name('collection.view');

// Blade link from navigation:
// <a href="{{ route('collection.view', $collection->defaultUrl->slug) }}">...</a>
```

--------------------------------

### fetchUrl method implementation

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/fetches-urls.md

Resolves a slug to a default Lunar Url model for a given element type. Returns the first default URL or null when none matches. The $type parameter is a morph class string (e.g., (new Product)->getMorphClass()) to scope the query to one element kind. Callers abort(404) on null.

```php
/**
 * Fetch a url model.
 *
 * @param  string  $slug
 * @param  string  $type
 * @param  array  $eagerLoad
 */
public function fetchUrl($slug, $type, $eagerLoad = []): ?Url
{
    return Url::whereElementType($type)
        ->whereDefault(true)
        ->whereSlug($slug)
        ->with($eagerLoad)->first();
}
```

--------------------------------

### Blade empty state when collection is null

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/collection-page.md

Alternative to abort(404): renders an empty state message when the collection is null.

```blade
{{-- Alternative to abort(404): render an empty state when the collection is null --}}
@if ($this->collection)
    {{-- collection content --}}
@else
    <p>This collection could not be found.</p>
@endif
```

--------------------------------

### User factory usage with Sanctum token

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/models.md

Creates a user via the factory, optionally unverified, and generates a Sanctum API token. The default password is 'password'.

```php
use App\Models\User;
$user = User::factory()->create();            // password: 'password'
$guest = User::factory()->unverified()->create();
$token = $user->createToken('api')->plainTextToken; // via HasApiTokens (Sanctum)
```

--------------------------------

### saveAddress method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Public method that validates address rules for the given type ('shipping' or 'billing'), then calls setBillingAddress or setShippingAddress on the cart. For shipping with shippingIsBilling true, it copies the shipping address to billing. Finally calls determineCheckoutStep(). Throws ValidationException when address rules fail.

```php
public function saveAddress(string $type): void
```

--------------------------------

### Livewire component usage on product page

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/add-to-cart.md

Blade directive to render the AddToCart component, passing the matched variant as the 'purchasable' property.

```blade
{{-- Usage (product page) — passes the matched variant --}}
@livewire('components.add-to-cart', ['purchasable' => $this->variant])
```

--------------------------------

### rules() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-address.md

Defines validation rules for address fields. Required fields: first_name, last_name, line_one, country_id, city, postcode. Nullable fields: company_name, line_two, line_three, state, delivery_instructions, contact_phone. contact_email is nullable|email (note: nullable here vs required|email in CheckoutPage).

```php
public function rules(): array
```

--------------------------------

### getSaleCollectionProperty(): Collection | null

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/home.md

Returns the collection whose default URL slug is 'sale', or null. The Url lookup is by morph type (Lunar\Models\Collection) and slug 'sale' — the slug the seeded 'Sale' collection resolves to once URLs are generated.

```php
public function getSaleCollectionProperty(): Collection | null
{
    return Url::whereElementType((new Collection)->getMorphClass())->whereSlug('sale')->first()?->element ?? null;
}
```

--------------------------------

### Cart component mapLines() method

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/cart.md

Rebuilds the lines property from cartLines, extracting id, identifier, quantity, description, thumbnail URL, option, options, sub_total, and unit_price per line.

```php
public function mapLines(): void
```

--------------------------------

### save() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-address.md

Validates the address data and saves it to the cart. For billing type, calls setBillingAddress. For shipping type, calls setShippingAddress and optionally copies to billing if shippingIsBilling is true. Sets editing to false and emits the legacy 'addressUpdated' event to the parent CheckoutPage. Throws ValidationException on invalid data.

```php
public function save(): void
```

--------------------------------

### triggerAddressRefresh method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Public method that dispatches the 'refreshAddress' browser event. CheckoutAddress components listen for this event to reload their address models. Returns void.

```php
public function triggerAddressRefresh(): void
```

--------------------------------

### Blade select for shipping country

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Blade template using wire:model to bind the shipping country selection, iterating over the countries collection.

```blade
<select wire:model="shipping.country_id">
    @foreach ($this->countries as $country)
        <option value="{{ $country->id }}">{{ $country->name }}</option>
    @endforeach
</select>
```

--------------------------------

### Programmatic cart add outside component

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/add-to-cart.md

Shows how to add a purchasable to the cart programmatically using Lunar's cart manager, outside the Livewire component. Expects a Purchasable instance and an integer quantity.

```php
// Programmatic equivalent outside the component — Lunar's cart manager
CartSession::manager()->add($variant, 2); // Lunar\Base\Purchasable, int quantity
```

--------------------------------

### getCountriesProperty() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-address.md

Computed property returning allowed countries (GBR, USA) as a collection of Lunar\Models\Country. Accessible as $this->countries.

```php
public function getCountriesProperty()
```

--------------------------------

### getAddressValidation() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Returns per-type address validation rules for shipping or billing, with required and nullable fields.

```php
protected function getAddressValidation(string $type): array
```

--------------------------------

### Cart line item shape — Cart::mapLines()

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/types.md

Builds an array for each cart line, storing it in Cart::$lines. Validated by rules() with lines.*.quantity required, numeric, min:1, max:10000.

```php
[
    'id' => $line->id,
    'identifier' => $line->purchasable->getIdentifier(),
    'quantity' => $line->quantity,
    'description' => $line->purchasable->getDescription(),
    'thumbnail' => $line->purchasable->getThumbnail()?->getUrl(),
    'option' => $line->purchasable->getOption(),
    'options' => $line->purchasable->getOptions()->implode(' / '),
    'sub_total' => $line->subTotal->formatted(),
    'unit_price' => $line->unitPrice->formatted(),
]
```

--------------------------------

### Order line shape — OrderSeeder

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/types.md

Each pushed line array is used with Order::lines()->createMany(). Includes tax_breakdown as Lunar\Base\ValueObjects\Cart\TaxBreakdown.

```php
[
    'quantity' => int, 'purchasable_type' => ProductVariant morph class,
    'purchasable_id' => int, 'type' => 'physical',
    'description' => string, 'option' => string, 'identifier' => sku,
    'unit_price' => int, 'unit_quantity' => int, 'sub_total' => int,
    'discount_total' => 0, 'tax_total' => int, 'total' => int,
    'tax_breakdown' => Lunar\Base\ValueObjects\Cart\TaxBreakdown,
]
```

--------------------------------

### AppServiceProvider register(): Register LunarPanel with ShippingPlugin

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/service-providers.md

Registers the Lunar admin panel with the Lunar\Shipping\ShippingPlugin (table-rate shipping admin UI at /lunar). Called during service provider registration.

```php
public function register(): void
{
    LunarPanel::panel(
        fn ($panel) => $panel->plugins([
            new ShippingPlugin,
        ])
    )
        ->register();
}
```

--------------------------------

### Stock error path

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/add-to-cart.md

Shows the error path when quantity exceeds stock: adds a component error instead of touching the cart, so the cart state never changes on a failed add.

```php
// Error path observed: quantity > stock adds a component error instead of
// touching the cart, so the cart state never changes on a failed add.
$this->addError('quantity', 'The quantity exceeds the available stock.');
```

--------------------------------

### getShippingOptionProperty() method signature

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/checkout-page.md

Returns the selected ShippingOption for the cart's shipping address, or null. Accessible as $this->shippingOption in Blade.

```php
public function getShippingOptionProperty()
```

--------------------------------

### handle() method for ShippingModifier

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/shipping-modifier.md

Registers a fallback 'Basic Delivery' shipping option when config('shipping-tables.enabled') is false. Since no config/shipping-tables.php ships with the repo, the value is null, so the option is registered by default. Always returns $next($cart) to continue the middleware chain.

```php
public function handle(Cart $cart, \Closure $next)
{
    /**
     * Custom shipping option.
     * --------------------------------------------
     * If you do not wish to use the shipping add-on you can add
     * your own shipping options that will appear at checkout
     */

    if(config('shipping-tables.enabled') == false){
        \Lunar\Facades\ShippingManifest::addOption(
            new \Lunar\DataTypes\ShippingOption(
                name: 'Basic Delivery',
                description: 'Basic Delivery',
                identifier: 'BASDEL',
                price: new \Lunar\DataTypes\Price(500, $cart->currency, 1),
                taxClass: \Lunar\Models\TaxClass::getDefault()
            )
        );
    }

    return $next($cart);
}
```

--------------------------------

### Cart component updateLines() method

Source: https://github.com/lunarphp/livewire-starter-kit/blob/main/_autodocs/api-reference/cart.md

Validates line quantities, updates the cart via CartSession::updateLines(), re-maps lines, and dispatches the cartUpdated event. Throws ValidationException if any quantity is out of range.

```php
public function updateLines(): void
```
Tokens:
Raw