boboko/core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
core/docs/lunar.md
T

1209 lines
38 KiB
Markdown
Raw Permalink Blame History

# Lunar Reference
Lunar is a headless e-commerce package for Laravel (`lunarphp/core` + `lunarphp/lunar`). It handles products, carts, orders, payments, discounts, taxation, and more while leaving full control over the storefront UI. The admin panel is built on Filament.
---
## Table of Contents
1. [Core Concepts](#core-concepts)
2. [Key Models and Relationships](#key-models-and-relationships)
3. [ModelManifest — Replacing Models](#modelmanifest--replacing-models)
4. [Filament Panel Integration](#filament-panel-integration)
5. [Extending Resources and Pages](#extending-resources-and-pages)
6. [Activity Logging](#activity-logging)
7. [Pricing](#pricing)
8. [Tax](#tax)
9. [Channels and Currencies](#channels-and-currencies)
10. [Cart and Checkout](#cart-and-checkout)
11. [Orders](#orders)
12. [Customers and Addresses](#customers-and-addresses)
13. [Discounts](#discounts)
14. [Products and Variants](#products-and-variants)
15. [Collections and URLs](#collections-and-urls)
16. [Payments](#payments)
17. [Shipping](#shipping)
18. [Search Indexing](#search-indexing)
19. [Access Control](#access-control)
---
## Core Concepts
- **Headless**: Lunar is a Laravel package, not a standalone app. It lives inside your Laravel application.
- **No storefront UI prescribed**: The admin panel uses Filament/Livewire; the storefront can be Blade, Livewire, Inertia/Vue, or a pure API.
- **Table prefix**: All Lunar database tables use the `lunar_` prefix by default (configurable in `config/lunar/database.php`).
- **Prices stored as integers**: All monetary values are stored in the currency's smallest unit (e.g. cents). They are cast to `Lunar\DataTypes\Price` objects on retrieval.
- **Polymorphic morph map**: Lunar uses string aliases (e.g. `product`, `customer`) for polymorphic relations — not fully-qualified class names.
- **Config files**: Published to `config/lunar/` — key files are `database.php`, `cart.php`, `orders.php`, `taxes.php`, `payments.php`, `pricing.php`, `urls.php`, `media.php`.
### LunarUser trait
Add to your `User` model to gain relationships to carts, orders, and customers:
```php
use Lunar\Base\Traits\LunarUser;
use Lunar\Base\LunarUser as LunarUserInterface;
class User extends Authenticatable implements LunarUserInterface
{
use LunarUser;
}
```
This adds: `customers` (BelongsToMany), `carts` (HasMany), `orders` (HasMany), and `latestCustomer()`.
---
## Key Models and Relationships
### Quick map
| Model | Namespace | Notes |
|---|---|---|
| Product | `Lunar\Models\Product` | Has many variants; belongs to ProductType and optionally Brand |
| ProductVariant | `Lunar\Models\ProductVariant` | The actual purchasable item; has prices, stock, SKU |
| ProductType | `Lunar\Models\ProductType` | Defines which attributes a product has |
| ProductOption | `Lunar\Models\ProductOption` | e.g. "Size", "Color" |
| ProductOptionValue | `Lunar\Models\ProductOptionValue` | e.g. "Red", "Large" |
| Collection | `Lunar\Models\Collection` | Nested-set tree; belongs to CollectionGroup |
| CollectionGroup | `Lunar\Models\CollectionGroup` | Top-level grouping of collections |
| Cart | `Lunar\Models\Cart` | Has many CartLines; belongs to Currency and Channel |
| CartLine | `Lunar\Models\CartLine` | Polymorphic purchasable (usually ProductVariant) + quantity |
| CartAddress | `Lunar\Models\CartAddress` | Shipping or billing address on a cart |
| Order | `Lunar\Models\Order` | Created from a cart; has OrderLines and OrderAddresses |
| OrderLine | `Lunar\Models\OrderLine` | Snapshot of a purchased item |
| OrderAddress | `Lunar\Models\OrderAddress` | Immutable snapshot of shipping/billing address |
| Transaction | `Lunar\Models\Transaction` | Payment record (intent, capture, refund) |
| Customer | `Lunar\Models\Customer` | Buyer; linked to User via `customer_user` pivot |
| Address | `Lunar\Models\Address` | Saved address belonging to a Customer |
| Price | `Lunar\Models\Price` | Polymorphic; supports customer groups and quantity tiers |
| Currency | `Lunar\Models\Currency` | ISO 4217 code; exchange rate relative to default |
| Channel | `Lunar\Models\Channel` | Sales outlet; products are published per channel |
| Language | `Lunar\Models\Language` | ISO 639-1 code; controls translated attribute data |
| TaxClass | `Lunar\Models\TaxClass` | Assigned to variants; determines which rate applies |
| TaxZone | `Lunar\Models\TaxZone` | Geographic region; `tax_inclusive` or `tax_exclusive` |
| TaxRate | `Lunar\Models\TaxRate` | Belongs to TaxZone; has many TaxRateAmounts |
| Discount | `Lunar\Models\Discount` | Coupon/promo; AmountOff or BuyXGetY |
| Tag | `Lunar\Models\Tag` | Polymorphic tagging |
| Url | `Lunar\Models\Url` | SEO slug; polymorphic; one default per language |
| Brand | `Lunar\Models\Brand` | Optional brand for products |
### Product relationships
```
Product
├── productType → ProductType
├── brand → Brand (optional)
├── variants → ProductVariant[]
│ └── prices → Price[]
├── collections ↔ Collection[]
├── productOptions ↔ ProductOption[]
│ └── values → ProductOptionValue[]
├── associations → ProductAssociation[]
├── urls → Url[]
├── tags ↔ Tag[]
└── media (Spatie MediaLibrary)
```
### Cart relationships
```
Cart
├── lines → CartLine[]
│ └── purchasable → ProductVariant (polymorphic)
├── shippingAddress → CartAddress
├── billingAddress → CartAddress
├── currency → Currency
├── user → User
├── customer → Customer
└── orders → Order[]
```
### Order relationships
```
Order
├── lines → OrderLine[]
│ ├── productLines (excludes shipping type)
│ └── shippingLines (type = 'shipping')
├── shippingAddress → OrderAddress
├── billingAddress → OrderAddress
├── transactions → Transaction[]
│ ├── captures (type = 'capture')
│ ├── intents (type = 'intent')
│ └── refunds (type = 'refund')
├── customer → Customer
├── cart → Cart
└── currency → Currency (matched on currency_code)
```
### Customer relationships
```
Customer
├── users ↔ User[] (pivot: customer_user)
├── customerGroups ↔ CustomerGroup[]
├── addresses → Address[]
└── orders → Order[]
```
---
## ModelManifest — Replacing Models
`ModelManifest` is an interface-to-implementation registry. Registering a replacement does three things: binds the contract in the container, registers route model binding, and updates the morph map.
**Only models with contracts can be replaced.** Contracts live in `vendor/lunarphp/core/src/Models/Contracts/`. `Lunar\Admin\Models\Staff` has no contract and cannot be replaced this way.
### Replace a single model
```php
// In AppServiceProvider::boot()
\Lunar\Facades\ModelManifest::replace(
\Lunar\Models\Contracts\Customer::class,
\App\Models\Customer::class,
);
```
Your `App\Models\Customer` should extend `Lunar\Models\Customer`.
### Replace models from a directory
Scans the directory and replaces every model that extends a Lunar base model:
```php
\Lunar\Facades\ModelManifest::addDirectory(__DIR__.'/../Models');
```
### Dynamic relationships (preferred for simple extensions)
For adding relationships without replacing models:
```php
use Lunar\Models\Order;
Order::resolveRelationUsing('ticket', function ($order) {
return $order->belongsTo(Ticket::class, 'ticket_id');
});
```
Register in a service provider `boot()`.
### What is replaceable
Check `vendor/lunarphp/core/src/Models/Contracts/` for available contracts: `Customer`, `Order`, `Product`, `ProductVariant`, `ProductType`, `Cart`, `CartLine`, `Channel`, `Currency`, `Language`, `Collection`, `CollectionGroup`, `Price`, `Discount`, `Tag`, `Brand`, `TaxClass`, `TaxZone`, `TaxRate`, and others.
---
## Filament Panel Integration
### Registering the panel
```php
use Lunar\Admin\Support\Facades\LunarPanel;
class AppServiceProvider extends ServiceProvider
{
public function register(): void
{
LunarPanel::panel(function ($panel) {
return $panel
->path('admin') // default: 'lunar'
->pages([SalesReport::class])
->resources([BannerResource::class])
->plugin(new ShippingPlugin())
->navigationGroups(['Catalog', 'Sales', 'Settings']);
})
->extensions([
CustomerResource::class => CustomerResourceExtension::class,
])
->disableTwoFactorAuth()
->register();
}
}
```
`LunarPanel::register()` must be called in `register()`, not `boot()`.
### Registering extensions (resources and pages)
Extensions are keyed by the Lunar resource/page class:
```php
LunarPanel::extensions([
\Lunar\Admin\Filament\Resources\ProductResource::class => MyProductExtension::class,
\Lunar\Admin\Filament\Resources\CustomerResource::class => MyCustomerExtension::class,
\Lunar\Admin\Filament\Resources\OrderResource\Pages\ManageOrder::class => MyOrderExtension::class,
]);
```
### All extendable resources
```php
use Lunar\Admin\Filament\Resources\{
ActivityResource, AttributeGroupResource, BrandResource, ChannelResource,
CollectionGroupResource, CollectionResource, CurrencyResource,
CustomerGroupResource, CustomerResource, DiscountResource, LanguageResource,
OrderResource, ProductOptionResource, ProductResource, ProductTypeResource,
ProductVariantResource, StaffResource, TagResource, TaxClassResource,
TaxRateResource, TaxZoneResource
};
```
### Staff model wiring
`Lunar\Admin\Models\Staff` is the Filament auth model. It does **not** go through ModelManifest. To extend it:
- Override it by extending the class and pointing Filament's auth config at your subclass.
- Listen on `Lunar\Admin\Models\Staff::created` (not your subclass) for events fired by Lunar internals.
- Use `LunarStaff::addActivitylogExcept([...])` on the base class to exclude fields from the activity log — not `getDefaultLogExcept()` on a subclass.
---
## Extending Resources and Pages
### ResourceExtension
Extend a Lunar resource's form, table, relations, pages, and sub-navigation:
```php
use Filament\Forms\Form;
use Filament\Tables\Table;
use Lunar\Admin\Support\Extending\ResourceExtension;
class MyProductResourceExtension extends ResourceExtension
{
public function extendForm(Form $form): Form
{
return $form->schema([
...$form->getComponents(withHidden: true), // always spread existing
TextInput::make('custom_field'),
]);
}
public function extendTable(Table $table): Table
{
return $table->columns([
...$table->getColumns(),
TextColumn::make('custom_field'),
]);
}
public function getRelations(array $managers): array
{
return [...$managers, MyRelationManager::class];
}
public function extendPages(array $pages): array
{
return [...$pages, 'my-page' => MyPage::route('/{record}/my-page')];
}
public function extendSubNavigation(array $nav): array
{
return [...$nav, MyPage::class];
}
public function headerActions(array $actions): array
{
return [...$actions, Actions\Action::make('custom')];
}
}
```
### RelationManagerExtension
```php
use Lunar\Admin\Support\Extending\RelationManagerExtension;
class MyExtension extends RelationManagerExtension
{
public function extendForm(Form $form): Form { /* ... */ }
public function extendTable(Table $table): Table { /* ... */ }
public function headerActions(array $actions): array { /* ... */ }
}
```
### Page extensions
| Class | Use case |
|---|---|
| `CreatePageExtension` | `heading()`, `beforeCreate()`, `afterCreation()`, `formActions()`, `headerActions()`, `headerWidgets()`, `footerWidgets()` |
| `EditPageExtension` | `heading()`, `beforeFill()`, `beforeSave()`, `beforeUpdate()`, `afterUpdate()` |
| `ListPageExtension` | `heading()`, `getTabs()`, `headerActions()`, `headerWidgets()`, `footerWidgets()` |
| `ViewPageExtension` | `heading()`, `headerActions()`, `headerWidgets()`, `footerWidgets()` |
| `RelationPageExtension` | `heading()`, `headerActions()`, `extendTable()` |
### Order management extension
```php
LunarPanel::extensions([
\Lunar\Admin\Filament\Resources\OrderResource\Pages\ManageOrder::class => MyOrderExtension::class,
]);
```
Overridable methods include `extendInfolistSchema()`, `extendOrderSummaryInfolist()`, `extendOrderTotalsInfolist()`, `extendTransactionsInfolist()`, and many targeted `extend*Entry()` methods.
### Extending in addons (defensive pattern)
When modifying forms in an addon, always spread existing components to avoid conflicts with other extensions:
```php
public function extendForm(Form $form): Form
{
$form->schema([
...$form->getComponents(true),
TextInput::make('my_field'),
]);
return $form;
}
```
---
## Activity Logging
Lunar uses [Spatie laravel-activitylog](https://spatie.be/docs/laravel-activitylog) with the trait `Lunar\Base\Traits\LogsActivity`.
**Models logged by default**: AttributeGroup, Brand, Cart, CartAddress, CartLine, Channel, CollectionGroup, Currency, Customer, CustomerGroup, Discount, Order, OrderAddress, OrderLine, Product, ProductOption, ProductType, ProductVariant, Tag, TaxClass, TaxRate, TaxZone, Transaction.
All entries use the `lunar` log name. Only dirty attributes are recorded; `updated_at` is excluded.
### Adding logging to custom models
```php
use Lunar\Base\Traits\LogsActivity;
class MyModel extends Model
{
use LogsActivity;
public static function getDefaultLogExcept(): array
{
return ['internal_notes'];
}
}
```
### Excluding fields on Lunar's own Staff model
Because Filament instantiates `Lunar\Admin\Models\Staff` directly (not a subclass), use this pattern in a service provider boot:
```php
use Lunar\Admin\Models\Staff as LunarStaff;
LunarStaff::addActivitylogExcept(['otp_code', 'otp_expires_at', 'password']);
```
---
## Pricing
Prices are stored as integers in the smallest currency unit (e.g. cents). The `Price` model is polymorphic — any model implementing `HasPrices` can have prices.
### Price model fields
| Field | Description |
|---|---|
| `price` | Integer; smallest currency unit |
| `compare_price` | Optional; used for showing crossed-out "was" prices |
| `min_quantity` | Minimum quantity for this tier (default 1) |
| `currency_id` | Currency FK |
| `customer_group_id` | Nullable; for group-specific pricing |
| `priceable_type/id` | Polymorphic parent (e.g. ProductVariant) |
### Pricing facade
```php
use Lunar\Facades\Pricing;
$response = Pricing::for($variant)
->currency($currency)
->customerGroups($customerGroups)
->qty(5)
->get();
$response->matched; // Lunar\Models\Price — best match
$response->base; // base price (qty=1, no group)
$response->priceBreaks; // Collection of tier prices
$response->customerGroupPrices; // Collection of group prices
```
### Price data type
Every price attribute returns `Lunar\DataTypes\Price`:
```php
$price->value; // raw integer
$price->decimal(); // float
$price->unitDecimal(); // float, divided by unit_quantity
$price->formatted(); // "£10.00" (uses PHP NumberFormatter)
$price->unitFormatted(); // formatted per unit
```
### Tax helpers on Price model
Config `lunar.pricing.stored_inclusive_of_tax` controls whether stored prices include tax.
```php
$priceModel->priceExTax(); // Lunar\DataTypes\Price
$priceModel->priceIncTax(); // Lunar\DataTypes\Price
$priceModel->comparePriceIncTax(); // Lunar\DataTypes\Price
// Override tax zone (useful before a cart exists)
$priceModel->priceIncTax($taxZone);
```
### Custom price formatter
Set `config/lunar/pricing.php` `formatter` to your class implementing `PriceFormatterInterface`.
---
## Tax
### Structure
```
TaxZone (geographic region)
└── TaxRate[] (e.g. "VAT", "State Tax")
└── TaxRateAmount[] (percentage per TaxClass)
ProductVariant → TaxClass
```
### TaxZone fields
| Field | Values | Notes |
|---|---|---|
| `zone_type` | `country`, `states`, `postcodes` | Determines scope |
| `price_display` | `tax_inclusive`, `tax_exclusive` | Controls how prices display |
| `default` | boolean | Fallback zone |
### TaxRate and TaxRateAmount
```php
$taxZone->taxRates()->create(['name' => 'VAT', 'priority' => 1]);
$taxRate->taxRateAmounts()->create([
'tax_class_id' => $defaultTaxClass->id,
'percentage' => 20.000,
]);
```
### Custom tax driver
Implement `Lunar\Base\TaxDriver` and register:
```php
\Lunar\Facades\Taxes::extend('taxjar', fn ($app) => $app->make(TaxJar::class));
```
Then set `config/lunar/taxes.php` `driver` to `'taxjar'`.
---
## Channels and Currencies
### Channels
Channels represent sales outlets (webstore, wholesale portal, etc.). Products and collections are published per channel with optional start/end dates.
```php
$product->scheduleChannel($channel);
$product->scheduleChannel($channel, now()->addDays(14), now()->addDays(28));
$products = Product::channel($channel)->get();
```
### Currencies
```php
$currency->code; // e.g. 'GBP'
$currency->exchange_rate; // relative to default currency
$currency->decimal_places; // e.g. 2
$currency->default; // boolean
```
Exchange rates do not auto-convert prices unless `sync_prices` is enabled on the non-default currency.
### Storefront session
Manages the active channel, currency, customer, and customer groups for the session:
```php
use Lunar\Facades\StorefrontSession;
$channel = StorefrontSession::getChannel();
$currency = StorefrontSession::getCurrency();
$customer = StorefrontSession::getCustomer();
$groups = StorefrontSession::getCustomerGroups();
StorefrontSession::setChannel($channel);
StorefrontSession::setCurrency($currency);
StorefrontSession::setCustomer($customer); // validates customer belongs to user
```
Customer resolution order: session → `$user->latestCustomer()`.
---
## Cart and Checkout
### CartSession facade
```php
use Lunar\Facades\CartSession;
$cart = CartSession::current(); // calculates totals; returns null if no cart
$cart->recalculate(); // force recalculation
CartSession::createOrder(); // creates order, removes cart from session
CartSession::createOrder(forget: false); // keeps cart in session
CartSession::forget(); // clear session (soft deletes cart by default)
CartSession::forget(delete: false); // clear session, keep cart in DB
```
### Adding items
```php
$cart->add($variant, quantity: 2, meta: ['gift_wrap' => true]);
$cart->addLines([
['purchasable' => $variant, 'quantity' => 2],
]);
```
### Updating and removing
```php
$cart->updateLine($cartLineId, quantity: 3, meta: [...]);
$cart->remove($cartLineId);
$cart->clear();
```
### Addresses
```php
$cart->setShippingAddress([
'country_id' => $id, 'first_name' => '...', 'line_one' => '...', 'city' => '...', 'postcode' => '...',
]);
$cart->setBillingAddress([/* same fields */]);
```
Accepts an array or any model implementing `Lunar\Base\Addressable` (e.g. `Lunar\Models\Address`).
### Cart total properties (after calculate/recalculate)
| Property | Description |
|---|---|
| `total` | Grand total including tax |
| `subTotal` | Sum of lines before tax and discounts |
| `subTotalDiscounted` | Subtotal after discounts |
| `taxTotal` | Total tax |
| `discountTotal` | Total discounts |
| `shippingSubTotal` | Shipping before tax |
| `shippingTaxTotal` | Tax on shipping |
| `shippingTotal` | Shipping including tax |
| `taxBreakdown` | TaxBreakdown object; iterate `.amounts` |
| `discountBreakdown` | Collection of discount breakdowns |
| `shippingBreakdown` | Collection of shipping line items |
### CartLine properties (after calculate)
`unitPrice`, `unitPriceInclTax`, `subTotal`, `subTotalDiscounted`, `discountTotal`, `taxAmount`, `total`
### Cart exceptions
| Exception | Cause |
|---|---|
| `Lunar\Exceptions\Carts\CartException` | Validation failure; access errors via `$e->errors()` |
| `InvalidCartLineQuantityException` | Quantity <= 0 |
| `NonPurchasableItemException` | Model does not implement `Purchasable` |
| `CartLineIdMismatchException` | Cart line does not belong to cart |
| `DisallowMultipleCartOrdersException` | Cart already has a completed order |
| `FingerprintMismatchException` | Cart contents changed since fingerprint was generated |
### Cart fingerprint
```php
$fingerprint = $cart->fingerprint();
// ... pass to frontend hidden input ...
$cart->checkFingerprint($request->fingerprint); // throws FingerprintMismatchException
```
### Cart pipelines
Configurable in `config/lunar/cart.php`:
```
CalculateLines → ApplyShipping → ApplyDiscounts → CalculateTax → Calculate
```
Cart line pipeline: `GetUnitPrice`
Custom pipeline class:
```php
class MyPipeline
{
public function handle(Cart $cart, Closure $next): mixed
{
// modify cart...
return $next($cart);
}
}
```
### Cart auth policy (login/logout behavior)
```php
// config/lunar/cart.php
'auth_policy' => 'merge', // or 'override'
```
`merge` — guest cart items combine with user's existing cart on login.
`override` — guest cart replaces user's cart.
### Shipping options
```php
use Lunar\Facades\ShippingManifest;
$options = ShippingManifest::getOptions($cart); // Collection of ShippingOption
$option = ShippingManifest::getOption($cart, $identifier);
$cart->setShippingOption($option); // triggers recalculate
```
`ShippingOption` properties: `name`, `description`, `identifier`, `price`, `collect` (bool).
---
## Orders
### Order creation from cart
```php
$order = $cart->createOrder();
// or via CartSession (also handles session cleanup):
$order = CartSession::createOrder();
```
Validation requirements before `createOrder()`:
- Billing address with `country_id`, `first_name`, `line_one`, `city`, `postcode`
- Shipping address (same fields) if cart contains shippable items
- A shipping option must be selected if cart is shippable
### Draft vs placed
```php
$order->isDraft(); // placed_at is null
$order->isPlaced(); // placed_at is not null
```
Only placed orders should be shown in the customer's order history.
### Order fields (key ones)
| Field | Type | Description |
|---|---|---|
| `status` | string | e.g. `payment-received`, `dispatched` |
| `reference` | string | Auto-generated; format configurable |
| `placed_at` | dateTime\|null | null = draft |
| `sub_total` | Price | Subtotal excluding tax |
| `tax_total` | Price | Total tax |
| `shipping_total` | Price | Shipping including tax |
| `discount_total` | Price | Total discounts |
| `total` | Price | Grand total |
| `currency_code` | string | ISO currency at time of order |
| `meta` | json | Custom metadata |
### Order line types
- `physical` — physical product
- `digital` — digital product
- `shipping` — shipping charge
Access via `$order->productLines` (physical + digital), `$order->shippingLines`.
### Order pipelines
Configurable in `config/lunar/orders.php`:
```
FillOrderFromCart → CreateOrderLines → CreateOrderAddresses →
CreateShippingLine → CleanUpOrderLines → MapDiscountBreakdown
```
### Order reference format
Default: zero-padded order ID (8 digits). Configurable in `config/lunar/orders.php`:
```php
'reference_format' => [
'prefix' => null,
'padding_direction' => STR_PAD_LEFT,
'padding_character' => '0',
'length' => 8,
],
```
### Transactions
| Field | Description |
|---|---|
| `type` | `intent`, `capture`, or `refund` |
| `success` | boolean |
| `amount` | integer (smallest unit) |
| `driver` | e.g. `stripe` |
| `reference` | provider reference |
| `card_type` | e.g. `visa` |
| `last_four` | last 4 digits |
| `parent_transaction_id` | links capture to intent, refund to capture |
---
## Customers and Addresses
### Customer fields
| Field | Description |
|---|---|
| `first_name`, `last_name` | Name |
| `company_name` | Optional |
| `tax_identifier` | VAT / tax ID |
| `account_ref` | External reference |
| `attribute_data` | Custom attributes |
| `meta` | Flexible JSON |
Accessor: `$customer->full_name` → `"Mr. Tony Stark"`
### Linking users to customers
```php
$customer = Customer::create([...]);
$customer->users()->attach($user);
// For B2B: multiple users per customer
$customer->users()->sync([$userA->id, $userB->id]);
```
### Customer groups
Customer groups (`retail`, `wholesale`, etc.) control pricing, product visibility, and discount eligibility. Default group: `retail`.
```php
$customer->customerGroups()->attach($group);
// Filter products/collections by group
Product::customerGroup($group)->get();
// Schedule product availability for a group
$product->scheduleCustomerGroup($group, starts: now()->addDays(7));
$product->unscheduleCustomerGroup($group);
```
### Saved addresses
`Address` belongs to `Customer`. Fields: `first_name`, `last_name`, `company_name`, `tax_identifier`, `line_one` through `line_three`, `city`, `state`, `postcode`, `country_id`, `contact_email`, `contact_phone`, `delivery_instructions`, `shipping_default`, `billing_default`, `meta`.
When `shipping_default` is set to true, Lunar automatically unsets the previous default via an observer.
```php
$customer->addresses()->create([...]);
$customer->addresses()->where('shipping_default', true)->first();
```
---
## Discounts
### Discount model fields
| Field | Description |
|---|---|
| `name` | Display name |
| `coupon` | Optional coupon code |
| `type` | Fully-qualified class name of the discount type |
| `starts_at` / `ends_at` | Active window |
| `max_uses` | Global usage limit |
| `max_uses_per_user` | Per-user limit |
| `priority` | Processing order |
| `stop` | Stop processing further discounts if applied |
| `data` | Type-specific config (JSON) |
### Built-in discount types
- `Lunar\DiscountTypes\AmountOff` — percentage or fixed amount off
- `Lunar\DiscountTypes\BuyXGetY` — buy X items, get Y free/discounted
### Discount status
`$discount->status` returns: `active`, `pending`, `expired`, or `scheduled`.
### Applying discounts
Discounts are applied automatically during cart calculation when `coupon_code` is set on the cart, or based on cart contents for automatic discounts.
```php
$cart->update(['coupon_code' => '20OFF']);
$cart->recalculate();
Discounts::validateCoupon('20OFF'); // bool
Discounts::resetDiscounts(); // clear cached discounts for current request
```
### Custom discount types
```php
use Lunar\Facades\Discounts;
Discounts::addType(MyCustomDiscountType::class);
```
Implement `Lunar\DiscountTypes\AbstractDiscountType`. For admin panel support, also implement `Lunar\Admin\Base\LunarPanelDiscountInterface` and provide `lunarPanelSchema()`, `lunarPanelOnFill()`, `lunarPanelOnSave()`.
---
## Products and Variants
### ProductVariant fields (key)
| Field | Description |
|---|---|
| `sku` | Stock keeping unit |
| `stock` | Stock quantity |
| `purchasable` | `always` or `in_stock` |
| `unit_quantity` | Units per price point (default 1) |
| `weight_value`, `weight_unit` | For shipping weight calculations |
| `tax_class_id` | Determines applicable tax rate |
### Purchasable values
- `always` — can always be purchased (backorder)
- `in_stock` — only when `stock > 0`
```php
$variant->canBeFulfilledAtQuantity(3); // bool
```
### Attributes
All custom product/collection/brand attributes are stored in `attribute_data` as JSON. Access via `$model->attr('name')` which resolves translations based on current locale.
Attribute field types: `Text`, `TranslatedText`, `Number`, `Toggle`, `Dropdown`, `ListField`, `File`, `YouTube`, `Vimeo`.
### Product associations
```php
use Lunar\Base\Enums\ProductAssociation;
$product->associate($target, ProductAssociation::CROSS_SELL);
$product->associate($target, ProductAssociation::UP_SELL);
$product->associate($target, ProductAssociation::ALTERNATE);
$product->associate([$a, $b], ProductAssociation::CROSS_SELL);
$product->associations()->crossSell()->with('target')->get();
$product->dissociate($target);
```
### Pricing facade for products
```php
$pricing = Pricing::for($variant)
->currency(StorefrontSession::getCurrency())
->customerGroups(StorefrontSession::getCustomerGroups())
->get();
$pricing->matched; // best price for this context
$pricing->priceBreaks; // quantity tiers
```
---
## Collections and URLs
### Collection hierarchy
Collections use a nested set (via `HasNestedSets`). Each collection belongs to a `CollectionGroup`.
```php
$rootCollections = Collection::where('collection_group_id', $group->id)
->whereIsRoot()
->defaultOrder()
->with(['defaultUrl', 'children' => fn ($q) => $q->defaultOrder(), 'children.defaultUrl'])
->get();
// Full tree
$tree = Collection::where('collection_group_id', $group->id)
->defaultOrder()
->with('defaultUrl')
->get()
->toTree();
```
### URLs (slugs)
```php
use Lunar\Models\Url;
// Resolve product from slug
$url = Url::where('slug', $slug)
->where('element_type', (new Product)->getMorphClass())
->firstOrFail();
$product = Product::find($url->element_id);
// Create a URL
$product->urls()->create([
'slug' => 'my-product',
'language_id' => $language->id,
'default' => true,
]);
// Access URLs
$product->defaultUrl; // default URL for current locale
$product->localeUrl; // URL for current app locale
$product->urls; // all URLs
```
Auto-generation from `attr('name')` is enabled by default via `Lunar\Generators\UrlGenerator`. Configure in `config/lunar/urls.php`.
Add URL support to custom models with the `HasUrls` trait.
---
## Payments
### Payments facade
```php
use Lunar\Facades\Payments;
// Authorize
$response = Payments::driver('card')
->cart($cart)
->withData(['payment_intent' => $intentId])
->authorize();
$response->success; // bool
$response->orderId; // int|null
$response->message; // string|null
$response->paymentType; // string|null
// Capture (manual capture policy)
Payments::driver('card')->order($order)->capture($transaction, $amount);
// Refund
Payments::driver('card')->order($order)->refund($transaction, $amount, 'notes');
```
### Payment types configuration
In `config/lunar/payments.php`:
```php
'types' => [
'card' => [
'driver' => 'stripe',
'released' => 'payment-received',
],
'cash-in-hand' => [
'driver' => 'offline',
'authorized' => 'payment-offline',
],
],
```
### Custom payment driver
```php
use Lunar\Facades\Payments;
Payments::extend('custom', fn ($app) => $app->make(CustomPayment::class));
```
Extend `Lunar\PaymentTypes\AbstractPayment`. Implement `authorize()`, `capture()`, `refund()`.
Transaction types: `intent` (payment reserved, not yet captured), `capture` (payment captured), `refund`.
### Stripe integration
```php
use Lunar\Stripe\Facades\Stripe;
$intent = Stripe::fetchOrCreateIntent($cart); // create/get PaymentIntent
Stripe::syncIntent($cart); // update amount after cart changes
Stripe::cancelIntent($cart, CancellationReason::ABANDONED);
$intentId = Stripe::getCartIntentId($cart); // get existing intent ID
```
Webhook endpoint auto-registered at `stripe/webhook` (configurable). Verify with `LUNAR_STRIPE_WEBHOOK_SECRET`.
---
## Shipping
### Adding a custom shipping modifier
```php
namespace App\Modifiers;
use Lunar\Base\ShippingModifier;
use Lunar\DataTypes\Price;
use Lunar\DataTypes\ShippingOption;
use Lunar\Facades\ShippingManifest;
class CustomShippingModifier extends ShippingModifier
{
public function handle(Cart $cart, \Closure $next)
{
ShippingManifest::addOption(
new ShippingOption(
name: 'Standard Delivery',
description: 'Delivered in 3-5 days',
identifier: 'STANDARD',
price: new Price(500, $cart->currency, 1),
taxClass: TaxClass::first(),
)
);
return $next($cart);
}
}
```
Register in a service provider:
```php
public function boot(\Lunar\Base\ShippingModifiers $shippingModifiers): void
{
$shippingModifiers->add(CustomShippingModifier::class);
}
```
### Table Rate Shipping add-on
Install `lunarphp/table-rate-shipping`. Register the Filament plugin:
```php
LunarPanel::panel(fn ($panel) => $panel->plugin(new ShippingPlugin()))->register();
```
Concepts: **ShippingZone** (geographic region), **ShippingMethod** (delivery type), **ShippingRate** (zone + method + prices), **ShippingExclusionList** (products blocked from a zone).
Drivers: `ship-by` (cart total or weight tiers), `flat-rate`, `free-shipping` (minimum spend), `collection` (in-store pickup).
---
## Search Indexing
Lunar uses Laravel Scout for indexing. Models with the `Searchable` trait use indexers configured in `config/lunar/search.php`.
### ProductIndexer fields
`id`, searchable attributes, `status`, `product_type`, `brand`, variant `skus`, `created_at`.
### Custom indexer
```php
// config/lunar/search.php
'indexers' => [
Lunar\Models\Product::class => App\Search\CustomProductIndexer::class,
],
```
Custom indexer extends `Lunar\Search\ScoutIndexer`:
```php
class CustomProductIndexer extends ScoutIndexer
{
public function toSearchableArray(Model $model): array
{
return array_merge([], $this->mapSearchableAttributes($model));
}
public function getSortableFields(): array { return ['created_at']; }
public function getFilterableFields(): array { return ['status']; }
}
```
`mapSearchableAttributes()` automatically includes all attributes flagged as searchable in the admin panel.
---
## Access Control
Lunar uses `spatie/laravel-permission` scoped to the `staff` guard.
Built-in roles: `admin`, `staff`.
### Adding permissions
Create via migration (not through the UI — authorization logic must accompany every permission):
```php
// In a migration
\Spatie\Permission\Models\Permission::create(['name' => 'manage-contracts', 'guard_name' => 'staff']);
```
### Two-factor auth
```php
LunarPanel::forceTwoFactorAuth()->register(); // enforce 2FA for all staff
LunarPanel::disableTwoFactorAuth()->register(); // disable 2FA entirely (this project uses OTP instead)
```
### Authorization checks
```php
// Route middleware
Route::get('/custom', Controller::class)->middleware('can:manage-contracts');
// In code
Auth::user()->can('manage-contracts');
```
---
## Useful Facades Summary
| Facade | Purpose |
|---|---|
| `Lunar\Facades\CartSession` | Manage the active cart session |
| `Lunar\Facades\Payments` | Route payment calls to drivers |
| `Lunar\Facades\Pricing` | Resolve the best price for a purchasable |
| `Lunar\Facades\ShippingManifest` | Get/set shipping options on a cart |
| `Lunar\Facades\Discounts` | Validate coupons, register custom types |
| `Lunar\Facades\Taxes` | Register custom tax drivers |
| `Lunar\Facades\ModelManifest` | Replace Lunar models with custom implementations |
| `Lunar\Facades\StorefrontSession` | Manage channel, currency, customer for session |
| `Lunar\Admin\Support\Facades\LunarPanel` | Configure and extend the Filament panel |
---
## Artisan Commands
```bash
php artisan lunar:install # first-time setup
php artisan vendor:publish --tag=lunar # publish all config
php artisan vendor:publish --tag=lunar.migrations # publish migrations
php artisan scout:import "Lunar\Models\Product" # index products
php artisan scout:flush "Lunar\Models\Order" # flush order index
```
---
## Gotchas
Real bugs/traps hit while building against Lunar in this package — not obvious from reading Lunar's source in isolation.
- **`Lunar\Base\BaseModel` prefixes table names at construction time.** Mass-assigning a `parent_id` on a model using `kalnoy/nestedset`'s `NodeTrait` (e.g. `Collection`) triggers a mutator that queries the database *before* the table prefix is applied, throwing "relation does not exist". Use `appendToNode()`/`saveAsRoot()` instead of setting `parent_id` directly. See `MigrateImport\Shopify\Resolvers\CollectionResolver` for the pattern.
- **Don't trust a schema read from memory — re-check the actual migration/model file.** `products.brand` was assumed to be a plain string column based on an earlier read; it's actually `brand_id`, a real FK to a `Brand` model. Verify column names against the live `Schema::getColumnListing()` or the actual migration file, not recollection.
- **Lunar's default `Language` may not be `en`.** Don't hardcode `app()->getLocale()` for `TranslatedText`/translatable fields — use `Lunar\Models\Language::getDefault()->code` (wrapped here as `MigrateImport\DefaultLocale::code()`). A mismatch means data saves under the wrong locale key and silently doesn't render in the panel.
- **`attribute_data` is not a free-form array.** Values must be `Lunar\Base\FieldType` instances (`Text`, `TranslatedText`, `Number`, etc.), and the handle must be mapped to the product's `ProductType` via `mappedAttributes()`/`productAttributes()` — otherwise the value is silently dropped or won't render in the panel.
- **New `ProductType`s start with zero mapped attributes.** Creating one via `ProductType::create()` alone means `name`/`description` won't work until you `attach()` the existing system attributes to it.
- **`ProductOption.handle` must be unique and non-null if a product has more than one option.** Lunar's Filament variant-switcher widget does `SelectFilter::make($option->handle)` per option — two options with a `null`/matching handle throws "Filter must have a unique name" as a 500 when opening that product's variant pricing page. Always derive a slug and check uniqueness.
- **`Attribute.position` is per-group, and the panel sorts by it.** Hardcoding `position => 1` for multiple new attributes in the same group makes their order undefined/collide with existing attributes at position 1. Compute `max('position') + 1` per group instead.
- **Currency `decimal_places` isn't always 2.** A seeded/demo currency can have the wrong value (seen: EUR seeded with `decimal_places = 1`), which silently corrupts every price display (`€16.50` renders as `165`). If prices look wrong by a factor of 10, check the currency row before assuming the price-writing code is broken.
Reference in New Issue View Git Blame Copy Permalink