Lunar Laravel Package

Getting Started

Begin by installing the core package and admin component with composer require lunarphp/lunar. Run php artisan lunar:install to publish configuration, migrations, seeders (including Spatie permissions roles), and sample data. Authenticate your first admin user via php artisan make:filament-user. Navigate to /admin to access the Filament-based admin panel — your default entrypoint for managing catalogs, orders, customers, and system settings.

Implementation Patterns

Use the admin panel as a dedicated backend for non-technical staff while building custom frontend experiences (e.g.,.Headless storefronts) with lunarphp/core models. Extend core resources — like ProductResource or OrderResource — to add custom fields, validation, and actions (e.g., bulk status updates). Leverage Filament’s form builders to manage variant-specific data, and integrate real-time order workflows using Livewire actions. Customize branding and navigation by publishing Filament theme views or overriding config/filament.php. For integrations, dispatch jobs from Lunar events (e.g., OrderPlaced) or use lunarphp/core’s repository pattern to sync with ERP/PIM systems.

Gotchas and Tips

⚠️ Strict version coupling: The admin package depends on lunarphp/core with self.version, making it critical to update both packages in lockstep — partial updates cause runtime failures.
⚠️ Permission seeding quirks: Role/permission seeding relies on spatie/laravel-permission; if config('permissions.autoload') is disabled, manually sync using php artisan db:seed --class=Spatie\Permission\PermissionSeeder after install.
💡 PDF invoice generation: Add a “Download Invoice” button to OrderResource by leveraging the included InvoicePdf class — inject it into a custom action using DomPDF and attach it to the Filament action chain.
💡 Media library enhancements: All product images use Spatie Media Library; define responsive conversions and named collections (e.g., images, thumbnails) in config/lunar.php under the media key.
🔧 Full extensibility: Override any Filament component (resource, page, widget) by extending the original class, registering your version in AppServiceProvider, and using Filament::serving() hooks to inject custom logic. Enable two-factor auth for admin staff by adding lunarphp/filament3-2fa and publishing its config.