Download the PHP package lunarphp/filament without Composer

Lunar Filament Bridge

Filament v5 components, widgets, schemas, and tables for Lunar — the e-commerce primitives behind the Lunar admin panel, packaged so you can drop them into any Filament v5 panel.

This package ships the reusable building blocks: a product picker that knows about Lunar's translated names and Scout-aware search, a translated-text input that round-trips your locale data, dashboard chart widgets pre-wired against the order schema, a complete set of resource forms and tables for every commerce model, and the attribute system that powers Lunar's flexible product data.

If you want Lunar's complete turnkey admin panel — navigation, branding, auth, dashboard — install lunarphp/admin instead. It depends on this package.

Requirements

• PHP 8.3+
• Laravel 11+ (Lunar v2 supports Laravel 13)
• Filament v5
• lunarphp/core (installed automatically)

Installation

The service provider auto-registers via Laravel's package discovery. No further wiring is required to start using the form components, table columns, infolist entries, or selectors.

To run Lunar's database migrations against your app:

What's in the box

Entity selectors

Sixteen first-class Select (and one MorphToSelect) subclasses for picking Lunar records by relationship. They all share one Scout-aware search backend, default to translated names where applicable, and ship with sensible Lunar-flavoured defaults.

Basic usage

Drop a selector into any Filament form, schema, or action — it works exactly like a Select:

Searching, filtering, and de-duplication

->excludeAttached() is a no-op outside a RelationManager context, and inside one it dedupes against the getRelationship()->get() ids automatically — including for AttachAction-driven attach modals.

Variants

Collections

The default label format is the breadcrumb path: "Men > Outerwear > Jackets".

Country & State (dependent datalist)

CountrySelect::iso3() switches the field to store ISO3 codes instead of foreign keys — useful for TaxZone countries and other ISO-keyed columns.

Polymorphic discount targets

Using a selector inside AttachAction

Filament's AttachAction::recordSelect(fn ($select) => …) callback hands you the existing Select rather than letting you swap in a subclass. Lunar selectors expose a static applyTo($select) helper for exactly this case:

Picking your own search backend

If you need to bend the search query for one call-site, the modifyOptionsQueryUsing() hook is stackable:

The underlying search service is Lunar\Filament\Forms\Components\Support\RecordSearch — call it directly from your own components:

It prefers Laravel Scout when both lunar.filament.scout_enabled is true and the model uses Scout's Searchable trait, falls back to a translated-attribute DB search, and falls back again to a plain name column search for models that have neither.

Other form components

Attributes — the Lunar attribute editor

Renders editable fields for every attribute attached to the current model (Product, Brand, Collection, etc.) according to its registered field type. Each field type knows how to draw itself, cast its data, and synthesize across Livewire.

An attribute's validation_rules (a list of Laravel rule strings, editable on the attribute form — spec 0062) are applied to the rendered field on top of the required flag, so ['min:2', 'max:10'] on a text attribute validates exactly as those rules would on any form input.

TranslatedText — locale-aware text input

Renders one input per Lunar Language, hydrating from attribute_data->name->value (translated Text and TranslatedText field types). Pair with TranslatedRichEditor for HTML content.

MediaSelect, Tags, Vimeo, YouTube

Spatie Media Library integration, a chip-style tag input with autocomplete suggestions, and embedded-video field types for common content needs.

AttributeSelector, PermissionSelector

CheckboxList-based pickers for product type → attribute mapping and staff → permission assignment respectively.

Table columns

TranslatedTextColumn

Renders a translated attribute, with optional tooltip when truncated:

ThumbnailImageColumn

Renders a square thumbnail resolved from a closure:

Infolist entries

• Lunar\Filament\Infolists\Components\Tags — read-only tag chips.
• Lunar\Filament\Infolists\Components\Transaction — payment-transaction summary card.

Resource schemas, tables, and relation managers

Each Lunar commerce model has a complete Filament schema set under Lunar\Filament\Schemas\{Model} and Lunar\Filament\Tables\{Model}. They are the same classes the Lunar admin panel uses internally.

Every schema/table class also exposes granular getXxxFormComponent() / getXxxTableColumn() static helpers, so you can pick a single field or column without inheriting the rest:

Models with a complete schema, table, infolist, and relation managers: Activity, Attribute, AttributeGroup, Brand, Channel, Collection, CollectionGroup, Currency, Customer, CustomerGroup, Discount, Language, Order, Product, ProductOption, ProductType, ProductVariant, Staff, Tag, TaxClass, TaxRate, TaxZone.

Actions

First-class Filament Action / BulkAction classes for every commerce verb the admin uses. The Filament class owns the modal schema, labels, notifications, and visibility predicate; the underlying business logic lives in a Lunar\Core\Actions\* counterpart so a CLI, API, or different UI can call the same code.

Drop into any header/row/bulk action array — they work like any Filament action:

Need the verb outside Filament (e.g. an API endpoint)? Call the core action directly:

The core action validates the amount against RefundOrder::availableToRefund($order), dispatches through the underlying payment driver, and returns the driver's PaymentRefund result. Bulk Filament actions are thin loops over the same core action wrapped in a single transaction.

Shared Concerns traits (InteractsWithTransactions, ConfirmsDestructiveAction) cover the repeating form fragments — extend or override them in a subclass to bend the schema without re-implementing the whole action.

Global search

Each searchable Lunar model has a GlobalSearchDescriptor subclass that owns its searchable attribute list, result title, result details, and eager-loaded query. Consumers compose their own Filament resource and opt in with one trait and one property:

The trait forwards getGloballySearchableAttributes, getGlobalSearchResultTitle, getGlobalSearchResultDetails, and getGlobalSearchEloquentQuery to the descriptor, and routes the actual constraint-building through RecordSearch — the same Scout-vs-translated-attribute backend the entity selectors use. Scout is used when lunar.filament.scout_enabled=true and the model uses Laravel\Scout\Searchable; otherwise the query falls back to LIKE-matching across the resource's attribute list plus any searchable TranslatedText attributes.

getGlobalSearchResultUrl stays on the resource — only the resource knows its own URL.

Descriptors shipped: OrderGlobalSearch, ProductGlobalSearch, CustomerGlobalSearch, CollectionGlobalSearch, BrandGlobalSearch.

There is no panel-wide auto-registration to enable or disable — global search is opt-in per resource via the trait. A consumer who only wants Lunar models in their existing resources adds the trait there; one who omits it gets no Lunar global-search rows.

Dashboard widgets

Drop into your panel's widgets([…]) configuration:

Also available: Lunar\Filament\Widgets\Customer\CustomerStatsOverviewWidget, Lunar\Filament\Widgets\Collections\CollectionTreeView, Lunar\Filament\Widgets\Products\ProductOptionsWidget, Lunar\Filament\Widgets\Products\VariantSwitcherTable.

Widgets and tables that link to Lunar records (e.g. "click an order in this table") resolve the target page through lunar.filament.record_urls.{key}. Point each key at your own panel's pages in config/lunar/filament.php:

Prefer the class-string forms: config has to survive php artisan config:cache, and a closure anywhere in the tree makes the whole application's config non-serializable. A callable — invoked as $resolver($record, $context) — is still accepted for a resolver that genuinely can't be expressed as a class and a page name, at the cost of config caching. When a key is null or unset, the component gracefully omits the link. The lunarphp/admin shell wires all three keys to its own pages at boot.

Attribute system

Lunar's flexible-attributes system is configured per-product-type and rendered automatically by the Attributes form component. The shipped field types live under Lunar\Filament\FieldTypes\* — TextField, TranslatedText, Dropdown, Toggle, Number, File, ListField, Vimeo, YouTube. Each is auto-registered via the service provider.

Register your own field type:

Field type configuration forms

The "configure this attribute" form (min/max, dropdown options, richtext toggle, …) is built from the core field type's renderer-agnostic descriptors — FieldType::getConfigurationFields() on Lunar\Core\FieldTypes\* — mapped onto Filament components by Lunar\Filament\Support\Forms\ConfigurationFieldMapper. A custom field type registered with core's FieldTypeManifest therefore gets a working configuration form here (and in the Inertia panel) without any bridge code: declare descriptors (text, number, toggle, select, tags, lookups) and validation via getConfig().

To replace the derived form with bespoke Filament components, override getConfigurationFields() on your BaseFieldType subclass — a non-empty return wins over the descriptor mapping.

Customisation strategies

Three ways to bend the bridge to your own UX, each with different upgrade implications.

Extension hooks

Register your extensions in a service provider's boot() method. Hooks stack — register multiple extensions against the same target and each runs in registration order, passing its return value into the next.

Subclass and rebind

Publish stubs

Copies every schema, table, infolist, and relation manager into app/Filament/… (configurable in config/lunar/filament.php → publish_path). The runtime resolver prefers your published copy when both exist.

You can also publish:

Configuration

Publish and tweak config/lunar/filament.php to change:

• publish_path — where stub publication writes files (default: app/Filament).
• resolver.prefer_published — runtime preference between published and bridge classes.
• record_url_resolvers — closures that map a record + key to a URL inside your panel.
• enable_variants — whether the variants manager shows when editing a product (default: true).
• pdf_rendering — 'download' or 'stream', controlling how PDFs are handled when browsing the resource (default: 'download').
• scout_enabled — whether to prefer Laravel Scout over the translated-attribute DB search on supported models (default: false).

Translations

The package ships translations in 16 locales: ar, bg, de, en, es, fa, fr, hr, hu, mn, nl, pl, pt_BR, ro, tr, vi. Override per-key by publishing the lang files (php artisan vendor:publish --tag=lunar-filament.lang) and editing lang/vendor/lunar-filament/{locale}/….

Standalone Filament panel example

A minimum panel that uses bridge components without Lunar's admin shell:

Versioning

The bridge tracks Filament's release cadence. A Filament major (v5 → v6) drives a bridge major; the Lunar admin shell tightens its constraint when ready.

For v2 the package is developed inside the Lunar monorepo. It extracts into its own repository (lunarphp/filament) at the v2.0.0 stable cut.

License

MIT.