How We Used LunarPHP for Headless E-Commerce in Our Project?

Starting each new e-commerce project from scratch often means repeating the same tasks: implementing features like Products, Categories, Carts, Orders, and Payment Integrations. While frameworks like Aimeos and Bagisto are solid choices, they come with their own limitations.

In this article, we want to introduce you to LunarPHP Headless E-commerce and share why it became our go-to for one of our recent projects. We’ll take you through our implementation journey and highlight the benefits and efficiencies we discovered along the way.

What Is LunarPHP Headless ECommerce?

LuranPHP is an open-source, headless eCommerce framework that provides externally usable features without predefined structural constraints. Developers love to architect their apps but frequently get frustrated when bound to specific project folder architectures and code execution pipelines enforced by library developers.

Lunar provides database migrations, models, relations between these models, and attached and usable calculation pipelines (cart total/subtotal calculation, discounts), among many other features right out of the box. It is easily installable as a Composer package, integrating seamlessly into your codebase and becoming immediately usable. There is even an option to use their starter kit and code a full-stack application using Livewire.

The features you get right out of the box include:

• Cart implementation

• Orders and Order Statuses implementation

• Advanced Discount Management System

• Category tree storage architecture and management ability

• Multi-Language support

• Laravel Scout Integration for a rapid search experience

• Trait to enhance your application user model with e-commerce relations

• Smart and polymorphic URL management system

• Currency Management

Basically, you get everything needed to build an eCommerce solution of any scale.

Why Did We Need It?

Our client was running a growing eCommerce SaaS solution. However, as more retailers joined and new markets opened up, the current solution proved to be insufficiently scalable. Native PHP and accumulated redundancy had taken their toll. There was a clear need for a next-generation, multi-tenant web application to support the client’s plans.

Managing an already launched and active project is very different from handling a startup. You need to maintain all the user-loved features while also dedicating enough time to developing new ones to justify the tech switch for customers. Our selection of technologies proved very effective in this case. Since the current tenancy implementation involved separate app instances for each retailer, we decided to utilize the Tenancy For Laravel package, which we had positive experiences with in previous projects.

The eCommerce side of things was handled by LunarPHP, and the need for rapid Admin Dashboard development was addressed by FilamentPHP. The front-end was managed by NextJS. LunarPHP is headless, so it doesn’t concern itself with the client-side technology you are using or impose any directory structures or endpoint designs. This made the whole process extremely flexible.

How Did We Manage To Create E-Commerce Website With Lunarphp?

In our eCommerce SaaS, each retailer is a separate tenant. Each tenant has its own selection of products, variants, categories, prices, etc. All data needed to be synced from a third-party EPOS API, with categories, brands, and products later enriched via another API. Using multiple databases for tenants was the best way to ensure data segregation and correctness. Therefore, the migrations provided by Lunar were applied to the tenant databases.

Since Lunar already designed the tables and connections between products, product variants, their attributes, options, and categories, we focused solely on the API synchronization aspect. This truly saved us valuable time.

Fig 1.1 Part of Database Migrations Offered by Lunar

One of the other features that Lunar comes with is the approach to translatable fields. Any table created by the framework accounts for this, so, for example, the name column of the products table looks like this:

Fig 1.1 Part of Database Migrations Offered by Lunar

In e-commerce, one frequently faces the issue of variable product options. You may be selling hats, which are available in colors, and bike parts that vary only in size. Lunar mitigates this problem with a smart database structure. First, you define an option as a separate entity in the product_options table:

Fig. 1.3 product_options table

Then, you link it to a product via the product_product_option table:

Fig. 1.4 product_product_option pivot table

 Then, you make specific values of an option available for a product:

Fig. 1.5 product_option_values table

 And lastly, you connect the option values to specific product variants. Meaning you are creating a particular product with particular traits. Ex. Large Blue T-Shirt:

Fig. 1.6 product_option_value_product_variant table

Lunar also frequently uses a concept called polymorphism. There are cases in real-life practice when prices should be attachable to different entities. For example, you may want to set different prices for various sizes of the same T-shirt you are selling but still be able to set prices generally for other products. Prices are stored in a separate table in Lunar, and it contains a polymorphic relation to entities they’re bound to and are gracefully picked up by Laravel during code execution:

Fig. 1.7 lunar_prices table

This way, the price can be dynamically bound to any of our Laravel models. The same goes for purchasables. Any model in your project can virtually become a cart or order item:

Fig. 1.8 Purchasables can be anything

 Carts and discounts are indeed a vital part of any e-commerce. The details may differ based on the client's requirements, but the core and backbone stay the same. A customer should be able to add items to the cart, change quantities of items, delete items, apply coupon codes and so on. All of that is already done for you in Lunar. And it’s highly extensible. A simple way to calculate cart total, subtotal, price and discount breakdowns comes right out of the box:

Fig. 1.9 Cart calculation

 In order to implement new logic for applying a discount, you create a new class for that discount type and implement the whole flow yourself. Lunar also gives you the ability to override already existing discount types:

Fig. 2.1 AmountOff Discount Type

 This level of extensibility and configuration makes LunarPHP a solid choice for custom e-commerce requirements.

How Are Things With The Administration Panel?

When creating e-commerce website with LunarPHP, you are not bound to use something specific for your administration panel needs. If rapid development is required, an in-house Filament/Livewire-based admin panel is probably the best decision you can make. Filament ensures fast addition of common CRUD functionality, providing resources, statistical widgets and many more crucial features for any e-commerce website. The CRUDs for existing structures like products, categories, and prices are already there and are open to experimentation.
Fig. 2.2 LunarPHP Admin Hub

 In our case, we’ve modified the default Admin Hub quite extensively due to specific client requirements. No two complex software solutions are the same.

Finally, it’s worth noting that all of the technologies used for this project work extremely well with each other. Tenancy for Laravel ensures multi-database tenancy, LunarPHP makes most of the tenants database and handles all e-commerce operations, while Filament provides a powerful platform for admin panel development.