Lunar

https://github.com/lunarphp/lunar
Admin
Lunar is a set of Laravel packages that bring Shopify-like e-commerce functionality to Laravel,...
Tokens:460,354
Snippets:3,036
Trust Score:8.5
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Example artisan commands for Lunar

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/console-commands.md

Example commands for installing Lunar, reindexing, refreshing or flushing a specific index, setting up Meilisearch attributes, pruning carts, and creating an admin user.

```bash
# Full install
php artisan lunar:install

# Reindex everything
php artisan lunar:search:index

# Refresh only the product index
php artisan lunar:search:index "App\Models\Product" --refresh

# Flush an index (delete records, don't reindex)
php artisan lunar:search:index --flush

# Set up Meilisearch filterable/sortable attributes
php artisan lunar:meilisearch:setup

# Prune carts manually
php artisan lunar:prune:carts

# Create an admin user for the panel
php artisan lunar:create-admin
```

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

### Lunar API Examples

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/storefront-session.md

Code examples for telemetry, storefront session, and measurement conversion APIs.

```APIDOC
## Telemetry::optOut()

### Description
Persists the user's opt-out preference for telemetry collection.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
None

### Request Example
```php
use Lunar\Facades\Telemetry;

Telemetry::optOut();
```

### Response
No return value (void).
```

```APIDOC
## Telemetry::getInsightsPayload()

### Description
Retrieves the telemetry insights payload containing system and usage data.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
None

### Request Example
```php
use Lunar\Facades\Telemetry;

$payload = Telemetry::getInsightsPayload();
```

### Response
Returns an array containing telemetry data.
```

```APIDOC
## StorefrontSession::setCurrency($currency)

### Description
Sets the current currency for the storefront session.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
- **$currency** (mixed) - Required - The currency instance to set.

### Request Example
```php
use Lunar\Facades\StorefrontSession;

StorefrontSession::setCurrency($currency);
```

### Response
No return value (void).
```

```APIDOC
## StorefrontSession::setChannel($channel)

### Description
Sets the current channel for the storefront session.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
- **$channel** (mixed) - Required - The channel instance to set.

### Request Example
```php
use Lunar\Facades\StorefrontSession;

StorefrontSession::setChannel($channel);
```

### Response
No return value (void).
```

```APIDOC
## StorefrontSession::setCustomerGroups(collect([$customerGroup]))

### Description
Sets the customer groups for the storefront session.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
- **$customerGroups** (Collection) - Required - A collection of customer group instances.

### Request Example
```php
use Lunar\Facades\StorefrontSession;

StorefrontSession::setCustomerGroups(collect([$customerGroup]));
```

### Response
No return value (void).
```

```APIDOC
## StorefrontSession::getCurrency()

### Description
Retrieves the current currency from the storefront session.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
None

### Request Example
```php
use Lunar\Facades\StorefrontSession;

$currentCurrency = StorefrontSession::getCurrency();
```

### Response
Returns the current currency instance.
```

```APIDOC
## StorefrontSession::setCustomer($customer)

### Description
Sets the customer for the storefront session, throwing an exception if the authenticated user is not linked to the customer record.

### Method
N/A (PHP method)

### Endpoint
N/A

### Parameters
- **$customer** (mixed) - Required - The customer instance to set.

### Request Example
```php
use Lunar\Exceptions\CustomerNotBelongsToUserException;

try {
    StorefrontSession::setCustomer($customer);
} catch (CustomerNotBelongsToUserException $e) {
    // authenticated user is not linked to this customer record
}
```

### Response
No return value (void). Throws `CustomerNotBelongsToUserException` if the customer does not belong to the authenticated user.
```

```APIDOC
## Converter::from('weight.g')->to('weight.kg')->value(2500)->convert()->getValue()

### Description
Converts a measurement from one unit to another and returns the numeric value.

### Method
N/A (PHP method chain)

### Endpoint
N/A

### Parameters
- **from** (string) - Required - The source unit (e.g., 'weight.g').
- **to** (string) - Required - The target unit (e.g., 'weight.kg').
- **value** (number) - Required - The numeric value to convert.

### Request Example
```php
use Lunar\Facades\Converter;

$kg = Converter::from('weight.g')->to('weight.kg')->value(2500)->convert()->getValue(); // 2.5
```

### Response
Returns the converted numeric value (float).
```

```APIDOC
## Converter::from('weight.kg')->value(2.5)->to('weight.lbs')->convert()->format()

### Description
Converts a measurement and formats the result as a human-readable string.

### Method
N/A (PHP method chain)

### Endpoint
N/A

### Parameters
- **from** (string) - Required - The source unit (e.g., 'weight.kg').
- **value** (number) - Required - The numeric value to convert.
- **to** (string) - Required - The target unit (e.g., 'weight.lbs').

### Request Example
```php
use Lunar\Facades\Converter;

$label = Converter::from('weight.kg')->value(2.5)->to('weight.lbs')->convert()->format(); // "5.51 lbs"
```

### Response
Returns a formatted string with the converted value and unit.
```

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

### AbstractEngine

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/search.md

Fluent configuration methods for the search engine, applied before calling get().

```APIDOC
## AbstractEngine

`Lunar\Search\Engines\AbstractEngine` — `packages/search/src/Engines/AbstractEngine.php`. Fluent configuration applied before `get()`:

```php
public function extendQuery(\Closure $callable): self
public function filter(array $filters): self
public function addFilter($key, $value): self
public function getFilters(): array
public function perPage(int $perPage): self
public function getFacets(): array
public function setFacets(array $facets): self
public function removeFacet(string $field, mixed $value = null): self
public function sort(string $sort): self
public function getSort(): ?string
public function sortRaw(string $sort): self
public function query(string $query): AbstractEngine
public function getQuery(): ?string
public function deleteByIds(Collection $ids): array
abstract public function get(): mixed;
abstract protected function getFieldConfig(): array;
```

- `sort()` accepts `field:asc|desc` (`sortByIsValid()` validates against the model's facet config `sort` flags).
- `getSearchQueries(): Collection<SearchQuery>` builds the primary query plus one per active facet (matching Meilisearch's facet-distribution model) and runs query extenders.
- `getFacetConfig(?string $field)` reads `lunar.search.facets.{model}` from the **search package's** config (`packages/search/config/search.php`): default facets for `Product` include `brand`.
```

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

### Facet configuration example for Lunar search

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/search.md

Configuration array for defining search facets in the Lunar search package. The 'facets' key maps model classes to facet definitions, where each facet can have options with additional attributes. The example shows a 'brand' facet with no options and a commented-out 'colour' facet with a 'Red' option that includes a 'hex_value' attribute.

```php
// packages/search/config/search.php (published to config/lunar/search.php)
return [
    'facets' => [
        Product::class => [
            'brand' => [],
            // 'colour' => [
            //     'Red' => ['hex_value' => '#FF0000'],
            // ],
        ],
    ],
];
```

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

### Typical storefront search using Lunar Search facade

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/search.md

Example of performing a search on a Product model using the Lunar Search facade. It chains methods to set the query, filter by brand, set facets, sort by price ascending, paginate with 24 items per page, and retrieve results. The results provide hits with documents (searchable arrays) and facets with values that include label, count, and active status. Pagination links are available via the 'links' property.

```php
use Lunar\Models\Product;
use Lunar\Search\Facades\Search;

$results = Search::model(Product::class)
    ->query('socks')
    ->filter(['brand' => 'happy-socks'])
    ->setFacets(['brand' => ['happy-socks']])
    ->sort('price:asc')
    ->perPage(24)
    ->get();

foreach ($results->hits as $hit) {
    $product = $hit->document; // searchable array
}

foreach ($results->facets as $facet) {
    foreach ($facet->values as $value) {
        // $value->label, $value->count, $value->active
    }
}

echo $results->links; // pagination links view
```

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

### Customise order creation pipeline

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/orders.md

Customises the order creation pipeline in config/lunar/orders.php by listing pipeline classes. The example appends a custom SendToErp pipeline after the default ones.

```php
// config/lunar/orders.php
'pipelines' => [
    'creation' => [
        FillOrderFromCart::class,
        CreateOrderLines::class,
        CreateOrderAddresses::class,
        CreateShippingLine::class,
        CleanUpOrderLines::class,
        MapDiscountBreakdown::class,
        App\Pipelines\Orders\SendToErp::class,
    ],
],
```

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

### Basic price lookup with Lunar\Facades\Pricing

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/pricing.md

Fetches the matched price for a product variant and reads the decimal and formatted values from the response. The `decimal` property returns the raw amount (for example 19.99) and `formatted` returns the display string.

```php
use Lunar\Facades\Pricing;
use Lunar\Models\ProductVariant;

$variant = ProductVariant::find($id);

$response = Pricing::for($variant)->get();

$amount = $response->matched->price->decimal;      // e.g. 19.99
$formatted = $response->matched->price->formatted; // e.g. £19.99
```

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

### Publish and configure Lunar panel features

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/admin-panel.md

Publish the Lunar configuration files and then adapt the panel features by editing the published config/lunar/panel.php file. The example shows enabling variants, setting PDF rendering to 'stream', enabling Scout, and defining order count statuses.

```bash
php artisan vendor:publish --tag=lunar
# config/lunar.php / config/lunar/panel.php

```

```php
// config/lunar/panel.php
return [
    'enable_variants' => true,
    'pdf_rendering' => 'stream',
    'scout_enabled' => true,
    'order_count_statuses' => ['payment-received', 'dispatched'],
];

```

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

### Add a custom shipping option at boot

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/manifests.md

Listen to the 'lunar:shipping-options' event and use ShippingManifest::addOption() to add a custom shipping option. The example creates a 'Next day' option with a price of 12.00 and the default tax class.

```php
use Illuminate\Support\Facades\Event;
use Lunar\DataTypes\ShippingOption;
use Lunar\Facades\ShippingManifest;
use Lunar\Models\TaxClass;

Event::listen('lunar:shipping-options', function ($cart) {
    ShippingManifest::addOption(new ShippingOption(
        name: 'Next day',
        description: 'Delivery tomorrow',
        identifier: 'NEXTDAY',
        price: new \Lunar\DataTypes\Price(1200, $cart->currency), // 12.00
        taxClass: TaxClass::getDefault(),
    ));
});
```

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

### Registering a custom rate driver

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/table-rate-shipping.md

Example of registering a custom rate driver using the Shipping facade's extend method.

```APIDOC
## Registering a custom rate driver

```php
use Lunar\Shipping\Facades\Shipping;

Shipping::extend('weighted', fn ($app) => $app->make(App\Shipping\WeightedRate::class));
```
```

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

### GET lunar/pdf/download

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/endpoints.md

Admin panel PDF download endpoint.

```APIDOC
## GET lunar/pdf/download

### Description
Streams the requested order PDF. Only registered when `lunar.panel.pdf_rendering === 'stream'`.

### Method
GET

### Endpoint
lunar/pdf/download

### Parameters
No parameters documented.

### Response
#### Success Response (200)
- PDF stream

### Notes
- Auth: panel middleware stack (staff guard).
```

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

### Measurement conversion

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/storefront-session.md

Convert weight measurements using the Converter facade. The first example converts grams to kilograms and returns the numeric value; the second converts kilograms to pounds and formats the result.

```php
use Lunar\Facades\Converter;

$kg = Converter::from('weight.g')->to('weight.kg')->value(2500)->convert()->getValue(); // 2.5
$label = Converter::from('weight.kg')->value(2.5)->to('weight.lbs')->convert()->format(); // "5.51 lbs"
```

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

### Adding a postcode resolver for a country not natively supported

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/table-rate-shipping.md

Example of adding a custom postcode resolver for a country not natively supported, then using it to get postcode parts.

```APIDOC
## Adding a postcode resolver for a country not natively supported

```php
use Lunar\Shipping\Facades\Postcode;

Postcode::addResolver(\App\Shipping\UkPostcodeResolver::class); // implements PostcodeResolverInterface
$parts = Postcode::country($country)->getParts('SW1A 1AA', $country);
```
```

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

### Customise order reference format

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/orders.md

Configures the order reference format in config/lunar/orders.php. The example produces references like LUN-000123 with left padding and a length of 6.

```php
// config/lunar/orders.php
'reference_format' => [
    'prefix' => 'LUN-',
    'padding_direction' => STR_PAD_LEFT,
    'padding_character' => '0',
    'length' => 6,
],
// LUN-000123
```

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

### Search facade usage: Search::model()->query()->get()

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/search.md

Uses the Search facade to run a search query against a model. Returns the result set for the given query string.

```php
use Lunar\Search\Facades\Search;

$results = Search::model(Product::class)->query('socks')->get();
```

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

### Basic CartSession facade lookup

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/cart-session.md

Shows basic CartSession facade usage: retrieving the current cart, getting a persisted cart via manager(), and setting the storefront currency. The current() method never creates a cart unless auto_create is enabled.

```php
use Lunar\Facades\CartSession;

// Get the current cart (never creates one unless auto_create is enabled)
$cart = CartSession::current();

// Always get a persisted cart, creating one if needed
$cart = CartSession::manager();

// Set the storefront currency for pricing
CartSession::setCurrency(Currency::getDefault());
```

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

### Resolve options for the session cart

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/table-rate-shipping.md

Example of resolving shipping options for the session cart using the Shipping facade. It retrieves zones, rates, and options based on the cart's shipping address.

```APIDOC
## Resolve options for the session cart

```php
use Lunar\Facades\CartSession;
use Lunar\Shipping\Facades\Shipping;

$cart = CartSession::current();

$zones = Shipping::zones()
    ->country($cart->shippingAddress?->country)
    ->get();

$rates = Shipping::shippingRates($cart)
    ->country($cart->shippingAddress?->country)
    ->state($cart->shippingAddress?->state)
    ->postcode($cart->shippingAddress?->postcode)
    ->get();

$options = Shipping::shippingOptions($cart)->get(
    new \Lunar\Shipping\DataTransferObjects\ShippingOptionLookup($rates)
);

foreach ($options as $option) {
    echo $option->getName().' — '.$option->price->formatted;
}
```
```

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

### Resolve and authorize an offline payment

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/payments.md

Uses Payments::driver('cash-in-hand') to get an OfflinePayment, sets the cart and data, then authorizes. On success, the order is placed with status 'payment-offline'.

```php
use Lunar\Facades\Payments;
use Lunar\Models\Cart;

$cart = Cart::find($id);

$driver = Payments::driver('cash-in-hand'); // OfflinePayment with setConfig()

$response = $driver
    ->cart($cart)
    ->withData(['authorized' => 'payment-offline'])
    ->authorize();

if ($response->success) {
    // order placed, status 'payment-offline'
    $order = \Lunar\Models\Order::find($response->orderId);
}
```

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

### Drive the system tax driver directly

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/taxes.md

Directly drives the system tax driver to compute a tax breakdown for a cart line. The breakdown amounts are summed to get the total tax, and each amount exposes identifier, description, and percentage properties.

```php
use Lunar\Facades\Taxes;

$breakdown = Taxes::driver('system')
    ->setShippingAddress($cart->shippingAddress)
    ->setBillingAddress($cart->billingAddress)
    ->setCurrency($cart->currency)
    ->setPurchasable($variant)
    ->setCartLine($cartLine)
    ->getBreakdown($cartLine->subTotal->value);

$totalTax = $breakdown->amounts->sum('price.value');

foreach ($breakdown->amounts as $amount) {
    // $amount->identifier, $amount->description, $amount->percentage
}
```

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

### AbstractDiscountType class

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/discounts.md

Base class for discount types. Provides methods to set the discount, mark it as used, get eligible lines, check conditions, add a discount breakdown, and track user usage. Conditions include customer restriction, coupon match, minimum spend, and use limits.

```php
namespace Lunar\DiscountTypes;

abstract class AbstractDiscountType implements DiscountTypeInterface
{
    public DiscountContract $discount;

    public function with(DiscountContract $discount): self
    public function markAsUsed(CartContract $cart): self
    protected function getEligibleLines(CartContract $cart): Collection
    protected function checkDiscountConditions(CartContract $cart): bool
    protected function addDiscountBreakdown(CartContract $cart, DiscountBreakdown $breakdown)
    protected function usesByUser(Authenticatable $user)
}
```

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

### Engine selection per model in Lunar search config

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/search.md

Configuration snippet for the 'engine_map' key in the Lunar search configuration file. It maps model classes to search engine identifiers, allowing different models to use different search engines. The example maps Product to 'meilisearch' and Order to 'database'.

```php
// config/lunar/search.php
'engine_map' => [
    Lunar\Models\Product::class => 'meilisearch',
    Lunar\Models\Order::class => 'database',
],
```

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

### GET opayo-threedsecure

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/endpoints.md

Opayo 3-D Secure iframe endpoint.

```APIDOC
## GET opayo-threedsecure

### Description
Renders an iframe view used during a 3-D Secure challenge.

### Method
GET

### Endpoint
opayo-threedsecure

### Parameters
No parameters.

### Response
#### Success Response (200)
- HTML iframe view

### Notes
- Auth: none.
```

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

### Set storefront context

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/storefront-session.md

Set the current currency, channel, and customer groups for the storefront session, then retrieve the current currency.

```php
use Lunar\Facades\StorefrontSession;

StorefrontSession::setCurrency($currency);
StorefrontSession::setChannel($channel);
StorefrontSession::setCustomerGroups(collect([$customerGroup]));

$currentCurrency = StorefrontSession::getCurrency();
```

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

### Registering a custom driver

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/payments.md

Shows how to extend Payments with a custom 'bank-transfer' driver and the corresponding config entry. The driver class must extend AbstractPayment.

```php
use Lunar\Facades\Payments;

Payments::extend('bank-transfer', function ($app) {
    return $app->make(App\Payments\BankTransferPayment::class); // extends AbstractPayment
});

// config/lunar/payments.php
'types' => [
    'bank-transfer' => [
        'driver' => 'bank-transfer',
        'authorized' => 'payment-received',
    ],
],
```

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

### Add a cart-line modifier

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/manifests.md

Use the CartLineModifiers service to add a custom cart-line modifier class. The example registers GiftWrapModifier.

```php
use Lunar\Base\CartLineModifiers;

app(CartLineModifiers::class)->add(\App\Modifiers\GiftWrapModifier::class);
```

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

### PricingManager::get() method

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/pricing.md

Resolves the pricing and returns a Lunar\Base\DataTransferObjects\PricingResponse. Throws \ErrorException if no purchasable or no price matched, and Lunar\Exceptions\MissingCurrencyPriceException if no prices exist in the requested currency.

```php
public function get()
```

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

### DatabaseEngine::get()

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/search.md

Executes a database-backed search query and returns SearchResults.

```APIDOC
## DatabaseEngine::get()

`Lunar\Search\Engines\DatabaseEngine::get(): mixed` — runs `get_search_builder($this->modelType, $this->query)->paginate()` and maps rows to `SearchHit` documents (`toSearchableArray()`), returning `SearchResults`.
```

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

### Get default records with HasDefaultRecord

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/models.md

Retrieves the default Currency, Channel, and CustomerGroup records using the HasDefaultRecord trait. The comments indicate the trait used for each model.

```php
use Lunar\Models\Currency;
use Lunar\Models\Channel;
use Lunar\Models\CustomerGroup;

$currency = Currency::getDefault();      // HasDefaultRecord
$channel  = Channel::getDefault();
$group    = CustomerGroup::getDefault();
```

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

### PostcodeManager

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/table-rate-shipping.md

The PostcodeManager provides methods to add postcode resolvers, retrieve a resolver for a specific country, and get all registered resolvers. It throws NoPostcodeResolverException when no resolver matches the country.

```APIDOC
## PostcodeManager

`Lunar\Shipping\Managers\PostcodeManager` — facade `Lunar\Shipping\Facades\Postcode`:

```php
public function addResolver(string|PostcodeResolverInterface|array $resolver)
public function country(CountryContract $country): PostcodeResolverInterface
public function getResolvers(): Collection
```

Built-in resolver `PostcodeResolver` implements `PostcodeResolverInterface` (`supportsCountry(CountryContract $country): bool`, `getParts(string $postcode, CountryContract $country): Collection`). Throw `Lunar\Shipping\Exceptions\NoPostcodeResolverException` when no country resolver exists (raised by the manager when `country()` is called without a matching resolver).
```

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

### Lunar\DiscountTypes\BuyXGetY::apply

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/discounts.md

Applies the BuyXGetY discount to the cart, adding free items and recording discount breakdowns.

```APIDOC
## [POST] /discounts/buyxgety/apply

### Description
Applies the BuyXGetY discount to the given cart.

### Method
POST

### Endpoint
/discounts/buyxgety/apply

### Parameters
#### Request Body
- **cart** (CartContract) - Required - The cart to apply the discount to.

### Request Example
{
  "cart": {}
}

### Response
#### Success Response (200)
- **cart** (CartContract) - The updated cart with the discount applied.

#### Response Example
{
  "cart": {}
}
```

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

### TaxManager

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/taxes.md

The TaxManager is a Laravel Manager that builds and provides tax driver instances. Use Taxes::driver() to get a driver, or Taxes::extend() to register a custom driver.

```APIDOC
## TaxManager

### Description
The TaxManager is a Laravel Manager that builds and provides tax driver instances. Use `Taxes::driver()` to get a driver, or `Taxes::extend()` to register a custom driver.

### Methods
- **createSystemDriver()** - Builds a SystemTaxDriver instance.
- **buildProvider($provider)** - Resolves a driver instance from the container.
- **getDefaultDriver()** - Returns the default driver name from config (`lunar.taxes.driver`, default `'system'`).

### Usage
```php
$driver = Taxes::driver(); // Get default driver
Taxes::extend('my-driver', fn () => new MyDriver); // Register custom driver
```
```

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

### Order state helper methods

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/orders.md

These methods check the order's placement state. isDraft() returns true when not placed, isPlaced() returns true when placed_at is not blank, and getDefaultLogExcept() returns ['status'] for activity logging.

```php
public function isDraft(): bool   // ! isPlaced()
public function isPlaced(): bool  // ! blank(placed_at)
public static function getDefaultLogExcept(): array // ['status'] for activity log
```

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

### Create admin user with lunar:create-admin

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/admin-panel.md

Run the artisan command to create an admin user for the Lunar panel.

```bash
php artisan lunar:create-admin

```

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

### Add postcode resolver for unsupported country

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/table-rate-shipping.md

Adds a custom postcode resolver for a country not natively supported and uses it to get postcode parts. The resolver must implement PostcodeResolverInterface.

```php
use Lunar\Shipping\Facades\Postcode;

Postcode::addResolver(\App\Shipping\UkPostcodeResolver::class); // implements PostcodeResolverInterface
$parts = Postcode::country($country)->getParts('SW1A 1AA', $country);
```

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

### Checkout flow with shipping estimation and order creation

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/cart-session.md

Checkout flow with a guest cart: sets shipping estimation metadata, retrieves the current cart with shipping estimates, handles the case where no cart exists (returns 404), creates an order, and checks that the session cart is cleared after order creation.

```php
use Lunar\Facades\CartSession;

CartSession::estimateShippingUsing(['postcode' => 'SW1A 1AA']);

$cart = CartSession::current(estimateShipping: true);

if (! $cart) {
    // No cart in session and auto_create is disabled
    return response('Cart is empty', 404);
}

// Create the order; the session cart is forgotten afterwards
$order = CartSession::createOrder();

// The order was persisted; the cart session is now clear
if (CartSession::current() === null) {
    // redirect to checkout success
}
```

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

### PostcodeManager public methods

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/table-rate-shipping.md

Public API of the PostcodeManager facade. Use addResolver to register a resolver, country to get a resolver for a specific country, and getResolvers to retrieve all registered resolvers.

```php
public function addResolver(string|PostcodeResolverInterface|array $resolver)
public function country(CountryContract $country): PostcodeResolverInterface
public function getResolvers(): Collection
```

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

### PricingManager::for() method

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/pricing.md

Sets the purchasable for the pricing resolution. The purchasable must implement Lunar\Base\Purchasable.

```php
public function for(Purchasable $purchasable)
```

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

### PricingManager fluent configuration methods

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/pricing.md

Fluently configurable methods for the PricingManager. All return $this for chaining. customerGroup() wraps the single group in a collection.

```php
public function user(?Authenticatable $user)
public function guest()
public function currency(?CurrencyContract $currency)
public function qty(int $qty)
public function customerGroups(?Collection $customerGroups)
public function customerGroup(?CustomerGroupContract $customerGroup)
```

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

### Catch CartException with MessageBag

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/errors.md

Catches CartException subclasses when performing cart operations. The exception carries a MessageBag; iterate errors() to log each message. Example output: "Quantity cannot exceed 1000000."

```php
use Lunar\Exceptions\Carts\CartException;

try {
    $cart->add($purchasable, quantity: 500);
} catch (CartException $e) {
    foreach ($e->errors()->all() as $error) {
        Log::warning($error); // e.g. "Quantity cannot exceed 1000000."
    }
}
```

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

### manager()

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/cart-session.md

Creates a cart if the current cart does not exist (fetchOrCreate(create: true)), then returns it. Use this when you always need a persisted cart instance.

```APIDOC
## manager()

### Description
Creates a cart if the current cart does not exist, then returns it. Use this when you always need a persisted cart instance.

### Method
manager

### Endpoint
manager()

### Parameters
None

### Response
#### Success Response
- **?Cart** - The current cart, creating one if necessary.

#### Response Example
```json
{
  "cart": "Cart object"
}
```
```

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

### Register an attribute type for a custom entity

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/manifests.md

Use AttributeManifest::addType() to register a custom attribute type for an entity. The example registers a GiftCard model with the type 'gift_card'. After registration, getTypes() includes the new mapping.

```php
use Lunar\Facades\AttributeManifest;

AttributeManifest::addType(\App\Models\GiftCard::class, 'gift_card');
$types = AttributeManifest::getTypes(); // includes 'gift_card' => App\Models\GiftCard::class
```

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

### CreateOrder

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/cart.md

Creates an order from the cart, running order creation pipelines and marking discounts as used.

```APIDOC
## CreateOrder

### Description
Creates an order from the cart, running order creation pipelines and marking discounts as used.

### Method
`execute`

### Signature
`execute(CartContract $cart, bool $allowMultipleOrders = false, ?int $orderIdToUpdate = null)`

### Parameters
- `$cart` (CartContract) - Required - The cart to create an order from
- `$allowMultipleOrders` (bool) - Optional - Whether to allow multiple orders, defaults to false
- `$orderIdToUpdate` (?int) - Optional - The ID of an existing order to update

### Behaviour
- Runs in a DB transaction.
- Runs order creation pipelines.
- Marks discounts as used.
- Dispatches `MarkAsNewCustomer` job.

```

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

### PricingManager::guest()

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/pricing.md

Sets the pricing context to guest (no user).

```APIDOC
## PricingManager::guest()

### Description
Sets the pricing context to guest (no user).

### Method
`guest()`

### Parameters
None.

### Returns
`$this` for chaining.

```

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

### Error handling with CartSession::associate

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/cart-session.md

Error handling when associating a cart with a user. CartSession::associate() throws a generic Exception('Invalid user') if the cart's customer does not belong to the user; the example catches and reports it.

```php
use Illuminate\Auth\AuthenticationException;
use Lunar\Facades\CartSession;

try {
    CartSession::associate($cart, auth()->user(), 'merge');
} catch (\Exception $e) {
    // Cart::associate() throws a generic Exception('Invalid user') when the
    // cart's customer does not belong to the user.
    report($e);
}
```

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

### SearchManager class with driver factory methods

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/search.md

Defines the SearchManager extending Manager and implementing SearchManagerContract. Declares the default model and factory methods for database, Meilisearch, and Typesense drivers, plus provider building and default driver resolution from Scout config.

```php
class SearchManager extends Manager implements SearchManagerContract
{
    protected string $model = Product::class;

    public function createDatabaseDriver()      // DatabaseEngine
    public function createMeilisearchDriver()   // MeilisearchEngine
    public function createTypesenseDriver()     // TypesenseEngine
    public function buildProvider($provider)
    public function model(string $model): self
    public function driver($driver = null): AbstractEngine
    public function getDefaultDriver()          // config('scout.driver', 'database')
}
```

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

### StorefrontSessionManager

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/storefront-session.md

The StorefrontSessionManager class manages storefront-context state (channel, customer groups, currency, customer) for the current request, independently of the cart session. It provides methods to get and set these values, with session keys prefixed 'lunar_storefront_*'.

```APIDOC
## StorefrontSessionManager

### Description
Manages storefront-context state (channel, customer groups, currency, customer) for the current request, independently of the cart session. All setters write to the session and return $this; forget() removes all four keys.

### Constructor
```php
public function __construct(
    protected SessionManager $sessionManager,
    protected AuthManager $authManager,
)
```
Calls initChannel(), initCustomerGroups(), initCurrency(), initCustomer().

### Methods

#### getChannel / setChannel
- **getChannel()**: ChannelContract - Returns the current channel from session.
- **setChannel(ChannelContract $channel)**: static - Stores the channel handle in session.

#### getCustomerGroups / setCustomerGroups
- **getCustomerGroups()**: Collection - Returns the current customer groups from session.
- **setCustomerGroups(Collection $groups)**: static - Stores customer group handles in session.

#### setCustomerGroup
- **setCustomerGroup(CustomerGroupContract $group)**: static - Wraps a single customer group in a collection and stores it.

#### resetCustomerGroups
- **resetCustomerGroups()**: static - Clears session customer groups.

#### getCurrency / setCurrency
- **getCurrency()**: CurrencyContract - Returns the current currency from session.
- **setCurrency(CurrencyContract $currency)**: static - Stores the currency code in session.

#### getCustomer / setCustomer
- **getCustomer()**: ?CustomerContract - Returns the current customer from session, or null.
- **setCustomer(CustomerContract $customer)**: static - Stores the customer ID in session. Throws Lunar\Exceptions\CustomerNotBelongsToUserException when an authenticated Lunar user does not own the customer.

#### initChannel
- **initChannel()**: void - Initializes channel from session value, falling back to Channel::getDefault().

#### initCustomerGroups
- **initCustomerGroups()**: void - Initializes customer groups from session handles, falling back to CustomerGroup::getDefault().

#### initCurrency
- **initCurrency()**: void - Initializes currency from session code, falling back to Currency::getDefault().

#### initCustomer
- **initCustomer()**: void - Initializes customer from session id, falling back to authenticated user's latestCustomer().

#### forget
- **forget()**: void - Clears all four session keys.

#### getSessionKey
- **getSessionKey()**: string - Returns the session key prefix 'lunar_storefront'.

### Session Keys
Session keys are prefixed `lunar_storefront_*` (getSessionKey() returns 'lunar_storefront').

### Exceptions
- **Lunar\Exceptions\CustomerNotBelongsToUserException** - Thrown by setCustomer() when an authenticated Lunar user does not own the customer.
```

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

### Lunar\Facades\Pricing

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/pricing.md

Facade for retrieving prices for purchasables with support for quantity breaks, currency, and customer groups.

```APIDOC
## Pricing Facade

### Description
Facade for the pricing manager, used to retrieve prices for a purchasable.

### Methods

#### for

```php
Pricing::for($purchasable)
```

Sets the purchasable (e.g., a ProductVariant) to price.

#### qty

```php
Pricing::for($variant)->qty(int $qty)
```

Sets the quantity for bulk pricing tiers.

#### currency

```php
Pricing::for($variant)->currency($currency)
```

Sets the currency for pricing.

#### customerGroup

```php
Pricing::for($variant)->customerGroup($customerGroup)
```

Sets a single customer group for pricing.

#### customerGroups

```php
Pricing::for($variant)->customerGroups(collect([...]))
```

Sets multiple customer groups for pricing.

#### get

```php
Pricing::for($variant)->get()
```

Executes the pricing pipeline and returns a response object with a `matched` property containing the price.

### Response

The response object has a `matched` property with a `price` object that exposes `decimal` and `formatted` attributes.

### Exceptions

- `MissingCurrencyPriceException` is thrown if the currency has no prices.
```

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

### PricingManager::get()

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/pricing.md

Resolves the applicable price and returns a PricingResponse DTO. The resolution order is: validate purchasable, default currency, default customer groups, filter by currency, filter by customer groups, prefer cheapest price, run through pipelines.

```APIDOC
## PricingManager::get()

### Description
Resolves the applicable price and returns a `Lunar\Base\DataTransferObjects\PricingResponse` DTO. The resolution order is: validate purchasable, default currency, default customer groups, filter by currency, filter by customer groups, prefer cheapest price, run through pipelines.

### Method
`get()`

### Parameters
None (uses previously configured state).

### Returns
`Lunar\Base\DataTransferObjects\PricingResponse`

### Throws
- `\ErrorException` - If no purchasable is set or no price matches the combination.
- `Lunar\Exceptions\MissingCurrencyPriceException` - If no prices exist in the requested currency.

```

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

### Promotion and FreeItem value objects

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/types.md

Value objects for promotions and free items. Promotion has a description, reference, and amount. FreeItem requires a ProductVariant, an available count defaulting to 1, and a group string.

```php
class Promotion
{
    public string $description = '';
    public string $reference = '';
    public Price $amount;
}

class FreeItem
{
    public ProductVariant $productVariant;
    public int $available = 1;
    public string $group = '';
}
```

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

### PricingManager::qty()

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/pricing.md

Sets the quantity for pricing resolution, used for quantity breaks.

```APIDOC
## PricingManager::qty()

### Description
Sets the quantity for pricing resolution, used for quantity breaks.

### Method
`qty(int $qty)`

### Parameters
- **$qty** (int) - Required - The quantity.

### Returns
`$this` for chaining.

```

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

### PricingResponse DTO

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/types.md

Data transfer object returned by PricingManager::get() or Pricing::...->get(). Contains the matched price (customer-group/price-break aware), base price (min_quantity 1, no group), price breaks (min_quantity > 1), and customer group prices.

```php
class PricingResponse
{
    public function __construct(
        public Price $matched,       // Lunar\Models\Contracts\Price
        public Price $base,
        public Collection $priceBreaks,
        public Collection $customerGroupPrices,
    ) {}
}
```

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

### Price constructor

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/types.md

Constructor signature for the Price data type. The value must be an integer in minor units; otherwise the constructor throws InvalidDataTypeValueException. The unitQty defaults to 1 and is used for unit conversions.

```php
class Price
{
    public function __construct(
        public mixed $value,
        public Currency $currency,
        public int $unitQty = 1
    ) {}
}
```

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

### Extend OrderResource with extension

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/admin-panel.md

Extend a resource list by registering an extension for the OrderResource. The extension must implement setCaller() and hook methods.

```php
app('lunar-panel')->extensions([
    \Lunar\Admin\Filament\Resources\OrderResource::class => [
        \App\Panel\Extensions\OrderExtension::class, // implements setCaller() + hook methods
    ],
]);

```

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

### Scope products by channel and customer group

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/models.md

Scopes products by channel and customer group using the scopeChannel and scopeCustomerGroup methods. Also demonstrates retrieving variant pricing with a quantity using the PricingManager via the HasPrices trait.

```php
use Lunar\Models\Product;

$products = Product::channel($channel)->get();                    // scopeChannel
$visible  = Product::customerGroup($group)->get();                // scopeCustomerGroup
$variant  = ProductVariant::find($id);
$prices   = $variant->pricing()->qty(10)->get();                  // PricingManager via HasPrices
```

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

### Apply Discounts to Cart and Inspect Breakdown

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/discounts.md

Applies all applicable discounts to a cart and iterates over the applied discount types, printing their names. Also inspects the discount breakdown to output the formatted total discount per line.

```php
use Lunar\Facades\Discounts;
use Lunar\Models\Cart;

$cart = Cart::find($id)->calculate();

Discounts::apply($cart);

foreach ($cart->discounts as $applied) {
    // $applied is the discount type instance (AmountOff|BuyXGetY)
    echo $applied->getName();
}

// Inspect the breakdown
$cart->discountBreakdown->each(function ($line) {
    echo $line->price->formatted; // total discount per breakdown
});
```

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

### Pricing Configuration

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/pricing.md

Configuration options for the pricing system.

```APIDOC
## Configuration

### Description
Configuration options for the pricing system.

### Options

- `stored_inclusive_of_tax` (bool) - When `true`, prices are stored with tax included.
- `formatter` (string) - Class name of a custom formatter implementing `PriceFormatterInterface`.
- `pipelines` (array) - List of pipeline classes that receive the `PricingManager` and must set `$manager->pricing`.
```

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

### MeilisearchEngine::get()

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/search.md

Executes a multi-search against Meilisearch and returns SearchResults with facet distributions.

```APIDOC
## MeilisearchEngine::get()

`Lunar\Search\Engines\MeilisearchEngine::get(): SearchResults` — executes a `multiSearch` against the Scout Meilisearch engine (primary query + per-facet queries), merges facet distributions, honours soft-delete filtering (`__soft_deleted = 0`), and maps facets through `mapFacets()` to `SearchFacet`/`SearchFacetValue` objects with per-value config (`additional()` data). `mapFilter($field, $value)` builds Meilisearch filter strings.
```

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

### POST api/paypal/order

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/paypal.md

Builds the initial PayPal order for the current cart. This endpoint is registered by the PayPal service provider and handled by GetPaypalOrderController.

```APIDOC
## [POST] api/paypal/order

### Description
Builds the initial PayPal order for the current cart.

### Method
POST

### Endpoint
api/paypal/order

### Response
#### Success Response (200)
- **order** (object) - The PayPal order object returned by the PayPal Orders v2 API.

#### Response Example
{
  "id": "ORDER_ID",
  "status": "CREATED",
  "links": []
}
```

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

### POST {lunar.stripe.webhook_path}

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/endpoints.md

Stripe webhook endpoint for handling payment intent events.

```APIDOC
## POST {lunar.stripe.webhook_path}

### Description
Handles Stripe webhook events for payment intents. Verifies the Stripe signature and processes accepted event types by dispatching a job.

### Method
POST

### Endpoint
{lunar.stripe.webhook_path} (default: `stripe/webhook`)

### Parameters
#### Request Body
- Raw JSON body (object) - Required - Full Stripe `Event` object (payment intent events)

#### Headers
- `Stripe-Signature` (string) - Required - Signature over the payload, verified against `services.stripe.webhooks.lunar`

### Request Example
```json
{
  "id": "evt_...",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_...",
      "status": "succeeded"
    }
  }
}
```

### Response
#### Success Response (200)
- `webhook_successful` (boolean) - Indicates success
- `message` (string) - Success message

#### Response Example
```json
{
  "webhook_successful": true,
  "message": "Webook handled successfully"
}
```

#### Error Response (400)
- `webhook_successful` (boolean) - Indicates failure
- `message` (string) - Error message

#### Error Response Example
```json
{
  "webhook_successful": false,
  "message": "Signature verification failed"
}
```

### Notes
- Accepted event types: `payment_intent.payment_failed`, `payment_intent.succeeded`. Other types return empty 200.
- CSRF token verification excluded.
- Auth: signed payload (no session auth).
```

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

### Discounts::apply

Source: https://github.com/lunarphp/lunar/blob/1.x/_autodocs/api-reference/discounts.md

Applies all applicable discounts to a given cart and returns the cart with discounts applied.

```APIDOC
## [POST] /discounts/apply

### Description
Applies all applicable discounts to the provided cart instance.

### Method
POST

### Endpoint
/discounts/apply

### Parameters
#### Request Body
- **cart** (Cart) - Required - The cart to apply discounts to.

### Request Example
```php
use Lunar\Facades\Discounts;
use Lunar\Models\Cart;

$cart = Cart::find($id)->calculate();
Discounts::apply($cart);
```

### Response
#### Success Response (200)
- **discounts** (Collection) - Collection of applied discount type instances.
- **discountBreakdown** (Collection) - Breakdown of discount amounts per line.

#### Response Example
```php
foreach ($cart->discounts as $applied) {
    echo $applied->getName();
}

$cart->discountBreakdown->each(function ($line) {
    echo $line->price->formatted;
});
```
```
Tokens:
Raw