 }}){kind=icon}
[](https://docs.laravelshopper.dev/v1/extending/control-panel#adding-control-panel-routes)
Adding control panel routes
--------------------------------------------------------------------------------------------------------------------------
If you need to have custom routes for the control panel:
1. Create a routes file. Name it whatever you want, for example: `routes/shopper.php`
2. Then add this to your `shopper/routes.php` file so that all routes are dynamically loaded:
'custom_file' => base_path('routes/shopper.php'),
3. If you want to add middleware to further control access to the routes available in this file you can add in the key `middleware` of the `shopper/routes.php` file
'middleware' => [\
'my-custom-middleware',\
'permission:can-access',\
],
[Orders](https://docs.laravelshopper.dev/v1/orders)
[Controllers](https://docs.laravelshopper.dev/v1/extending/controllers)
⌘I
---
# Categories - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v1/categories#content-area)
This is documentation for Shopper v1, which is no longer maintained. Please refer to the [v2 docs](https://docs.laravelshopper.dev/v2)
for the latest information.
For example, if you sell clothing, you might have “t-shirts”, “hoodies” and “pants” as categories.
[](https://docs.laravelshopper.dev/v1/categories#overview)
Overview
-----------------------------------------------------------------------
Shopper gives you a possibility to categorize your products in a very flexible way, which is one of the most vital functionalities of the modern e-commerce systems. The categories system in Shopper use the [Laravel Adjacency List](https://github.com/staudenmeir/laravel-adjacency-list)
package to create categories trees like this
Category
|
|\__ Women
| \_ T-Shirts
| \_ Shirts
| \_ Dresses
| \_ Shoes
|
|\__ Men
| \_ Accessories
| |--> Bags
| |--> Jeans
| |--> Sunglasses
| \_ Jeans
| \_ T-shirts
| \_ Shoes
|
###
[](https://docs.laravelshopper.dev/v1/categories#fields)
Fields
The model used is `Shopper\Framework\Models\Shop\Product\Category`.
| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | autoinc | | auto |
| `name` | string | yes | |
| `slug` | string | yes | Unique, default value is generated using category name |
| `description` | longText | no | Nullable |
| `position` | string | no | Default `0` |
| `is_enabled` | boolean | no | Default `false` |
| `seo_title` | string | no | Nullable, for seo title max length is 60 |
| `seo_description` | string | no | Nullable, for seo description max length is 160 |
| `parent_id` | bigint | no | |
Models are customizable, and we recommend changing the **Category** model when you configure your store. To change the model you need to look at the configuration file `config/shopper/system.php` at the key `models`.
Let’s keep in mind the modification that was made in the previous section regarding [Brands](https://docs.laravelshopper.dev/brands)
.
return [\
'models' => [\
/*\
* Eloquent model should be used to retrieve your brands. Of course,\
* it is often just the "Brand" model but you may use whatever you like.\
*\
* The model you want to use as a Brand model needs to extends the\
* `\Shopper\Framework\Models\Shop\Product\Brand` model.\
*/\
'brand' => \App\Models\Brand::class,\
\
/*\
* Eloquent model should be used to retrieve your categories. Of course,\
* it is often just the "Category" model but you may use whatever you like.\
*\
* The model you want to use as a Category model needs to extends the\
* `\Shopper\Framework\Models\Shop\Product\Category` model.\
*/\
'category' => \Shopper\Framework\Models\Shop\Product\Category::class,\
]\
];
1. Create your own model that you have to use
php artisan make:model Category
Once the `app/Models/Category.php` model is created in our app folder, we will make it extend from the `Shopper\Framework\Models\Shop\Product\Category` model available in Shopper.
2. Extend our Category model from the Category Shopper Model
namespace App\Models;
use Shopper\Framework\Models\Shop\Product;
class Category extends Product\Category
{
}
3. Update `category` key for the model on the `system.php` config file to use our new model
return [\
'models' => [\
/*\
* Eloquent model should be used to retrieve your brands. Of course,\
* it is often just the "Brand" model but you may use whatever you like.\
*\
* The model you want to use as a Brand model needs to extends the\
* `\Shopper\Framework\Models\Shop\Product\Brand` model.\
*/\
'brand' => \App\Models\Brand::class,\
\
/*\
* Eloquent model should be used to retrieve your categories. Of course,\
* it is often just the "Category" model but you may use whatever you like.\
*\
* The model you want to use as a Category model needs to extends the\
* `\Shopper\Framework\Models\Shop\Product\Category` model.\
*/\
'category' => \App\Models\Category::class,\
]\
];
###
[](https://docs.laravelshopper.dev/v1/categories#components)
Components
Livewire components for managing categories are available in the component configuration file `config/shopper/components.php`.
use Shopper\Framework\Http\Livewire;
return [\
'livewire' => [\
\
'categories.browse' => Livewire\Categories\Browse::class,\
'categories.create' => Livewire\Categories\Create::class,\
'categories.edit' => Livewire\Categories\Edit::class,\
\
'tables.categories-table' => Livewire\Tables\CategoriesTable::class,\
\
];\
];
[](https://docs.laravelshopper.dev/v1/categories#manage-categories)
Manage Categories
-----------------------------------------------------------------------------------------
Categories are determinant of how people will navigate on your site and search for your products. You should focus on your category tree and how categories are organized even before you start creating product sheets. The categories are accessible via the **Categories** Menu on the left sidebar. The display page is rendered by the Livewire component `Shopper\Framework\Http\Livewire\Categories\Browse` and for the display of the categories table is the component `Shopper\Framework\Http\Livewire\Tables\CategoriesTable`. You can modify them in the component configuration file to use your own.
###
[](https://docs.laravelshopper.dev/v1/categories#create-category)
Create category
Click on the “Create” button on the categories page, and a creation form appears.
Save your changes in order to be taken back to the categories list. Required fields are marked with an **asterisk (\*)** The SEO section allows you to define how your category information should be displayed in search engines. To modify the content you click on the button “Edit SEO preview”. It uses the same blade component as the brands.
Once you have finished configuring your category, save it, and you are ready to fill it with products. If you use another interface (e.g. API) to save your categories, you can save directly using your Model
use App\Models\Category;
$category = Category::create([\
'name' => $name = 'Clothes',\
'slug' => $name,\
'is_enabled' => true,\
]);
The slug cannot be null, you have to fill in the value of the category name and according to that the slug will be generated. In case a slug already exists, the slug will be automatically extended to prevent duplicates:
use App\Models\Category;
$category1 = Category::create(['name' => 'Category', 'slug' => 'Category']);
$category2 = Category::create(['name' => 'Category', 'slug' => 'Category']);
echo $category1->slug;
// category
echo $category2->slug;
// category-1
And if the category has a parent, the child’s slug will be generated with the parent’s directly This generation is done when adding a category in Shopper. But you can change this behavior by extending the category create [Shopper\\Framework\\Http\\Livewire\\Categories\\Create](https://github.com/shopperlabs/framework/blob/main/src/Http/Livewire/Categories/Create.php)
Livewire component or by creating a new one.
use App\Models\Category;
$category = Category::create(['name' => 'Photo', 'slug' => 'photo']);
$categoryChild = Category::create([\
'name' => 'Camera',\
'slug' => $this->parent ? $this->parent->slug . '-' . 'Camera' : 'Camera',\
'parent_id' => $caregory->id\
]);
echo $category->slug;
// photo
echo $categoryChild->slug;
// photo-camera
####
[](https://docs.laravelshopper.dev/v1/categories#create-category-with-parent)
Create Category with parent
use App\Models\Category;
$parent = Category::create([\
'name' => $name = 'Clothes',\
'slug' => $name,\
'is_enabled' => true,\
]);
$child = Category::create([\
'name' => 'Jeans',\
'slug' => 'jeans',\
'parent_id' => $parent->id,\
'is_enabled' => true,\
]);
On Shopper, to specify the parent category you just have to choose via the select field
###
[](https://docs.laravelshopper.dev/v1/categories#update-category)
Update category
The “Modify” button allows you to modify the category.
It is important to know that if you update the category name, the slug will automatically be updated as well.
[](https://docs.laravelshopper.dev/v1/categories#retrieve-data)
Retrieve Data
---------------------------------------------------------------------------------
With Shopper Framework you are the master of your front-end. After extending the model you can make all the necessary queries to retrieve your data. We just recommend that you always use the `enabled` scope to ensure that only active categories are visible
use App\Models\Category;
$categories = Category::enabled()->get(),
To find a category with his children or parent, etc. The following functions are available.
* `ancestors()`: The model’s recursive parents.
* `ancestorsAndSelf()`: The model’s recursive parents and itself.
* `bloodline()`: The model’s ancestors, descendants and itself.
* `children()`: The model’s direct children.
* `childrenAndSelf()`: The model’s direct children and itself.
* `descendants()`: The model’s recursive children.
* `descendantsAndSelf()`: The model’s recursive children and itself.
* `parent()`: The model’s direct parent.
* `parentAndSelf()`: The model’s direct parent and itself.
* `rootAncestor()`: The model’s topmost parent.
* `siblings()`: The parent’s other children.
* `siblingsAndSelf()`: All the parent’s children.
$ancestors = Category::find($id)->ancestors;
$categories = Category::with('descendants')->get();
$categories = Category::whereHas('siblings', function ($query) {
$query->where('name', '=', 'Photo');
})->get();
$total = Category::find($id)->descendants()->count();
Category::find($id)->descendants()->update(['is_enabled' => false]);
Category::find($id)->siblings()->delete();
The complete documentation is available in the readme of [Laravel Adjacency List](https://github.com/staudenmeir/laravel-adjacency-list)
[Brands](https://docs.laravelshopper.dev/v1/brands)
[Collections](https://docs.laravelshopper.dev/v1/collections)
⌘I
---
# Configuration - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v1/configuration#content-area)
This is documentation for Shopper v1, which is no longer maintained. Please refer to the [v2 docs](https://docs.laravelshopper.dev/v2)
for the latest information.
[](https://docs.laravelshopper.dev/v1/configuration#config-files)
Config Files
----------------------------------------------------------------------------------
With the installation of Shopper you will find new configurations files located in `config/shopper/`. They are PHP files named by area of responsibility.
config/shopper/
admin.php
auth.php
components.php
core.php
media.php
models.php
routes.php
settings.php
And the `admin.php` is the main file, you can find various options to change the configuration of your Shopper installation.
[](https://docs.laravelshopper.dev/v1/configuration#system)
System
----------------------------------------------------------------------
All the basic configurations for using shopper can be found in this file. The management of the locale, the models to use and additional resources (scripts and styles) to the administration.
###
[](https://docs.laravelshopper.dev/v1/configuration#brand-logo)
Brand logo
By default, the Shopper logo will be used as the brand logo in the administration panel. To update it you just have to fill in the logo link in your public folder
/*
|--------------------------------------------------------------------------
| Brand Name
|--------------------------------------------------------------------------
|
| This will be displayed on the login page and in the sidebar's header.
|
*/
'brand' => '/images/v1/logo.svg',
###
[](https://docs.laravelshopper.dev/v1/configuration#controllers)
Controllers
By default Shopper loads controllers that are defined in this namespace. You can change it if you have a different structure. These controllers are used to extend and add functionalities in the administration. In your config file you have the controllers key that define the controller’s namespace for your extended Controllers:
'controllers' => [\
'namespace' => 'App\\Http\\Controllers\\Shopper',\
],
###
[](https://docs.laravelshopper.dev/v1/configuration#models)
Models
Models used are defined in the models key, if you want to use your own models you can replace them on the `models.php` config file.
'brand' => \Shopper\Core\Models\Brand::class,
'category' => \Shopper\Core\Models\Category::class,
'collection' => \Shopper\Core\Models\Collection::class,
'product' => \Shopper\Core\Models\Product::class,
###
[](https://docs.laravelshopper.dev/v1/configuration#additional-resources)
Additional resources
During your work you may need to add your own style tables or javascript scenarios globally for all the pages, so you need to add them to relevant arrays.
'resources' => [\
'stylesheets' => [\
//'css/custom.css',\
],\
'scripts' => [\
//'js/custom.js',\
],\
],
[](https://docs.laravelshopper.dev/v1/configuration#routes)
Routes
----------------------------------------------------------------------
The configuration of the routes allows you to specify a prefix to access your dashboard, the addition of middleware and the configuration file to add more routes to your administration.
###
[](https://docs.laravelshopper.dev/v1/configuration#prefix)
Prefix
// config/shopper/admin.php
'prefix' => env('SHOPPER_PREFIX', 'cpanel'),
The system installed on the website can be easily defined by the dashboard prefix, for example it is `wp-admin` for WordPress, and it gives an opportunity to automatically search for old vulnerable versions of software and gain control over it. There are other reasons but we won’t speak of them in this section. The point is that Shopper allows to change dashboard prefix to every other name, `admin` or `administrator` for example.
###
[](https://docs.laravelshopper.dev/v1/configuration#middleware)
Middleware
// config/shopper/routes.php
'middleware' => [],
Shopper gives you the ability to add middleware to all of your routes. These middlewares will be applied to all the routes of your administration.
###
[](https://docs.laravelshopper.dev/v1/configuration#additional-dashboard-routes)
Additional dashboard routes
// Eg.: base_path('routes/shopper.php')
'custom_file' => null,
By default none of your routes in the `web.php` file will be accessible and loaded in the shopper administration. So that your routes added in the sidebar can have the middleware applied to the dashboard, you must fill in an additional routing file and this will be automatically loaded by Shopper’s internal RouteServiceProvider.
[](https://docs.laravelshopper.dev/v1/configuration#components)
Components
------------------------------------------------------------------------------
The main features of Shopper is to handle Livewire components to add new functionnalities to your admin panel. For this purpose you have a component file that lists all Livewire components used within Shopper. You can for each feature modify the associated or extends component to add functionality or even change the view to fit your own logic. Here is an example of some components
use Shopper\Http\Livewire\Components;
return [\
/*\
|--------------------------------------------------------------------------\
| Livewire Components\
|--------------------------------------------------------------------------\
|\
| Below you reference all the Livewire components that should be loaded\
| for your app. By default all components from Shopper Kit are loaded in.\
|\
*/\
'livewire' => [\
'account.devices' => Components\Account\Devices::class,\
'account.dropdown' => Components\Account\Dropdown::class,\
'account.password' => Components\Account\Password::class,\
],\
];
[](https://docs.laravelshopper.dev/v1/configuration#settings)
Settings
--------------------------------------------------------------------------
Settings are a very important part of an e-commerce site administration. Shopper has understood this very well and has set up a settings file, to allow you to add or modify the default settings of Shopper. In this file you can add parameters or delete those you don’t need to simplify your store or to make it larger
return [\
\
/*\
|--------------------------------------------------------------------------\
| Setting Menu\
|--------------------------------------------------------------------------\
|\
| The menu for the generation of the page settings and layout.\
| BladeUIKit Heroicon is the icon used. See https://blade-ui-kit.com/blade-icons?set=1\
|\
*/\
\
'items' => [\
[\
'name' => 'General',\
'description' => 'View and update your store information.',\
'icon' => 'heroicon-o-cog',\
'route' => 'shopper.settings.shop',\
'permission' => null,\
],\
[\
'name' => 'Staff & permissions',\
'description' => 'View and manage what staff can see or do in your store.',\
'icon' => 'heroicon-o-users',\
'route' => 'shopper.settings.users',\
'permission' => null,\
],\
\
],\
];
[](https://docs.laravelshopper.dev/v1/configuration#mapbox)
Mapbox
----------------------------------------------------------------------
Shopper uses Mapbox to enter the geographic coordinates (latitude and longitude) of your store so that you can easily tell your customers your location. To activate mapbox you need to go to the [API](https://docs.mapbox.com/mapbox-gl-js/api/)
documentation and create an API token. Once this is done you need to add the key `MAPBOX_PUBLIC_TOKEN` with the token value to your `.env` file
MAPBOX_PUBLIC_TOKEN=your_token_here
[](https://docs.laravelshopper.dev/v1/configuration#update-configurations)
Update Configurations
----------------------------------------------------------------------------------------------------
In your `config/filesystems.php` config file add the following to the disks and links section:
'disks' => [\
// Shopper Uploads Disks. [tl! highlight:13]\
'avatars' => [ // [tl! collapse:start]\
'driver' => 'local',\
'root' => storage_path('app/avatars'),\
'url' => env('APP_URL').'/avatars',\
'visibility' => 'public',\
], // [tl! collapse:end]\
\
'uploads' => [ // [tl! collapse:start]\
'driver' => 'local',\
'root' => storage_path('app/uploads'),\
'url' => env('APP_URL').'/uploads',\
'visibility' => 'public',\
], // [tl! collapse:end]\
\
],
/*
|--------------------------------------------------------------------------
| Symbolic Links
|--------------------------------------------------------------------------
|
| Here you may configure the symbolic links that will be created when the
| `storage:link` Artisan command is executed. The array keys should be
| the locations of the links and the values should be their targets.
|
*/
'links' => [\
// [tl! highlight:2]\
public_path('avatars') => storage_path('app/avatars'),\
public_path('uploads') => storage_path('app/uploads'),\
],
###
[](https://docs.laravelshopper.dev/v1/configuration#create-new-folders)
Create New Folders
After adding the 2 entries in the filesystem config file, you must create them and add them to the .gitignore file. In your storage directory create 2 new folders called `avatars` and `uploads`.
mkdir storage/app/avatars && mkdir storage/app/uploads
In each new folder that you have created (avatars and uploads) you must create a .gitignore file which will contain the following line
*
!.gitignore
[Installation](https://docs.laravelshopper.dev/v1/installation)
[Customization](https://docs.laravelshopper.dev/v1/customization)
⌘I
---
# Collections - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v1/collections#content-area)
This is documentation for Shopper v1, which is no longer maintained. Please refer to the [v2 docs](https://docs.laravelshopper.dev/v2)
for the latest information.
In most e-commerce tools, collections are considered as categories. And especially on Shopify, collections are a great feature for grouping products. And for the constitution of the collections we got closer to what Shopify offers in terms of configuration, and the management of collections in Shopper is inspired by Shopify.
[](https://docs.laravelshopper.dev/v1/collections#context)
Context
----------------------------------------------------------------------
For example if you have a store that sells various electronic products, you will probably have categories like “Phones”, “Computers”, “Cameras” etc. Each of these categories may have several products that can be listed. And to try to group the products in an even more detailed way you can create for example a collection called “Gaming Collection” and specify in this collection that any product with certain conditions can be included. And that Gaming Collection can have products that even come from various categories in your site (desktop, laptop, monitor, and many others of the same type) or that don’t even have categories (very rare case in e-commerce sites). Let’s use Netflix as an example. Categories are essentially genres: adventure, action, horror, romance, etc., while collections are similar to a TV series or movie sequels that are ultimately meant to be viewed together.
[](https://docs.laravelshopper.dev/v1/collections#collections-vs-categories)
Collections vs Categories
----------------------------------------------------------------------------------------------------------
The question is essential, it is difficult to find this type of configuration on e-commerce tools because most of the time categories, collections or taxonomies are used to perform the same action **group products**. The advantage of having collections in addition to categories in Shopper is to differentiate or optimize the search for products by customers in your store.
###
[](https://docs.laravelshopper.dev/v1/collections#depth)
Depth
A collection can’t have a child or a parent like a category. So all the collections are at the same hierachical level.
###
[](https://docs.laravelshopper.dev/v1/collections#condition)
Condition
Where products can be added to any category, collections cannot. Depending on the type of collection you want to create (Manual or Automatic) you will find yourself creating conditions or rules for the products that should be in that collection.
[](https://docs.laravelshopper.dev/v1/collections#overview)
Overview
------------------------------------------------------------------------
As mentioned above, the collections in Shopper are inspired by [Shopify collections](https://help.shopify.com/en/manual/products/collections)
. So there are also 2 types of collections: “Manual” and “Automatic” and the configuration for each is different.
###
[](https://docs.laravelshopper.dev/v1/collections#fields)
Fields
As the collections can be automatic, they are managed by 2 Models, the Collection model and the model for rules associated with automatic collections. Manual collections do not need to have rules.
* Collection model is `Shopper\Framework\Models\Shop\Product\Collection`.
* Rule model is `Shopper\Framework\Models\Shop\Product\CollectionRule`
**Collection Model**
| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | autoinc | | auto |
| `name` | string | yes | |
| `slug` | string | yes | Unique, default value is generated using collection name |
| `description` | longText | no | Nullable |
| `type` | enum | yes | Values `['manual', 'auto']` |
| `sort` | string | no | Nullable, potential values `alpha_asc`, `alpha_desc`, `price_desc`, `price_asc`, `created_desc`, `created_asc` |
| `match_conditions` | enum | no | Nullable, `['all', 'any']` |
| `published_at` | dateTimeTz | no | Default `now()` |
**CollectionRule Model**
| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | autoinc | | auto |
| `rule` | string | yes | current values `product_title`, `product_price`, `compare_at_price`, `inventory_stock`, `product_brand`, `product_category` |
| `operator` | string | yes | current values `equals_to`, `not_equals_to`, `less_than`, `greater_than`, `starts_with`, `ends_with`, `contains`, `not_contains` |
| `value` | string | yes | |
| `collection_id` | bigint | no | Collection ID |
Models are customizable, and we recommend changing the **Collection** model when you configure your store. To change the model you need to look at the configuration file `config/shopper/system.php` at the key `models`.
Let’s keep in mind the modification that was made in the previous section regarding [Categories](https://docs.laravelshopper.dev/categories)
.
return [\
'models' => [\
/*\
* Eloquent model should be used to retrieve your categories. Of course,\
* it is often just the "Category" model but you may use whatever you like.\
*\
* The model you want to use as a Category model needs to extends the\
* `\Shopper\Framework\Models\Shop\Product\Category` model.\
*/\
'category' => \App\Models\Category::class,\
\
/*\
* Eloquent model should be used to retrieve your collections. Of course,\
* it is often just the "Collection" model but you may use whatever you like.\
*\
* The model you want to use as a Collection model needs to extends the\
* `\Shopper\Framework\Models\Shop\Product\Collection` model.\
*/\
'collection' => \Shopper\Framework\Models\Shop\Product\Collection::class,\
]\
];
1. Create your own model that you have to use
php artisan make:model Collection
Once the `app/Models/Collection.php` model is created in our app folder, we will make it extend from the `Shopper\Framework\Models\Shop\Product\Collection` model available in Shopper.
2. Extend our Collection model from the Collection Shopper Model
namespace App\Models;
use Shopper\Framework\Models\Shop\Product;
class Collection extends Product\Collection
{
}
3. Update `Collection` key for the model on the `system.php` config file to use our new model
return [\
'models' => [\
/*\
* Eloquent model should be used to retrieve your categories. Of course,\
* it is often just the "Category" model but you may use whatever you like.\
*\
* The model you want to use as a Category model needs to extends the\
* `\Shopper\Framework\Models\Shop\Product\Category` model.\
*/\
'category' => \App\Models\Category::class,\
\
/*\
* Eloquent model should be used to retrieve your collections. Of course,\
* it is often just the "Collection" model but you may use whatever you like.\
*\
* The model you want to use as a Collection model needs to extends the\
* `\Shopper\Framework\Models\Shop\Product\Collection` model.\
*/\
'collection' => \App\Models\Collection::class,\
]\
];
###
[](https://docs.laravelshopper.dev/v1/collections#components)
Components
Livewire components for managing collections are available in the component configuration file `config/shopper/components.php`.
use Shopper\Framework\Http\Livewire;
return [\
\
'livewire' => [\
\
'collections.browse' => Livewire\Collections\Browse::class,\
'collections.create' => Livewire\Collections\Create::class,\
'collections.edit' => Livewire\Collections\Edit::class,\
'collections.products' => Livewire\Collections\Products::class,\
\
'tables.collections-table' => Livewire\Tables\CollectionsTable::class,\
\
];\
\
];
[](https://docs.laravelshopper.dev/v1/collections#manage-collections)
Manage Collections
--------------------------------------------------------------------------------------------
Form your Shopper admin on the sidebar go to **Collections**. The display page is rendered by the Livewire component `Shopper\Framework\Http\Livewire\Collections\Browse` and for the display of the collections table is the component `Shopper\Framework\Http\Livewire\Tables\CollectionsTable`. By default you will see this page without data which is rendered by a blade component of Shopper called [empty state](https://docs.laravelshopper.dev/extending/empty-state)
.
###
[](https://docs.laravelshopper.dev/v1/collections#create-collection)
Create collection
Click on the “Create” button on the collections page, and a creation form appears.
Save your changes in order to be taken back to the collections list. Required fields are marked with an **asterisk (\*)**. You can create two types of collections as we said: Automatic and manual collection. Only automatic collections have rules for automating them. When you choose to create an automatic collection the rules section will be available in the creation form
After you create a collection, you can’t change its type. The Livewire component for collection creation is `Shopper\Framework\Http\Livewire\Collections\Create`. Here is the function to save a collection
namespace Shopper\Framework\Http\Livewire\Collections;
use Shopper\Framework\Models\Shop\Product\CollectionRule;
use Shopper\Framework\Repositories\Ecommerce\CollectionRepository;
class Create extends Component
{
public function store()
{
$this->validate($this->rules());
$collection = (new CollectionRepository())->create([\
'name' => $this->name,\
'slug' => $this->name,\
'description' => $this->description,\
'type' => $this->type,\
'match_conditions' => $this->condition_match,\
'seo_title' => $this->seoTitle,\
'seo_description' => $this->seoDescription,\
'published_at' => $this->publishedAt ?? now(),\
]);
if ($this->fileUrl) {
$collection->addMedia($this->fileUrl)
->toMediaCollection(config('shopper.system.storage.disks.uploads'));
}
if ($this->type === 'auto' && count($this->conditions) > 0 && $this->rule) {
foreach ($this->rule as $key => $value) {
CollectionRule::query()->create([\
'collection_id' => $collection->id,\
'rule' => $this->rule[$key],\
'operator' => $this->operator[$key],\
'value' => $this->value[$key],\
]);
}
$this->conditions = [];
$this->resetConditionsFields();
}
session()->flash('success', __('Collection successfully added!'));
$this->redirectRoute('shopper.collections.edit', $collection);
}
}
[](https://docs.laravelshopper.dev/v1/collections#retrieve-data)
Retrieve Data
----------------------------------------------------------------------------------
After extending the Shopper Collection model you can use your own model to retrieve data from the database. Here an example code.
use App\Models\Collection;
// To retrieve only manual collections
$collections = Collection::manual()->get();
// To retrieve collection by slug
$collection = Collection::findBySlug('summers-clothes');
To view the image of a collection you can consult the [media documentation](https://docs.laravelshopper.dev/media#retrieving-images)
. And you can display collections in your frontend.
[Categories](https://docs.laravelshopper.dev/v1/categories)
[Customers](https://docs.laravelshopper.dev/v1/customers)
⌘I
---
# Installation - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v1/installation#content-area)
This is documentation for Shopper v1, which is no longer maintained. Please refer to the [v2 docs](https://docs.laravelshopper.dev/v2)
for the latest information.
[](https://docs.laravelshopper.dev/v1/installation#supported-versions-of-laravel)
Supported Versions of Laravel
-------------------------------------------------------------------------------------------------------------------
**Laravel 8 and Laravel 9 are supported.** It feels like this section needs more than one sentence but it really doesn’t. That first one said all that needs saying.
[](https://docs.laravelshopper.dev/v1/installation#install-shopper)
Install Shopper
---------------------------------------------------------------------------------------
Shopper is really easy to install. After creating your new app or in an existing Laravel app (8+). There are 2 steps to follow to install Shopper.
1. Run `php artisan config:clear` to make sure your config isn’t cached.
2. Install `shopper/framework` with Composer.
composer require shopper/framework --with-dependencies
[](https://docs.laravelshopper.dev/v1/installation#write-env-variables)
Write Env Variables
-----------------------------------------------------------------------------------------------
Next make sure to create a new database and add your database credentials to your .env file, you will also want to add your application URL in the `APP_URL` variable
APP_URL=http://laravelshopper.test
DB_HOST=localhost
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret
[](https://docs.laravelshopper.dev/v1/installation#automatic-installation)
Automatic Installation
-----------------------------------------------------------------------------------------------------
After installing Shopper in your project via compose and configuring the database, now we will automatically install in the project.
php artisan shopper:install
This will install shopper, publish vendor files, create shopper and storage symlinks if they don’t exist in the public folder, run migrations and seeders classes. And we’re all good to go!
[](https://docs.laravelshopper.dev/v1/installation#update-existing-files)
Update Existing Files
---------------------------------------------------------------------------------------------------
Extend your current User Model (usually `app/Models/User.php`) using the `Shopper\Framework\Models\User\User as Authenticatable` alias:
// app/Models/User.php
use Shopper\Framework\Models\User\User as Authenticatable;
class User extends Authenticatable
{
// ...
}
[](https://docs.laravelshopper.dev/v1/installation#create-an-admin-user)
Create an Admin user
-------------------------------------------------------------------------------------------------
Now we can create a new superuser and sign into the Dashboard and start creating some content to display on the frontend. Run the following command to create a user with supreme (at the moment of creation) rights:
php artisan shopper:admin
And you will be prompted for the user email, firstname, lastname and password. You can now login to start create products
[](https://docs.laravelshopper.dev/v1/installation#new-shopper-directory)
New Shopper Directory
---------------------------------------------------------------------------------------------------
After Shopper is installed, you’ll have 1 new directory in your project:
* `config/shopper/`
[](https://docs.laravelshopper.dev/v1/installation#publish-vendor-files)
Publish Vendor Files
-------------------------------------------------------------------------------------------------
If you want to publish again Shopper’s vendor files run these commands:
php artisan shopper:publish
To run the project you may use the built-in server: `php artisan serve` After that, run `composer dump-autoload` to finish your installation! If your are using Laravel Valet you can easily access with your project name with `.test` at the end when you navigate on you project.
http://laravelshopper.test/shopper/login
[Requirements](https://docs.laravelshopper.dev/v1/requirements)
[Configuration](https://docs.laravelshopper.dev/v1/configuration)
⌘I
---
# Orders - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v1/orders#content-area)
This is documentation for Shopper v1, which is no longer maintained. Please refer to the [v2 docs](https://docs.laravelshopper.dev/v2)
for the latest information.
[Discounts](https://docs.laravelshopper.dev/v1/discounts)
[Control Panel](https://docs.laravelshopper.dev/v1/extending/control-panel)
⌘I
---
# Media - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v1/media#content-area)
This is documentation for Shopper v1, which is no longer maintained. Please refer to the [v2 docs](https://docs.laravelshopper.dev/v2)
for the latest information.
The Shopper Framework supports assigning images to products, brands, collections and categories. It is an additional layer provided by the framework with the help of the [Spatie Media Library](https://spatie.be/v1/laravel-medialibrary)
We recommend organizing your images in a folder offline and keeping a backup in case you need them in the future or mistakenly alter one and wish to revert to the original. You can look at the [documentation](https://docs.laravelshopper.dev/configuration#update-configurations)
for this purpose
[](https://docs.laravelshopper.dev/v1/media#configuration)
Configuration
----------------------------------------------------------------------------
For uploading images we are using [FilePond](https://pqina.nl/)
and some custom upload component with Livewire.
###
[](https://docs.laravelshopper.dev/v1/media#filepond)
Filepond
This component is used to update media at the product level and variants for products.
Filepond is used in Shopper Framework only to update images, and for that it takes as parameters the images of your model.
{category &&
))}
)
}
[](https://docs.laravelshopper.dev/v2/reference/typescript-types#example-order-details)
Example: Order Details
------------------------------------------------------------------------------------------------------------------
import type { Order, OrderItem } from '@shopperlabs/shopper-types'
import { OrderStatus, PaymentStatus, ShippingStatus } from '@shopperlabs/shopper-types'
function OrderDetails({ order }: { order: Order }) {
const statusColors: Record{category.name}
} {products.map((product) => ({product.name}
{product.description}
{product.type === ProductType.VARIANT && ( {product.variants?.length} variants )} {product.prices?.[0] && ( {product.prices[0].currency_code} {product.prices[0].amount} )}Order #{order.number}
{order.status}
{order.payment_status}
{order.shipping_status}
Items
{order.items?.map((item: OrderItem) => (
{item.name}
x{item.quantity}
{item.unit_price_amount}
))}
{order.shippingAddress && (
Shipping Address
{order.shippingAddress.full_name}
{order.shippingAddress.street_address}
{order.shippingAddress.city}, {order.shippingAddress.state}
{order.shippingAddress.postal_code}
-
@foreach($item->getItems() as $subItem)
@include('sidebar::item', ['item' => $subItem])
@endforeach
) | | **Tax rules** | Tax rates applied at checkout | Managed separately in tax settings | You need to create [carriers](https://docs.laravelshopper.dev/v2/user-guide/store-setup/carriers) and payment methods before you can assign them to a zone. Set those up first, then create your zones. [](https://docs.laravelshopper.dev/v2/user-guide/store-setup/zones#zones-in-orders) Zones in Orders ------------------------------------------------------------------------------------------------------- When viewing orders, you can see which zone applies to each order. This helps you understand which shipping and payment rules were used.  [](https://docs.laravelshopper.dev/v2/user-guide/store-setup/zones#common-zone-setups) Common Zone Setups ------------------------------------------------------------------------------------------------------------- ### [](https://docs.laravelshopper.dev/v2/user-guide/store-setup/zones#single-country-store) Single-Country Store If you only sell domestically, create one zone: | Zone | Countries | Currency | Carriers | | --- | --- | --- | --- | | Domestic | Your country | Your currency | Local carriers | ### [](https://docs.laravelshopper.dev/v2/user-guide/store-setup/zones#multi-region-store) Multi-Region Store For stores selling across regions: | Zone | Countries | Currency | Carriers | | --- | --- | --- | --- | | Domestic | France | EUR | Colissimo, Chronopost | | Europe | Germany, Belgium, Spain, Italy | EUR | DHL, UPS | | North America | United States, Canada | USD | FedEx, UPS | | Africa | Cameroon, Senegal, Ivory Coast | XAF | DHL Express | ### [](https://docs.laravelshopper.dev/v2/user-guide/store-setup/zones#global-store-with-few-zones) Global Store with Few Zones Keep it simple with broad zones: | Zone | Countries | Currency | | --- | --- | --- | | Domestic | Your country | Your currency | | International | All others | USD | [](https://docs.laravelshopper.dev/v2/user-guide/store-setup/zones#best-practices) Best Practices ----------------------------------------------------------------------------------------------------- Start Simple ------------ Begin with a domestic zone and expand to international zones as your business grows. Group by Cost ------------- Countries with similar shipping costs should share a zone to simplify pricing. One Currency per Zone --------------------- Each zone uses one currency. If you sell in EUR and USD, you need separate zones. Test Checkout ------------- After configuring zones, place test orders from different countries to verify everything works. [](https://docs.laravelshopper.dev/v2/user-guide/store-setup/zones#related-pages) Related Pages --------------------------------------------------------------------------------------------------- Carriers -------- Set up shipping carriers and configure delivery options. Currencies ---------- Manage the currencies available in your store. Zones Documentation ------------------- Developer reference for zones, relationships, and configuration. [Currencies](https://docs.laravelshopper.dev/v2/user-guide/store-setup/currencies) [Shipping Carriers](https://docs.laravelshopper.dev/v2/user-guide/store-setup/carriers) ⌘I --- # Cart - TALL Stack E-commerce Framework > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.laravelshopper.dev/v2/cart#content-area) The `shopper/cart` package handles everything between “Add to cart” and “Place order”. It manages cart lines, validates stock, applies discounts, calculates taxes, and converts completed carts into orders. All through a clean, testable API. Every monetary value is stored in **cents** as an unsigned integer. A product priced at $25.00 is stored as `2500`. [](https://docs.laravelshopper.dev/v2/cart#how-it-works) How It Works ------------------------------------------------------------------------- The cart system has five main pieces: 1. **CartManager** handles cart operations: add, update, remove, apply coupons, calculate totals 2. **CartSessionManager** persists the current cart in the session for storefront use 3. **Pipeline system** calculates totals through a configurable chain of pipes (subtotals → discounts → taxes → total) 4. **DiscountValidator** enforces coupon rules: eligibility, usage limits, zones, minimum amounts 5. **CreateOrderFromCartAction** converts a cart into an order within a database transaction [](https://docs.laravelshopper.dev/v2/cart#cart-manager) Cart Manager ------------------------------------------------------------------------- The `CartManager` is the primary API for all cart operations. It is registered as a singleton and injected with the `CartPipelineRunner`. use Shopper\Cart\CartManager; $manager = resolve(CartManager::class); ### [](https://docs.laravelshopper.dev/v2/cart#adding-items) Adding Items Pass any model that implements `Priceable`, typically a `Product` or `ProductVariant`. The manager looks up the unit price from the purchasable’s price list using the cart’s currency. $line = $manager->add($cart, $product); $line = $manager->add($cart, $product, quantity: 3); $line = $manager->add($cart, $variant, metadata: [\ 'gift_wrap' => true,\ 'message' => 'Happy birthday!',\ ]); Adding the same purchasable twice increments the existing line’s quantity instead of creating a duplicate. $manager->add($cart, $product, quantity: 2); // quantity: 2 $manager->add($cart, $product, quantity: 3); // quantity: 5 ### [](https://docs.laravelshopper.dev/v2/cart#stock-validation) Stock Validation Every `add()` and `update()` call checks available stock. If the purchasable implements `Stockable` and `allow_backorder` is false, an `InsufficientStockException` is thrown when the requested quantity exceeds available inventory. use Shopper\Cart\Exceptions\InsufficientStockException; try { $manager->add($cart, $product, quantity: 100); } catch (InsufficientStockException $e) { $e->purchasable; // The product or variant $e->available; // Current stock level $e->requested; // Quantity that was requested } Products with `allow_backorder` set to `true` bypass stock checks entirely. ### [](https://docs.laravelshopper.dev/v2/cart#updating-a-line) Updating a Line $updated = $manager->update($cart, $lineId, [\ 'quantity' => 5,\ ]); $updated = $manager->update($cart, $lineId, [\ 'metadata' => ['gift_wrap' => false],\ ]); ### [](https://docs.laravelshopper.dev/v2/cart#removing-lines) Removing Lines $manager->remove($cart, $lineId); $manager->clear($cart); ### [](https://docs.laravelshopper.dev/v2/cart#applying-coupons) Applying Coupons The `applyCoupon()` method validates that the discount code exists in the database before setting it on the cart. The actual discount calculation happens during the pipeline. use Shopper\Cart\Exceptions\InvalidDiscountException; try { $manager->applyCoupon($cart, 'SUMMER20'); } catch (InvalidDiscountException $e) { // Discount code not found } $manager->removeCoupon($cart); Removing a coupon also deletes all line adjustments that were created by the discount pipeline. ### [](https://docs.laravelshopper.dev/v2/cart#adding-addresses) Adding Addresses use Shopper\Core\Enum\AddressType; $manager->addAddress($cart, AddressType::Shipping, [\ 'first_name' => 'John',\ 'last_name' => 'Doe',\ 'address_1' => '123 Main St',\ 'city' => 'New York',\ 'postal_code' => '10001',\ 'country_id' => $countryId,\ ]); $manager->addAddress($cart, AddressType::Billing, $billingData); If an address of the same type already exists, it is updated instead of duplicated. ### [](https://docs.laravelshopper.dev/v2/cart#calculating-totals) Calculating Totals use Shopper\Cart\Pipelines\CartPipelineContext; $context = $manager->calculate($cart); $context->subtotal; // Sum of line subtotals (before discounts/tax) $context->discountTotal; // Total discount amount $context->taxTotal; // Total tax amount $context->total; // Final total $context->taxInclusive; // Whether tax is included in prices ### [](https://docs.laravelshopper.dev/v2/cart#completed-cart-guard) Completed Cart Guard All mutating operations (`add`, `update`, `remove`, `clear`, `applyCoupon`, `removeCoupon`) throw `CartCompletedException` if the cart has already been completed. This prevents modifications after an order has been placed. use Shopper\Cart\Exceptions\CartCompletedException; $cart->update(['completed_at' => now()]); $manager->add($cart, $product); // throws CartCompletedException [](https://docs.laravelshopper.dev/v2/cart#session-management) Session Management ------------------------------------------------------------------------------------- The `CartSessionManager` handles cart persistence in the HTTP session. Use it in your storefront to retrieve or create the current customer’s cart. ### [](https://docs.laravelshopper.dev/v2/cart#using-the-facade) Using the Facade use Shopper\Cart\Facades\Cart; $cart = Cart::current(); $cart = Cart::create(); $cart = Cart::create(['channel_id' => $channelId, 'zone_id' => $zoneId]); Cart::use($existingCart); Cart::associate($user); Cart::forget(); ### [](https://docs.laravelshopper.dev/v2/cart#behavior) Behavior * `current()` returns `null` if no cart exists in the session and `auto_create` is `false` * `current()` returns `null` if the session cart has been completed (it won’t return stale carts) * `create()` stores the new cart’s ID in the session and sets the `currency_code` from `shopper_currency()` * `associate()` sets the `customer_id` on the current cart. Call this after login * `forget()` removes the cart ID from the session without deleting the cart itself [](https://docs.laravelshopper.dev/v2/cart#models) Models ------------------------------------------------------------- ### [](https://docs.laravelshopper.dev/v2/cart#cart) Cart Shopper\Cart\Models\Cart | Column | Type | Nullable | Description | | --- | --- | --- | --- | | `id` | bigint | | Primary key | | `customer_id` | bigint | Yes | FK to `users` | | `channel_id` | bigint | Yes | FK to `shopper_channels` | | `zone_id` | bigint | Yes | FK to `shopper_zones` | | `currency_code` | string | | ISO currency code (e.g. `USD`) | | `coupon_code` | string | Yes | Applied discount code | | `completed_at` | timestamp | Yes | Set when cart is converted to order | | `metadata` | json | Yes | Custom data | | `created_at` | timestamp | | | | `updated_at` | timestamp | | | #### [](https://docs.laravelshopper.dev/v2/cart#relationships) Relationships $cart->lines; // HasMany
@if ($items->isEmpty())
@endif
###
[](https://docs.laravelshopper.dev/v2/cart#cart-header-button)
Cart Header Button
A small component that displays the cart item count in the navigation. It listens for the `cartUpdated` event to refresh automatically:
namespace App\Livewire;
use Illuminate\Contracts\View\View;
use Livewire\Attributes\On;
use Livewire\Component;
use Shopper\Cart\CartSessionManager;
final class ShoppingCartButton extends Component
{
public int $count = 0;
public function mount(): void
{
$this->updateCount();
}
#[On('cartUpdated')]
public function updateCount(): void
{
$cart = resolve(CartSessionManager::class)->current();
$this->count = $cart ? $cart->lines->sum('quantity') : 0;
}
public function render(): View
{
return view('livewire.shopping-cart-button');
}
}
###
[](https://docs.laravelshopper.dev/v2/cart#displaying-cart-totals)
Displaying Cart Totals
Use the `CartManager::calculate()` method to get the full breakdown. The returned `CartPipelineContext` contains all computed values:
$context = resolve(CartManager::class)->calculate($cart);
Your cart is empty.
@else-
@foreach ($items as $line)
-
@if ($line->purchasable instanceof \App\Models\ProductVariant) {{ $line->purchasable->product->name }} - {{ $line->purchasable->name }} @else {{ $line->purchasable->name }} @endif
Qty: {{ $line->quantity }} · {{ shopper_money_format($line->unit_price_amount, cartSession()->currency_code) }}
@endforeach
Subtotal: {{ shopper_money_format($subtotal, cartSession()->currency_code) }}
Subtotal: {{ shopper_money_format($context->subtotal, $cart->currency_code) }}
@if ($context->discountTotal > 0)Discount: -{{ shopper_money_format($context->discountTotal, $cart->currency_code) }}
@endif @if ($context->taxTotal > 0)Tax: {{ shopper_money_format($context->taxTotal, $cart->currency_code) }}
@endifTotal: {{ shopper_money_format($context->total, $cart->currency_code) }}
About Us
; } ### [](https://docs.laravelshopper.dev/v2/react-starter-kit#models-2) Models Add methods, scopes, or relationships directly to the model files in `app/Models/`. These models extend Shopper’s base models, so all existing functionality is preserved. use Illuminate\Database\Eloquent\Builder; class Product extends Shopper\Models\Product { public function scopeFeatured(Builder $query): Builder { return $query->where('is_featured', true); } } [Livewire](https://docs.laravelshopper.dev/v2/livewire-starter-kit) [Vue](https://docs.laravelshopper.dev/v2/vue-starter-kit) ⌘I --- # Upgrade Guide - TALL Stack E-commerce Framework > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.laravelshopper.dev/v2/upgrade#content-area) Shopper documentation always reflects the latest release of the current major version. When a new minor version ships, the docs are updated to match. Upgrade guides document every breaking change, new feature, and migration step between versions. [](https://docs.laravelshopper.dev/v2/upgrade#before-you-start) Before You Start ------------------------------------------------------------------------------------ Before upgrading, take these precautions: 1. **Back up your database.** E-commerce data (orders, customers, prices) is difficult to recover if a migration fails. 2. **Run the upgrade on a staging environment first.** Verify everything works before touching production. 3. **If upgrading across multiple versions** (e.g., v2.2 to v2.5), follow each guide in sequence. Do not skip versions. [](https://docs.laravelshopper.dev/v2/upgrade#upgrade-guides) Upgrade Guides -------------------------------------------------------------------------------- | From | To | Summary | | --- | --- | --- | | [v2.9](https://docs.laravelshopper.dev/v2/upgrade/v2-9-to-v2-10) | v2.10 | Security release: admin authorization audit, slide-over IDOR fix, exact tax on discounted totals (`TaxableItem` contract change), atomic stock reservation (`StockReserver` contract, `Stockable::tracksInventory()`), guest per-user discount block. No database migrations | | [v2.8](https://docs.laravelshopper.dev/v2/upgrade/v2-8-to-v2-9) | v2.9 | Laravel 13 support, onboarding wizard rebuilt on Filament Schema, cache stores scalars instead of models, Stripe SDK upgraded to v19. No database migrations | | [v2.7](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8) | v2.8 | Security release: authorization guards across admin Livewire components, atomic discount reservation, `orders` discount snapshot columns | | [v2.6](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7) | v2.7 | Money values stored in smallest currency unit (cents), slide-over components replaced, 2FA split into SOLID interfaces | | [v2.5](https://docs.laravelshopper.dev/v2/upgrade/v2-5-to-v2-6) | v2.6 | Cart package, tax system, auth models moved to admin package, event renaming, render hooks | | [v2.4](https://docs.laravelshopper.dev/v2/upgrade/v2-4-to-v2-5) | v2.5 | Order system split into three independent statuses (order, payment, shipping), payment drivers, shipment tracking | | [v2.2](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3) | v2.3 | Product Tags feature with new permissions and feature flag | | [v2.1](https://docs.laravelshopper.dev/v2/upgrade/v2-1-to-v2-2) | v2.2 | Repository pattern removed, Model Contracts system, Filament v4, ShopperUser trait, sidebar redesign | There is no upgrade guide for v2.3 to v2.4. That release only added Spanish translations and internal render hooks with no breaking changes. [](https://docs.laravelshopper.dev/v2/upgrade#getting-help) Getting Help ---------------------------------------------------------------------------- If you encounter issues during an upgrade: * Check the [GitHub Issues](https://github.com/shopperlabs/shopper/issues) * Join the [Discord community](https://discord.gg/CC444Gy7) * Review the [changelog](https://github.com/shopperlabs/shopper/releases) [Vue](https://docs.laravelshopper.dev/v2/vue-starter-kit) [From v2.9 to v2.10](https://docs.laravelshopper.dev/v2/upgrade/v2-9-to-v2-10) ⌘I --- # From v2.2 to v2.3 - TALL Stack E-commerce Framework > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#content-area) **Estimated Upgrade Time:** 5-10 minutes for most applications. [](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#updating-dependencies) Updating Dependencies ----------------------------------------------------------------------------------------------------------- Update your `composer.json` file to require Shopper 2.3: "require": { "shopper/framework": "^2.3" } Then run: composer update -W After updating Composer dependencies, run the migrations: php artisan migrate * * * [](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#new-features) New Features ----------------------------------------------------------------------------------------- ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#product-tags) Product Tags Shopper 2.3 introduces **Product Tags**, simple flat labels you can attach to products for cross-cutting organization. Unlike categories (hierarchical) or collections (rule-based), tags are flexible and ideal for seasonal labels, marketing campaigns, or storefront filtering. See the [Product Tags documentation](https://docs.laravelshopper.dev/v2/product-tags) for full details. #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#new-permissions) New Permissions New permissions have been added for **tags**. For existing installations, create them and assign to your admin role: use Shopper\Core\Models\Permission; use Spatie\Permission\Models\Role; Permission::generate('tags', 'products'); $admin = Role::findByName('administrator'); $admin->givePermissionTo([\ 'browse_tags',\ 'read_tags',\ 'edit_tags',\ 'add_tags',\ 'delete_tags',\ ]); If you don’t create these permissions, users will not be able to access the Tags page or manage tags from the product form. #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#new-feature-flag) New Feature Flag A new `tag` feature flag has been added to `config/shopper/features.php`. If you have a published config file, add: use Shopper\Enum\FeatureState; return [\ // ... existing features\ 'tag' => FeatureState::Enabled,\ ]; Set to `FeatureState::Disabled` if you don’t need tags in your store. #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#published-components) Published Components If you have published product components via `php artisan shopper:component:publish product`, add the new tag page to your `config/shopper/components/product.php`: 'pages' => [\ // ... existing pages\ 'tag-index' => \Shopper\Livewire\Pages\Tag\Index::class,\ ], * * * [](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#migration-checklist) Migration Checklist ------------------------------------------------------------------------------------------------------- 1 [](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#) Update dependencies Update `shopper/framework` to `^2.3` in `composer.json`, then run `composer update -W`. 2 [](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#) Run migrations Run `php artisan migrate` to create the `product_tags` table. 3 [](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#) Create new permissions Run `Permission::generate('tags', 'products')` and assign the five generated permissions (`browse_tags`, `read_tags`, `edit_tags`, `add_tags`, `delete_tags`) to the `administrator` role. 4 [](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#) Update published config files If you have published `config/shopper/features.php`, add the `tag` feature flag. If you have published `config/shopper/components/product.php`, add the `tag-index` component entry. 5 [](https://docs.laravelshopper.dev/v2/upgrade/v2-2-to-v2-3#) Clear caches Run `php artisan optimize:clear`. [From v2.4 to v2.5](https://docs.laravelshopper.dev/v2/upgrade/v2-4-to-v2-5) [From v2.1 to v2.2](https://docs.laravelshopper.dev/v2/upgrade/v2-1-to-v2-2) ⌘I --- # From v2.7 to v2.8 - TALL Stack E-commerce Framework > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#content-area) **Estimated Upgrade Time:** 5 to 15 minutes. v2.8 is a pure security release with no breaking API changes. v2.8.0 patches two security advisories disclosed responsibly by [@baradika](https://github.com/baradika) : * Authorization bypass in admin Livewire components (CWE-862 / CWE-285) * Race condition on `Discount.usage_limit` allows silent over-redemption (CWE-362 / CWE-840) Upgrade as soon as possible. Both advisories are public on the [Shopper GitHub Security Advisories](https://github.com/shopperlabs/shopper/security/advisories) page. [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#updating-dependencies) Updating Dependencies ----------------------------------------------------------------------------------------------------------- Update the following dependency in your application’s `composer.json` file: `shopper/framework` to `^2.8` Then run: composer update -W php artisan migrate [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#database-migration) Database Migration ----------------------------------------------------------------------------------------------------- v2.8 ships one additive migration. It adds five nullable columns to the `orders` table to snapshot the discount that was redeemed at order placement time: | Column | Type | Purpose | | --- | --- | --- | | `discount_id` | bigint FK (nullOnDelete) | Link to the discount that was redeemed | | `discount_code` | string | Snapshot of the code used (kept even if the discount is later edited or deleted) | | `discount_type` | string(32) | Snapshot of the discount type (`percentage` / `fixed_amount`) | | `discount_value_at_apply` | unsigned int | Snapshot of the discount value at apply time | | `discount_currency_code` | char(3) | Currency the discount was applied in | Existing rows are left untouched. The snapshot follows the Shopify pattern: an order keeps the discount it was placed with, even after the originating discount is edited or deleted. [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#high-impact-changes) High Impact Changes ------------------------------------------------------------------------------------------------------- ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#discount-limit-enforcement) Discount Limit Enforcement **Likelihood of Impact: High if you call `CreateOrderFromCartAction` directly.** _Affects any storefront code that converts carts to orders outside the default checkout flow._ Two production bugs around `Discount.usage_limit` are fixed in v2.8. Both can now throw a new exception from `CreateOrderFromCartAction::execute()`. The global usage counter (`total_use`) is now incremented atomically inside the order-creation transaction. The discount row is locked with `lockForUpdate`, then a conditional `UPDATE` increments `total_use` **only if** it is still below `usage_limit`. If zero rows are affected, the limit was reached between cart validation and commit and `DiscountLimitReachedException::global()` is thrown. The order is **not** created and the transaction rolls back. The per-user limit (`usage_limit_per_user`) previously read from `DiscountDetail.total_use`, a counter that was never incremented. It now counts prior orders on the new `orders.discount_id` column. The check runs in two places: `DiscountValidator` rejects the code at cart-apply time (so the customer is not surprised at checkout), and `CreateOrderFromCartAction` re-checks at commit and throws `DiscountLimitReachedException::perUser()` if the customer redeemed it between cart apply and commit. Update your checkout controller to catch the new exception: use Shopper\Cart\Actions\CreateOrderFromCartAction; use Shopper\Cart\Exceptions\DiscountLimitReachedException; use Shopper\Cart\Facades\Cart; try { $order = resolve(CreateOrderFromCartAction::class)->execute(Cart::current()); } catch (DiscountLimitReachedException $e) { return back()->with('error', 'This discount can no longer be used. Please remove the code and try again.'); } For full details on both limits, see the [Discounts page](https://docs.laravelshopper.dev/v2/discounts#usage-limit-enforcement) . [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#medium-impact-changes) Medium Impact Changes ----------------------------------------------------------------------------------------------------------- ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#custom-livewire-admin-components) Custom Livewire Admin Components **Likelihood of Impact: Medium** _Affects applications with custom Livewire components extending Shopper’s admin surfaces._ v2.8 tightens authorization across every Shopper admin Livewire component. If you have custom components that extend or mimic Shopper’s order, product, customer, or settings surfaces, audit them against the new patterns. Skipping this audit leaves the same bypass surface that v2.8 closed in Shopper itself. #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#chain-authorize-on-filament-actions) Chain `authorize()` on Filament actions Filament `Action` handlers should declare their ability on the action itself, not inside the closure. This hides the button when the user lacks the ability, instead of throwing a 403 on click: Action::make('cancel') ->action(function () { $this->authorize('edit_orders'); // ... }); Action::make('cancel') ->authorize('edit_orders') ->action(function () { // ... }); #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#authorize-livewire-methods-on-the-first-line) Authorize Livewire methods on the first line Every public method that mutates state must call `$this->authorize()` first: public function leaveNotes(): void { $this->authorize('edit_orders'); // ... } #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#lock-public-eloquent-properties) Lock public Eloquent properties Any `public Model $x` property on a Livewire component must be marked `#[Locked]` so it cannot be rebound from the browser. This is the pattern Shopper now applies to `Order`, `OrderShipping`, `Discount`, `Review`, `ShopperUser`, `Role`, `Inventory`, `Legal`, and `Product`: use Livewire\Attributes\Locked; use Shopper\Models\Order; #[Locked] public Order $order; #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#allow-list-input-on-store-methods) Allow-list input on `store()` methods When persisting user input from the browser, use an explicit `Arr::only(...)` allow-list instead of `Arr::except(...)`. The latter is what allowed the `_password` hidden-field leak that v2.8 closed in `Customers/Create::store()`: $data = Arr::except($payload, ['_token']); $data = Arr::only($payload, ['first_name', 'last_name', 'email']); ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#settings-permissions-tightened) Settings Permissions Tightened **Likelihood of Impact: Medium** _Affects custom roles that previously relied on the loose permission scope._ Five settings surfaces moved from `view_users` to `access_setting`. If you have custom roles, audit them to make sure the right people retain access: | Surface | Before | After | | --- | --- | --- | | `Settings/Team/Index::createRole` | `view_users` | `access_setting` | | `Settings/Team/Index` DeleteAction | `view_users` | `access_setting` | | `Settings/Team/RolePermission` save/generate/create | `view_users` | `access_setting` | | `PaymentMethods` / `Currencies` / `Carriers` `ToggleColumn`, record actions, bulk actions | `view_users` | `access_setting` | | `Settings/Team/Permissions::togglePermission` / `removePermission` | `view_users` | `access_setting` (and guards against null lookups) | Roles that managed payment methods, currencies, carriers, team, or permissions must now have `access_setting` granted. [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#low-impact-changes) Low Impact Changes ----------------------------------------------------------------------------------------------------- ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#product-barcode-validation) Product Barcode Validation Product barcodes are now validated against `^[A-Za-z0-9\-]*$` server-side. This closes a stored XSS surface on the admin barcode renderer. If you have existing products with non-alphanumeric barcodes, they will fail re-validation on next save, so clean them up before upgrading. ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#discount-snapshot-on-orders) Discount Snapshot on Orders Orders now snapshot the discount at placement time. If you have storefront pages or admin extensions that read the discount tied to an order, prefer the new snapshot columns over `Order::discount` for historical accuracy. The relationship is still there but will return `null` if the originating discount has been deleted. $order->discount_code; $order->discount_type; $order->discount_value_at_apply; $order->discount_currency_code; [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#migration-checklist) Migration Checklist ------------------------------------------------------------------------------------------------------- 1 [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#) Update composer Set `shopper/framework` to `^2.8` and run `composer update -W`. 2 [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#) Run the migration Run `php artisan migrate` to add the five `orders.discount_*` columns. 3 [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#) Catch DiscountLimitReachedException Wrap `CreateOrderFromCartAction::execute()` calls in your checkout controller to surface a friendly message to the customer when a discount limit is hit at commit time. 4 [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#) Audit custom Livewire components For every custom Livewire admin component, chain `->authorize()` on Filament actions, call `$this->authorize()` on Livewire method handlers, and mark `public Model $x` properties with `#[Locked]`. 5 [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#) Audit custom roles Grant `access_setting` to roles that need to manage payment methods, currencies, carriers, team members, or permissions. 6 [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#) Sanitize existing barcodes Find products with non-alphanumeric barcodes and clean them up before saving. 7 [](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8#) Run tests Run `php artisan test`. The new authorization guards may reveal tests that were using under-privileged users. [From v2.8 to v2.9](https://docs.laravelshopper.dev/v2/upgrade/v2-8-to-v2-9) [From v2.6 to v2.7](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7) ⌘I --- # Reviews - TALL Stack E-commerce Framework > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.laravelshopper.dev/v2/reviews#content-area) Reviews allow customers to rate and review products. Shopper provides a flexible review system with approval workflows, rating calculations, and polymorphic relationships. [](https://docs.laravelshopper.dev/v2/reviews#model) Model -------------------------------------------------------------- The model used is `Shopper\Core\Models\Review`. It implements `Shopper\Core\Models\Contracts\Review`. Unlike products or brands, the Review model is not configurable via `config/shopper/models.php` and has no admin model wrapper. Products gain review capabilities through the `InteractsWithReviews` trait, which implements the `Shopper\Core\Contracts\HasReviews` interface. This is already applied to the Product model. [](https://docs.laravelshopper.dev/v2/reviews#database-schema) Database Schema ---------------------------------------------------------------------------------- | Column | Type | Nullable | Default | Description | | --- | --- | --- | --- | --- | | `id` | bigint | no | auto | Primary key | | `rating` | integer | no | \- | Rating value (typically 1-5) | | `title` | text | yes | null | Review title | | `content` | text | yes | null | Review content | | `is_recommended` | boolean | no | false | Customer recommends product | | `approved` | boolean | no | false | Review approval status | | `reviewrateable_id` | bigint | no | \- | Polymorphic relation ID (product) | | `reviewrateable_type` | string | no | \- | Polymorphic relation type | | `author_id` | bigint | no | \- | Polymorphic relation ID (user) | | `author_type` | string | no | \- | Polymorphic relation type | | `created_at` | timestamp | yes | null | Creation timestamp | | `updated_at` | timestamp | yes | null | Last update timestamp | [](https://docs.laravelshopper.dev/v2/reviews#relationships) Relationships ------------------------------------------------------------------------------ ### [](https://docs.laravelshopper.dev/v2/reviews#reviewrateable-product) Reviewrateable (Product) // Get the reviewed entity (usually a product) $review->reviewrateable; // Product model ### [](https://docs.laravelshopper.dev/v2/reviews#author-user) Author (User) // Get the review author $review->author; // User model [](https://docs.laravelshopper.dev/v2/reviews#hasreviews-contract) HasReviews Contract ------------------------------------------------------------------------------------------ Products implement the `HasReviews` contract via the `InteractsWithReviews` trait: use Shopper\Core\Contracts\HasReviews; use Shopper\Core\Models\Traits\InteractsWithReviews; class Product extends Model implements HasReviews { use InteractsWithReviews; } [](https://docs.laravelshopper.dev/v2/reviews#rating-methods) Rating Methods -------------------------------------------------------------------------------- ### [](https://docs.laravelshopper.dev/v2/reviews#getting-ratings) Getting Ratings // Get all ratings for a product $product->ratings; // Collection of Review models // Get all ratings with sorting $product->getAllRatings($product->id, 'desc'); // Get only approved ratings $product->getApprovedRatings($product->id); // Get pending (not approved) ratings $product->getNotApprovedRatings($product->id); // Get recent ratings $product->getRecentRatings($product->id, 5); // Get recent ratings by user $product->getRecentUserRatings($userId, 5, approved: true); ### [](https://docs.laravelshopper.dev/v2/reviews#rating-counts) Rating Counts // Count all ratings $product->countRating(); // Returns integer // Get rating sum $product->sumRating(); // Collection with sum ### [](https://docs.laravelshopper.dev/v2/reviews#average-ratings) Average Ratings // Get average rating $product->averageRating(); // Collection with average // Get average rating rounded to 1 decimal $product->averageRating(round: 1); // e.g., 4.5 // Get average rating of approved reviews only $product->averageRating(round: 1, onlyApproved: true); ### [](https://docs.laravelshopper.dev/v2/reviews#rating-percentage) Rating Percentage // Get percentage of 5-star ratings $product->ratingPercent(5); // e.g., 85.5 // Useful for displaying rating distribution $distribution = [\ 5 => $product->ratingPercent(5),\ 4 => $product->ratingPercent(4),\ 3 => $product->ratingPercent(3),\ 2 => $product->ratingPercent(2),\ 1 => $product->ratingPercent(1),\ ]; [](https://docs.laravelshopper.dev/v2/reviews#creating-reviews) Creating Reviews ------------------------------------------------------------------------------------ ### [](https://docs.laravelshopper.dev/v2/reviews#via-product-model) Via Product Model use Shopper\Models\Product; $product = Product::query()->find($id); // Create a review $review = $product->rating([\ 'rating' => 5,\ 'title' => 'Excellent product!',\ 'content' => 'This product exceeded my expectations.',\ 'is_recommended' => true,\ 'approved' => false, // Pending approval\ ], $user); ### [](https://docs.laravelshopper.dev/v2/reviews#via-review-model) Via Review Model use Shopper\Core\Models\Review; $review = new Review; $review = $review->createRating($product, [\ 'rating' => 4,\ 'title' => 'Good quality',\ 'content' => 'Happy with my purchase.',\ 'is_recommended' => true,\ ], $user); ### [](https://docs.laravelshopper.dev/v2/reviews#direct-creation) Direct Creation $review = Review::query()->create([\ 'rating' => 5,\ 'title' => 'Love it!',\ 'content' => 'Best purchase I made.',\ 'is_recommended' => true,\ 'approved' => false,\ 'reviewrateable_id' => $product->id,\ 'reviewrateable_type' => get_class($product),\ 'author_id' => $user->id,\ 'author_type' => get_class($user),\ ]); [](https://docs.laravelshopper.dev/v2/reviews#updating-reviews) Updating Reviews ------------------------------------------------------------------------------------ // Via product model $product->updateRating($reviewId, [\ 'rating' => 4,\ 'content' => 'Updated review content.',\ ]); // Via review model $review = new Review; $review->updateRating($reviewId, [\ 'title' => 'Updated title',\ 'content' => 'Updated content',\ ]); [](https://docs.laravelshopper.dev/v2/reviews#approval-management) Approval Management ------------------------------------------------------------------------------------------ // Approve a review $review->updatedApproved(true); // Unapprove a review $review->updatedApproved(false); // Direct update $review->update(['approved' => true]); [](https://docs.laravelshopper.dev/v2/reviews#deleting-reviews) Deleting Reviews ------------------------------------------------------------------------------------ // Via product model $product->deleteRating($reviewId); // Via review model $review = new Review; $review->deleteRating($reviewId); // Direct delete Review::query()->find($reviewId)->delete(); [](https://docs.laravelshopper.dev/v2/reviews#retrieving-reviews) Retrieving Reviews ---------------------------------------------------------------------------------------- use Shopper\Core\Models\Review; // Get all reviews $reviews = Review::query() ->with(['author', 'reviewrateable']) ->latest() ->get(); // Get pending reviews $pending = Review::query() ->where('approved', false) ->with('author') ->get(); // Get approved reviews for a product $productReviews = Review::query() ->where('reviewrateable_id', $productId) ->where('reviewrateable_type', Product::class) ->where('approved', true) ->with('author') ->latest() ->paginate(10); // Get reviews by user $userReviews = Review::query() ->where('author_id', $userId) ->where('author_type', User::class) ->with('reviewrateable') ->get(); [](https://docs.laravelshopper.dev/v2/reviews#configuration) Configuration ------------------------------------------------------------------------------ ### [](https://docs.laravelshopper.dev/v2/reviews#disabling-reviews) Disabling Reviews If your store doesn’t need product reviews, disable the feature in `config/shopper/features.php`: use Shopper\Enum\FeatureState; return [\ 'review' => FeatureState::Disabled,\ ]; ### [](https://docs.laravelshopper.dev/v2/reviews#permissions) Permissions The admin panel generates five permissions for review management: | Permission | Description | | --- | --- | | `browse_reviews` | View the reviews list | | `read_reviews` | View a single review | | `add_reviews` | Create new reviews | | `edit_reviews` | Edit existing reviews | | `delete_reviews` | Delete reviews | [](https://docs.laravelshopper.dev/v2/reviews#components) Components ------------------------------------------------------------------------ To customize the admin UI for review management: php artisan shopper:component:publish review Creates `config/shopper/components/review.php`: use Shopper\Livewire; return [\ 'pages' => [\ 'review-index' => Livewire\Pages\Reviews\Index::class,\ ],\ 'components' => [\ 'slide-overs.review-detail' => Livewire\SlideOvers\ReviewDetail::class,\ ],\ ]; [](https://docs.laravelshopper.dev/v2/reviews#storefront-example) Storefront Example ---------------------------------------------------------------------------------------- ### [](https://docs.laravelshopper.dev/v2/reviews#review-display) Review Display namespace App\Http\Controllers; use Shopper\Models\Product; class ProductController extends Controller { public function show(string $slug) { $product = Product::findBySlug($slug); // Get approved reviews $reviews = $product->ratings() ->where('approved', true) ->with('author') ->latest() ->paginate(10); // Get rating stats $averageRating = $product->averageRating(1, onlyApproved: true)->first(); $reviewCount = $product->ratings()->where('approved', true)->count(); // Rating distribution $distribution = []; for ($i = 5; $i >= 1; $i--) { $count = $product->ratings() ->where('approved', true) ->where('rating', $i) ->count(); $distribution[$i] = [\ 'count' => $count,\ 'percentage' => $reviewCount > 0 ? ($count / $reviewCount) * 100 : 0,\ ]; } return view('products.show', compact( 'product', 'reviews', 'averageRating', 'reviewCount', 'distribution' )); } } ### [](https://docs.laravelshopper.dev/v2/reviews#review-submission) Review Submission namespace App\Http\Controllers; use Shopper\Models\Product; class ReviewController extends Controller { public function store(Request $request, Product $product) { $validated = $request->validate([\ 'rating' => 'required|integer|min:1|max:5',\ 'title' => 'nullable|string|max:255',\ 'content' => 'nullable|string|max:2000',\ 'is_recommended' => 'boolean',\ ]); // Check if user already reviewed this product $existingReview = $product->ratings() ->where('author_id', auth()->id()) ->where('author_type', get_class(auth()->user())) ->exists(); if ($existingReview) { return back()->with('error', 'You have already reviewed this product.'); } // Create review (pending approval) $product->rating([\ ...$validated,\ 'approved' => false,\ ], auth()->user()); return back()->with('success', 'Thank you! Your review is pending approval.'); } } ### [](https://docs.laravelshopper.dev/v2/reviews#review-management-admin) Review Management (Admin) namespace App\Http\Controllers\Admin; use Shopper\Core\Models\Review; class ReviewController extends Controller { public function index() { $reviews = Review::query() ->with(['author', 'reviewrateable']) ->latest() ->paginate(20); return view('admin.reviews.index', compact('reviews')); } public function approve(Review $review) { $review->updatedApproved(true); return back()->with('success', 'Review approved.'); } public function reject(Review $review) { $review->delete(); return back()->with('success', 'Review deleted.'); } } [](https://docs.laravelshopper.dev/v2/reviews#blade-template-example) Blade Template Example ------------------------------------------------------------------------------------------------ {{-- Product rating summary --}} {{-- Rating distribution --}}
@foreach ($distribution as $rating => $data)
{{-- Reviews list --}}
@foreach ($reviews as $review)
{{ $rating }} stars
{{ $data['count'] }}
@endforeach
{{ $review->created_at->diffForHumans() }}
@if ($review->title)
{{ $review->title }}
@endif{{ $review->content }}
@if ($review->is_recommended) ✓ Recommends this product @endifAbout Us
### [](https://docs.laravelshopper.dev/v2/vue-starter-kit#models-2) Models Add methods, scopes, or relationships directly to the model files in `app/Models/`. These models extend Shopper’s base models, so all existing functionality is preserved. use Illuminate\Database\Eloquent\Builder; class Product extends Shopper\Models\Product { public function scopeFeatured(Builder $query): Builder { return $query->where('is_featured', true); } } [React](https://docs.laravelshopper.dev/v2/react-starter-kit) [Upgrade Guide](https://docs.laravelshopper.dev/v2/upgrade) ⌘I --- # From v2.6 to v2.7 - TALL Stack E-commerce Framework > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#content-area) **Estimated Upgrade Time:** 30 to 90 minutes depending on how much storefront code interacts with monetary values.v2.7 ships with an AI-assisted upgrade package. Install it before upgrading to get guided migration prompts. [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#ai-assisted-upgrade-recommended) AI-Assisted Upgrade (Recommended) --------------------------------------------------------------------------------------------------------------------------------- Shopper v2.7 includes `shopper/upgrade`, a temporary package with [Laravel Boost](https://github.com/laravel/boost) skills that guide your AI assistant through each breaking change. composer require shopper/upgrade:^2.7 --dev php artisan boost:install This registers 4 upgrade skills in your AI assistant: | Skill | What it does | | --- | --- | | `shopper-upgrade-money-storage` | Migrates storefront code to smallest currency unit | | `shopper-upgrade-slide-overs` | Migrates custom slide-over components | | `shopper-upgrade-two-factor-auth` | Migrates 2FA traits to SOLID interfaces | | `shopper-upgrade-filament-schemas` | Migrates InteractsWithForms to InteractsWithSchemas | Each skill checks if the migration applies to your project before suggesting changes. After completing the upgrade, remove the package: composer remove shopper/upgrade --dev [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#updating-dependencies) Updating Dependencies ----------------------------------------------------------------------------------------------------------- Update the following dependencies in your application’s `composer.json` file: `shopper/framework` to `^2.7` `shopper/stripe` to `^2.7` (If installed) Then run: composer update -W v2.7 requires **Laravel 11.28+** or **Laravel 12.x**. If you are on an earlier Laravel 11 version, update Laravel first. Filament minimum version is now **4.9**. * * * [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#high-impact-changes) High Impact Changes ------------------------------------------------------------------------------------------------------- ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#money-storage-smallest-currency-unit) Money Storage: Smallest Currency Unit **Likelihood of Impact: High** _Affects all applications that read or write monetary values (prices, orders, cart totals, payment gateway calls)._ This is the most critical change in v2.7. All monetary values are now stored and returned in the **smallest currency unit** (cents for USD/EUR/GBP, raw value for zero-decimal currencies like XAF/JPY). This follows the Stripe/Shopify standard. **What changed:** All Eloquent price accessors (get/set) have been removed from `Order`, `OrderItem`, `Price`, `CarrierOption`, `CartLine`, `CartLineTaxLine`, `CartLineAdjustment`, and `Discount`. #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#reading-prices) Reading prices Model properties now return the raw database value (smallest unit) instead of human-readable values: $order->price_amount; $price->amount; These return `1200` and `16300` respectively, not `12.00` and `163.00`. For display, use `shopper_money_format()`: shopper_money_format($order->price_amount, $order->currency_code); #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#writing-prices) Writing prices Pass the value in cents directly. The setter no longer multiplies by 100: Order::create(['price_amount' => 12.00]); Order::create(['price_amount' => 1200]); Price::create(['amount' => 163]); Price::create(['amount' => 16300]); #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#cart-pipeline) Cart pipeline `CartPipelineRunner` no longer divides results by 100. All values are in cents: $context = $cartManager->calculate($cart); $context->subtotal; // 25.00 $context->subtotal; // 2500 #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#payment-gateways) Payment gateways Values are already in cents. Remove any manual multiplication: Stripe::charge($order->price_amount * 100); Stripe::charge($order->price_amount); #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#zero-decimal-currencies) Zero-decimal currencies If you use zero-decimal currencies (XAF, JPY, KRW, etc.), existing data was incorrectly multiplied by 100. Run the fix command: # Preview what will change php artisan shopper:upgrade:fix-zero-decimal-currencies --dry-run # Apply the fix php artisan shopper:upgrade:fix-zero-decimal-currencies Put your site in maintenance mode before running this command. It modifies prices, orders, order items, carrier options, cart lines, and discounts. #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#new-helpers) New helpers Two new helpers are available: | Helper | Purpose | | --- | --- | | `zero_decimal_currencies()` | Returns the list of zero-decimal currency codes | | `is_no_division_currency($code)` | Checks if a currency code is zero-decimal | #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#moneyinput-component) MoneyInput component A new Filament form component handles the conversion between human values (form display) and smallest unit (database) automatically: use Shopper\Components\Form\MoneyInput; MoneyInput::make('price') ->currency('USD') ->suffix('USD'); If no currency is specified, it defaults to the shop’s configured currency. For zero-decimal currencies, the mask precision adjusts to 0 automatically. #### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#filament-table-columns) Filament table columns Replace `->money()` with the `->currency()` macro: TextColumn::make('amount')->money(fn ($record) => $record->currencyCode) TextColumn::make('amount')->currency(fn ($record) => $record->currencyCode) **Existing database data for standard currencies (USD, EUR, GBP) is already correct**. The old setters stored values in cents. No migration needed for these currencies. * * * ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#slide-over-components-replaced) Slide-Over Components Replaced **Likelihood of Impact: High** _Affects applications with custom slide-over components extending Shopper’s base class._ Shopper’s internal `SlideOverComponent` and `SlideOverPanel` classes have been removed and replaced by the [`laravelcm/livewire-slide-overs`](https://github.com/laravelcm/livewire-slide-overs) package. If you created custom slide-over components that extend Shopper’s base class, update the import: use Shopper\Livewire\Components\SlideOverComponent; use Laravelcm\LivewireSlideOvers\SlideOverComponent; The `closePanelWithEvents()` method no longer exists: $this->closePanelWithEvents(['eventName']); $this->dispatch('eventName'); $this->closePanel(); * * * [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#medium-impact-changes) Medium Impact Changes ----------------------------------------------------------------------------------------------------------- ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#two-factor-authentication-solid-interfaces) Two-Factor Authentication: SOLID Interfaces **Likelihood of Impact: Medium** _Affects applications that override the User model and use two-factor authentication._ The monolithic `TwoFactorAuthenticatable` trait has been split into focused interfaces and traits: use Shopper\Traits\TwoFactorAuthenticatable; use Shopper\Contracts\HasStoreAuthentication; use Shopper\Contracts\HasStoreAuthenticationRecovery; use Shopper\Traits\InteractsWithStoreAuthentication; use Shopper\Traits\InteractsWithStoreAuthenticationRecovery; class User extends Authenticatable class User extends Authenticatable implements HasStoreAuthentication, HasStoreAuthenticationRecovery { use TwoFactorAuthenticatable; use InteractsWithStoreAuthentication; use InteractsWithStoreAuthenticationRecovery; } The two-factor columns on the users table have been renamed to avoid conflicts with Laravel Fortify’s own 2FA columns. Update the `$hidden` array on your User model: protected $hidden = [\ 'password',\ 'remember_token',\ 'two_factor_secret', \ 'two_factor_recovery_codes', \ 'store_two_factor_secret', \ 'store_two_factor_recovery_codes', \ ]; ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#filament-hasforms-to-hasschemas) Filament HasForms to HasSchemas **Likelihood of Impact: Medium** _Affects applications with custom Filament components that use `InteractsWithForms`._ Shopper now uses `InteractsWithSchemas` instead of `InteractsWithForms`. If you have custom components in `app/Shopper/` or `app/Livewire/`: use Filament\Forms\Concerns\InteractsWithForms; use Filament\Forms\Contracts\HasForms; use Filament\Schemas\Concerns\InteractsWithSchemas; use Filament\Schemas\Contracts\HasSchemas; `InteractsWithForms` still works in Filament 4.x. This migration is recommended but not urgent. ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#dependency-version-bumps) Dependency Version Bumps **Likelihood of Impact: Medium** _Affects all applications._ | Dependency | Before | After | | --- | --- | --- | | `laravel/framework` | `^11.0\|^12.0` | `^11.28\|^12.0` | | `filament/filament` | `^4.7` | `^4.9` | | `spatie/laravel-permission` | `^6.24` | `^6.24\|^7.0` | * * * [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#low-impact-changes) Low Impact Changes ----------------------------------------------------------------------------------------------------- ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#interactswithslideoverform-trait) InteractsWithSlideOverForm Trait 10 slide-over form components now use the shared `InteractsWithSlideOverForm` trait and a generic Blade view. Their dedicated Blade views have been removed: `add-collection-form.blade.php`, `attribute-form.blade.php`, `brand-form.blade.php`, `category-form.blade.php`, `create-team-member.blade.php`, `discount-form.blade.php`, `supplier-form.blade.php`, `update-variant.blade.php` If you published and customized any of these views, you’ll need to adapt to the new generic view or override the component’s `render()` method. ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#shipment-event-date-validation) Shipment Event Date Validation Shipment events now enforce chronological ordering. You cannot create an event with a date earlier than the previous event. The `RecordShipmentEventAction` validates this server-side. ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#nested-sortable-categories) Nested Sortable Categories Categories can now be reordered with drag & drop in the admin panel. No code changes required. ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#collection-price-rules) Collection Price Rules Automatic collection price rules now filter by the shop’s default currency when evaluating products. * * * [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#new-features) New Features ----------------------------------------------------------------------------------------- ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#upgrade-package) Upgrade Package `shopper/upgrade` is a new temporary package with Laravel Boost skills for AI-assisted upgrades and an artisan command for zero-decimal currency data fixes. Install it before upgrading, remove it after. ### [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#moneyinput-component-2) MoneyInput Component A new `MoneyInput` Filament form component that handles currency-aware conversion between human values and smallest unit storage. * * * [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#migration-checklist) Migration Checklist ------------------------------------------------------------------------------------------------------- 1 [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#) Install the upgrade package Run `composer require shopper/upgrade:^2.7 --dev` and `php artisan boost:install` to get AI-assisted migration prompts. 2 [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#) Update storefront price reads Replace direct price property access with `shopper_money_format()` for display. Use raw values for calculations. 3 [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#) Update storefront price writes Pass values in smallest currency unit to all `create()` / `update()` calls on monetary fields. 4 [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#) Update payment gateway code Remove any `* 100` multiplication before sending to Stripe or other providers. 5 [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#) Fix zero-decimal currency data Run `php artisan shopper:upgrade:fix-zero-decimal-currencies` if you use XAF, JPY, or other zero-decimal currencies. 6 [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#) Update slide-over imports Replace `Shopper\Livewire\Components\SlideOverComponent` with `Laravelcm\LivewireSlideOvers\SlideOverComponent` in any custom slide-overs. 7 [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#) Update 2FA traits and hidden fields Replace `TwoFactorAuthenticatable` with the new interfaces and traits if you override the User model. Update your `$hidden` array to use `store_two_factor_secret` and `store_two_factor_recovery_codes` instead of the old column names. 8 [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#) Update dependencies Run `composer update -W` after setting `shopper/framework` to `^2.7`. 9 [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#) Run tests Run `php artisan test` and fix assertions that expect human-readable price values instead of cents. 10 [](https://docs.laravelshopper.dev/v2/upgrade/v2-6-to-v2-7#) Remove upgrade package Run `composer remove shopper/upgrade --dev` when done. [From v2.7 to v2.8](https://docs.laravelshopper.dev/v2/upgrade/v2-7-to-v2-8) [From v2.5 to v2.6](https://docs.laravelshopper.dev/v2/upgrade/v2-5-to-v2-6) ⌘I --- # Taxes - TALL Stack E-commerce Framework > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://docs.laravelshopper.dev/v2/taxes#content-area) Shopper calculates taxes per line item, based on where an order is being shipped. You define geographic zones, assign percentage rates to each zone, and optionally override those rates for specific products, product types, or categories. The cart pipeline applies all of this automatically during checkout. All tax amounts are stored in **cents** as unsigned integers, consistent with the rest of the monetary system. [](https://docs.laravelshopper.dev/v2/taxes#how-it-works) How It Works -------------------------------------------------------------------------- The tax system has four main pieces: 1. **TaxZone**: a geographic area (country, or country + province) with a tax inclusion policy and an optional custom provider 2. **TaxRate**: a percentage rate attached to a zone; one rate per zone is marked as the default 3. **TaxRateRule**: a targeting rule on a rate; when a cart line matches a rule, its rate takes priority over the zone’s default 4. **TaxCalculationProvider**: the service responsible for receiving a taxable item and a context, and returning `TaxLine` value objects When the cart is being calculated, the `CalculateTax` pipeline step reads the shipping address, resolves the matching `TaxZone`, picks the applicable `TaxRate`, and persists a `CartLineTaxLine` record for every cart line with a non-zero tax amount. [](https://docs.laravelshopper.dev/v2/taxes#tax-zones) Tax Zones -------------------------------------------------------------------- A tax zone defines where a tax configuration applies. It maps to a country and optionally to a specific province or state within that country. The most important setting on a zone is `is_tax_inclusive`, which determines whether prices already include tax (VAT, common in Europe) or whether tax is added on top (sales tax, common in the US). use Shopper\Core\Models\Country; use Shopper\Core\Models\TaxZone; $france = Country::query()->where('cca2', 'FR')->firstOrFail(); TaxZone::query()->create([\ 'country_id' => $france->id,\ 'name' => 'Standard VAT',\ 'is_tax_inclusive' => true,\ ]); $usa = Country::query()->where('cca2', 'US')->firstOrFail(); TaxZone::query()->create([\ 'country_id' => $usa->id,\ 'province_code' => 'CA',\ 'name' => 'California Sales Tax',\ 'is_tax_inclusive' => false,\ ]); When the calculator resolves a zone for a shipping address, it first tries to find a zone matching both the country and province. If none exists, it falls back to a country-level zone with no `province_code`. The `display_name` accessor produces a human-readable label by combining country and zone name (for example, `France — Standard VAT`). ### [](https://docs.laravelshopper.dev/v2/taxes#zone-schema) Zone Schema | Column | Type | Description | | --- | --- | --- | | `country_id` | `unsignedBigInteger` | The country this zone applies to | | `province_code` | `nullable string` | ISO province/state code (`CA`, `NY`, `IDF`) | | `name` | `nullable string` | Optional label to identify the zone in the admin | | `is_tax_inclusive` | `boolean` | Whether prices already include tax (VAT) or not (sales tax) | | `provider_id` | `nullable unsignedBigInteger` | Custom tax provider; falls back to the system default when null | | `parent_id` | `nullable unsignedBigInteger` | Parent zone for hierarchical configurations | | `metadata` | `nullable jsonb` | Arbitrary data for custom providers | The combination of `country_id` and `province_code` is unique, you cannot have two zones for the same country/province pair. The TaxZone model is configurable via `config/shopper/models.php`. ### [](https://docs.laravelshopper.dev/v2/taxes#zone-relationships) Zone Relationships | Relationship | Type | Description | | --- | --- | --- | | `country()` | `BelongsTo` | The country this zone is scoped to | | `rates()` | `HasMany` | All tax rates defined for this zone | | `provider()` | `BelongsTo` | The custom tax provider assigned to this zone | | `parent()` | `BelongsTo` | Parent zone | | `children()` | `HasMany` | Child zones | [](https://docs.laravelshopper.dev/v2/taxes#tax-rates) Tax Rates -------------------------------------------------------------------- Each zone has one or more rates. One rate should be marked as `is_default` it applies to every item in the zone that does not match a more specific override rule. use Shopper\Core\Models\TaxRate; TaxRate::query()->create([\ 'tax_zone_id' => $franceZone->id,\ 'name' => 'TVA 20%',\ 'code' => 'FR_VAT_STANDARD',\ 'rate' => 20.0,\ 'is_default' => true,\ ]); France has a reduced VAT rate of 5.5% on food. You can define it as a separate non-default rate on the same zone, then target it at the right product category using a rule: TaxRate::query()->create([\ 'tax_zone_id' => $franceZone->id,\ 'name' => 'TVA reduce 5.5%',\ 'code' => 'FR_VAT_REDUCED',\ 'rate' => 5.5,\ 'is_default' => false,\ ]); ### [](https://docs.laravelshopper.dev/v2/taxes#tax-rate-schema) Tax Rate Schema | Column | Type | Description | | --- | --- | --- | | `tax_zone_id` | `unsignedBigInteger` | The zone this rate belongs to | | `name` | `string` | Display name shown on invoices (`TVA 20%`) | | `code` | `nullable string` | Machine-readable identifier (`FR_VAT_STANDARD`) | | `rate` | `decimal(8,4)` | Percentage value `20.0` means 20% | | `is_default` | `boolean` | Applied when no override rule matches the item | | `is_combinable` | `boolean` | Whether this rate stacks with rates from a parent zone | | `metadata` | `nullable jsonb` | Arbitrary data for external providers | The TaxRate model is configurable via `config/shopper/models.php`. ### [](https://docs.laravelshopper.dev/v2/taxes#rate-relationships) Rate Relationships | Relationship | Type | Description | | --- | --- | --- | | `taxZone()` | `BelongsTo` | The zone this rate is attached to | | `rules()` | `HasMany` | Override rules that activate this rate for specific items | [](https://docs.laravelshopper.dev/v2/taxes#tax-rate-rules) Tax Rate Rules ------------------------------------------------------------------------------ Rules let you override the default rate for specific items. The calculator checks all non-default rates with rules first. The first rule that matches the cart line wins; if none matches, the zone’s default rate is used. A rule has two fields: `reference_type` identifies what kind of entity to match, and `reference_id` holds the specific value to match against. use Shopper\Core\Models\TaxRateRule; TaxRateRule::query()->create([\ 'tax_rate_id' => $reducedRate->id,\ 'reference_type' => 'category',\ 'reference_id' => (string) $foodCategory->id,\ ]); This rule tells the calculator: “whenever a cart line belongs to the food category, use the 5.5% rate instead of the default 20%.” You can also target a specific product: TaxRateRule::query()->create([\ 'tax_rate_id' => $zeroVatRate->id,\ 'reference_type' => 'product',\ 'reference_id' => (string) $childrenBook->id,\ ]); Or an entire product type, which is useful for applying different rules to virtual goods versus physical ones: TaxRateRule::query()->create([\ 'tax_rate_id' => $digitalRate->id,\ 'reference_type' => 'product_type',\ 'reference_id' => 'virtual',\ ]); ### [](https://docs.laravelshopper.dev/v2/taxes#rule-reference-types) Rule Reference Types | `reference_type` | `reference_id` | Matches when | | --- | --- | --- | | `product_type` | A `ProductType` enum value (`standard`, `virtual`, `external`) | The item’s product type equals the value | | `product` | A product primary key, as a string | The item’s exact product ID matches | | `category` | A category primary key, as a string | The item belongs to that category | ### [](https://docs.laravelshopper.dev/v2/taxes#rule-schema) Rule Schema | Column | Type | Description | | --- | --- | --- | | `id` | bigint | Primary key | | `tax_rate_id` | bigint | FK to tax rate | | `reference_type` | string | Entity type to match (`product_type`, `product`, `category`) | | `reference_id` | string | Entity value or ID to match against | The combination of `tax_rate_id`, `reference_type`, and `reference_id` is unique. You cannot attach the same rule twice to the same rate. [](https://docs.laravelshopper.dev/v2/taxes#inclusive-vs-exclusive-taxes) Inclusive vs Exclusive Taxes ---------------------------------------------------------------------------------------------------------- The `is_tax_inclusive` flag on the zone controls the math behind the tax amount. **Tax-exclusive** (sales tax): tax is added on top of the price. The customer pays more than the listed price: tax = unit_price × rate / 100 total = unit_price + tax A 100productwitha10100 product with a 10% exclusive tax costs \*\*100productwitha10110\*\* at checkout. **Tax-inclusive** (VAT): tax is already embedded in the listed price. The customer pays exactly the listed price, but the tax authority receives a portion: tax = price − (price / (1 + rate / 100)) total = price (unchanged) A €100 product with 20% VAT inclusive: tax = €100 - (€100 / 1.2) = **€16.67**, amount before tax = **€83.33**. Shopper handles both formulas automatically in `SystemTaxProvider`. The zone’s `is_tax_inclusive` value is also propagated through the pipeline context so storefronts can present prices correctly showing “VAT included” or displaying tax as an addition at checkout. [](https://docs.laravelshopper.dev/v2/taxes#cart-integration) Cart Integration ---------------------------------------------------------------------------------- Tax calculation is part of the cart pipeline and runs automatically whenever you call `Cart::calculate()`. The `CalculateTax` step runs after discounts are applied, ensuring taxes are computed on the post-discount amount. The step does the following for each cart line: 1. Reads the cart’s shipping address country and province 2. Builds a `TaxCalculationContext` from those values 3. Passes a `CartLineTaxAdapter` for the line to `TaxCalculator::calculate()` 4. Deletes any existing `CartLineTaxLine` records for that line 5. Creates new `CartLineTaxLine` records with the resulting tax lines 6. Accumulates the tax total on the pipeline context use Shopper\Cart\Facades\Cart; $cart = Cart::calculate($cart); $cart->tax_amount; foreach ($cart->lines as $line) { $line->taxLines; } If no matching tax zone exists for the shipping address, the `CalculateTax` step skips silently and no tax lines are created. [](https://docs.laravelshopper.dev/v2/taxes#persisting-tax-lines-on-orders) Persisting Tax Lines on Orders -------------------------------------------------------------------------------------------------------------- When a cart is converted into an order, tax lines are snapshotted onto the order using `CreateOrderTaxLinesAction`. This snapshot preserves the exact tax breakdown at the moment of purchase future changes to zones or rates have no impact on historical orders. use Shopper\Core\Actions\CreateOrderTaxLinesAction; app(CreateOrderTaxLinesAction::class)->execute($order); The action resolves the shipping address country, runs `TaxCalculator::calculate()` for each order item, creates an `OrderTaxLine` record for each result, and updates `tax_amount` on both the order item and the order itself. ### [](https://docs.laravelshopper.dev/v2/taxes#ordertaxline-schema) OrderTaxLine Schema | Column | Type | Description | | --- | --- | --- | | `taxable_type` | `string` | Polymorphic type (`Order` or `OrderItem`) | | `taxable_id` | `unsignedBigInteger` | Polymorphic ID | | `tax_rate_id` | `nullable unsignedBigInteger` | Reference to the rate used at time of purchase | | `code` | `string` | Rate code snapshot | | `name` | `string` | Rate name snapshot | | `rate` | `decimal(8,4)` | Rate percentage snapshot | | `amount` | `unsignedInteger` | Tax amount in cents | ### [](https://docs.laravelshopper.dev/v2/taxes#accessing-tax-lines-on-an-order) Accessing Tax Lines on an Order use Shopper\Core\Models\Contracts\Order; $order = resolve(Order::class)::query() ->with(['items.taxLines', 'taxLines']) ->find($orderId); $order->tax_amount; foreach ($order->items as $item) { $item->tax_amount; foreach ($item->taxLines as $taxLine) { $taxLine->name; $taxLine->rate; $taxLine->amount; } } [](https://docs.laravelshopper.dev/v2/taxes#tax-providers) Tax Providers ---------------------------------------------------------------------------- A `TaxProvider` record links a zone to a custom tax calculation service. When a zone has an enabled provider, the calculator uses that provider instead of the built-in system. ### [](https://docs.laravelshopper.dev/v2/taxes#provider-schema) Provider Schema | Column | Type | Description | | --- | --- | --- | | `id` | bigint | Primary key | | `identifier` | string | Unique provider code (e.g., `avalara`, `taxjar`) | | `is_enabled` | boolean | Whether the provider is active | ### [](https://docs.laravelshopper.dev/v2/taxes#custom-tax-providers) Custom Tax Providers The built-in `SystemTaxProvider` handles most use cases. For regions that require an external API like Avalara, TaxJar, or a homegrown tax service, you can implement the `TaxCalculationProvider` contract and assign it to specific zones. The contract is simple: use Shopper\Core\Contracts\TaxCalculationProvider; use Shopper\Core\Contracts\TaxableItem; use Shopper\Core\Taxes\TaxCalculationContext; use Shopper\Core\Taxes\TaxLine; interface TaxCalculationProvider { public function identifier(): string; /** @return arraytwMerge(['class' => $containerClass]) }}>
[Card](https://docs.laravelshopper.dev/v2/extending/components/card)
[Heading](https://docs.laravelshopper.dev/v2/extending/components/heading)
⌘I
---
# Contribution Guide - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v2/contributing#content-area)
Contributions are accepted via Pull Requests on [Github](https://github.com/shopperlabs/shopper)
.
[](https://docs.laravelshopper.dev/v2/contributing#bug-reports)
Bug Reports
-------------------------------------------------------------------------------
To encourage active collaboration, Shopper strongly encourages pull requests, not just bug reports. “Bug reports” may also be sent in the form of a pull request containing a failing test.
[](https://docs.laravelshopper.dev/v2/contributing#pull-requests)
Pull Requests
-----------------------------------------------------------------------------------
* **Document any change in behaviour** - Make sure the `readme.md` and any other relevant documentation are kept up-to-date.
* **Consider our release cycle** - We try to follow [SemVer v2.0.0](http://semver.org/)
.
* **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
* **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](http://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages)
before submitting.
**Happy coding**!
[](https://docs.laravelshopper.dev/v2/contributing#security-vulnerabilities)
Security Vulnerabilities
---------------------------------------------------------------------------------------------------------
If you discover a security vulnerability within Shopper, please email us at [arthur@shopperlabs.co](mailto:arthur@shopperlabs.co)
. All security vulnerabilities will be promptly addressed.
[](https://docs.laravelshopper.dev/v2/contributing#coding-style)
Coding Style
---------------------------------------------------------------------------------
Laravel follows the [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
coding standard and the [PSR-4](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md)
autoloading standard.
[](https://docs.laravelshopper.dev/v2/contributing#code-of-conduct)
Code of Conduct
---------------------------------------------------------------------------------------
As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. We are committed to making participation in this project a harassment-free experience for everyone, regardless of the level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion. Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct. Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
[Demo Store](https://docs.laravelshopper.dev/v2/demo-store)
[Requirements](https://docs.laravelshopper.dev/v2/requirements)
⌘I
---
# Currencies - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v2/currencies#content-area)
Currencies define the monetary units used across your store. Each [zone](https://docs.laravelshopper.dev/v2/zones)
is associated with a currency, and each [price](https://docs.laravelshopper.dev/v2/pricing)
record is linked to a currency. Shopper supports multi-currency pricing out of the box, with over 150 currencies seeded during installation.
[](https://docs.laravelshopper.dev/v2/currencies#model)
Model
-----------------------------------------------------------------
The model used is `Shopper\Core\Models\Currency`. It implements `Shopper\Core\Models\Contracts\Currency`. The model has a global `enabled` scope that automatically filters out disabled currencies (see [Pricing](https://docs.laravelshopper.dev/v2/pricing#currency-model)
for details).
###
[](https://docs.laravelshopper.dev/v2/currencies#database-schema)
Database Schema
| Column | Type | Nullable | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | bigint | no | auto | Primary key |
| `name` | string | no | \- | Currency name (e.g., “US Dollar”) |
| `code` | string(10) | no | \- | ISO 4217 code (e.g., “USD”), unique |
| `symbol` | string(25) | no | \- | Currency symbol (e.g., ”$“) |
| `format` | string(50) | no | \- | Display format pattern |
| `exchange_rate` | decimal(10,2) | yes | null | Exchange rate relative to base currency |
| `is_enabled` | boolean | no | true | Whether the currency is active |
[](https://docs.laravelshopper.dev/v2/currencies#how-currencies-are-created)
How Currencies are Created
-----------------------------------------------------------------------------------------------------------
Currencies are defined in a JSON file at `core/database/data/currencies.json`. When you run `php artisan shopper:install`, a migration reads this file and inserts all currencies into the database. Shopper ships with over 150 currencies out of the box, so you rarely need to add more. If you do need a custom currency, create a migration that inserts it into the `currencies` table directly.
[](https://docs.laravelshopper.dev/v2/currencies#how-setup-store-currencies)
How Setup Store Currencies
-----------------------------------------------------------------------------------------------------------
After installing Shopper, you need to [set up your store](https://docs.laravelshopper.dev/v2/setup-store)
and during this step you’ll choose the currencies you want for your store and set the one that will be used by default. But once you’ve done this, in your general settings `Settings > General`, you can change these currencies.
[](https://docs.laravelshopper.dev/v2/currencies#zero-decimal-currencies)
Zero-Decimal Currencies
-----------------------------------------------------------------------------------------------------
Some currencies have no subdivision (no “cents”). For example, the Japanese Yen (JPY) and the Central African CFA Franc (XAF) are stored as whole numbers, so 1000 JPY is 1000, not 10.00. Shopper handles this automatically. The `is_no_division_currency()` helper checks if a currency code is zero-decimal, and `zero_decimal_currencies()` returns the full list:
is_no_division_currency('XAF'); // true
is_no_division_currency('USD'); // false
zero_decimal_currencies();
// ['BIF', 'CLP', 'DJF', 'GNF', 'HTG', 'JPY', 'KMF', 'KRW',\
// 'MGA', 'PYG', 'RWF', 'VND', 'VUV', 'XAF', 'XAG', 'XAU',\
// 'XDR', 'XOF', 'XPF']
The `shopper_money_format()` helper and the `MoneyInput` form component both use this to determine whether to divide/multiply by 100. See the [Pricing documentation](https://docs.laravelshopper.dev/v2/pricing)
for details.
[](https://docs.laravelshopper.dev/v2/currencies#relation-to-other-entities)
Relation to Other Entities
-----------------------------------------------------------------------------------------------------------
###
[](https://docs.laravelshopper.dev/v2/currencies#store)
Store
A store has a default currency and can have many currencies. These currencies are then used in other relations, such as when associating a zone with a currency. These 2 values are available throw the `Shopper\Core\Models\Setting` Model, under the values `default_currency_id` and `currencies` for the `key` column. The `shopper_setting('default_currency_id')` helper will return the id of the default currency and `shopper_setting('currencies')` will return and array of currencies setup for your store
###
[](https://docs.laravelshopper.dev/v2/currencies#zone)
Zone
Each Zone is associated with a currency. A currency can be used in more than one zone, but a zone can have only one currency. The relation is available on a Zone throw the `currency` relation and will return a `Shopper\Core\Models\Currency` object. You can also access the currency code through the attribute `currency_code` on the zone.
###
[](https://docs.laravelshopper.dev/v2/currencies#price)
Price
The Price entity is used to represent a price associated with an entity, for example for products or variants. Each price is associated with a currency. The relation is available on a Price throw the `currency` relation and will return a `Shopper\Core\Models\Currency` object. You can also access the currency code through the attribute `currency_code` on the zone.
[Locations](https://docs.laravelshopper.dev/v2/locations)
[Legal](https://docs.laravelshopper.dev/v2/legal)
⌘I
---
# Configuration - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v2/configuration#content-area)
Shopper publishes its configuration files to `config/shopper/` during installation. These files control the admin panel behavior, model resolution, feature flags, media handling, and more. Component configuration files are published separately on demand.
[](https://docs.laravelshopper.dev/v2/configuration#configuration-files)
Configuration Files
------------------------------------------------------------------------------------------------
The following files are published by `php artisan shopper:install`:
| File | Package | Purpose |
| --- | --- | --- |
| `admin.php` | admin | Admin panel prefix, domain, roles, branding, locales |
| `auth.php` | admin | Authentication guard, 2FA toggle, password reset |
| `core.php` | core | Database table prefix, barcode type |
| `features.php` | admin | Feature flags for each admin module |
| `media.php` | admin | Media storage, MIME types, max sizes, image conversions |
| `models.php` | admin | Model class resolution for every Shopper entity |
| `orders.php` | core | Order number generator format |
| `routes.php` | admin | Additional middleware and custom route files |
| `settings.php` | admin | Settings page registry |
Additional config files are published when you install optional packages like `shopper/cart` (`cart.php`), `shopper/payment` (`payment.php`), `shopper/shipping` (`shipping.php`), and `shopper/stripe` (`stripe.php`).
[](https://docs.laravelshopper.dev/v2/configuration#admin-panel)
Admin Panel
--------------------------------------------------------------------------------
By default, the admin panel is accessible at `/cpanel`. You can change this prefix in `config/shopper/admin.php` or by adding the `SHOPPER_PREFIX` variable to your `.env` file:
config/shopper/admin.php
'prefix' => env('SHOPPER_PREFIX', 'cpanel'),
If you change the prefix, run `php artisan shopper:link` to recreate the asset symlink with the new name.
To bind the admin panel to a specific domain, set the `SHOPPER_DOMAIN` environment variable. This uses Laravel’s `Route::domain()` under the hood:
config/shopper/admin.php
'domain' => env('SHOPPER_DOMAIN'),
You can also customize the admin panel branding (logo, favicon, and Filament primary color):
config/shopper/admin.php
'brand' => null,
'favicon' => null,
'primary_color' => \Filament\Support\Colors\Color::Blue,
The `primary_color` key accepts any [Filament color](https://filamentphp.com/docs/support/colors)
constant. After changing your primary color in your Tailwind config, update this value to keep Filament elements consistent.
###
[](https://docs.laravelshopper.dev/v2/configuration#avatar-colors)
Avatar Colors
Default colors for auto-generated user avatars (UI Avatars). Values are hexadecimal without the `#` prefix:
config/shopper/admin.php
'avatar' => [\
'color' => '1d4ed8',\
'bg_color' => 'dbeafe',\
],
###
[](https://docs.laravelshopper.dev/v2/configuration#locales)
Locales
Available languages in the admin panel. Each entry maps a locale code to a display label and a flag code (ISO 3166-1 alpha-2, lowercase) used for the flag SVG:
config/shopper/admin.php
'locales' => [\
'en' => ['label' => 'English', 'flag' => 'gb'],\
'fr' => ['label' => 'Français', 'flag' => 'fr'],\
],
###
[](https://docs.laravelshopper.dev/v2/configuration#custom-pages)
Custom Pages
If you create custom Livewire page components for the admin panel, configure the namespace and view path:
config/shopper/admin.php
'pages' => [\
'namespace' => 'App\\Livewire\\Shopper',\
'view_path' => resource_path('views/livewire/shopper'),\
],
[](https://docs.laravelshopper.dev/v2/configuration#database-table-prefix)
Database Table Prefix
----------------------------------------------------------------------------------------------------
All Shopper tables are prefixed with `sh_` by default so they do not conflict with your application’s existing tables.
config/shopper/core.php
'table_prefix' => 'sh_',
Set the table prefix before running `php artisan shopper:install`. Changing it after installation requires writing a custom migration to rename all existing Shopper tables.
[](https://docs.laravelshopper.dev/v2/configuration#feature-flags)
Feature Flags
------------------------------------------------------------------------------------
The `features.php` config controls which sections of the admin panel are active. Set any feature to `FeatureState::Disabled` to hide it from the UI entirely:
config/shopper/features.php
use Shopper\Enum\FeatureState;
return [\
'attribute' => FeatureState::Enabled,\
'brand' => FeatureState::Enabled,\
'category' => FeatureState::Enabled,\
'collection' => FeatureState::Enabled,\
'discount' => FeatureState::Enabled,\
'review' => FeatureState::Enabled,\
'supplier' => FeatureState::Disabled,\
'tag' => FeatureState::Enabled,\
];
For example, if your store does not use product reviews, set `'review' => FeatureState::Disabled` and the reviews page, sidebar link, and product form tab disappear from the admin panel.
[](https://docs.laravelshopper.dev/v2/configuration#models)
Models
----------------------------------------------------------------------
Shopper resolves model classes through `config/shopper/models.php`. To use your own model for any entity, replace the class in this file. The entire system (admin panel, relationships, route bindings) uses the configured class automatically. Models that have media support (images, thumbnails) use the `Shopper\Models` namespace from the admin package. Models without media use the `Shopper\Core\Models` namespace from the core package. When swapping a model, extend the class listed in the config comment for that entry.
config/shopper/models.php
use Shopper\Models;
return [\
'address' => Shopper\Core\Models\Address::class,\
'brand' => Models\Brand::class,\
'category' => Models\Category::class,\
'collection' => Models\Collection::class,\
'product' => Models\Product::class,\
'variant' => Models\ProductVariant::class,\
'channel' => Shopper\Core\Models\Channel::class,\
'inventory' => Shopper\Core\Models\Inventory::class,\
'order' => Shopper\Core\Models\Order::class,\
'supplier' => Shopper\Core\Models\Supplier::class,\
'tax_zone' => Shopper\Core\Models\TaxZone::class,\
'tax_rate' => Shopper\Core\Models\TaxRate::class,\
];
See the [Introduction](https://docs.laravelshopper.dev/v2/getting-started)
page for more details on model swapping and extensibility.
[](https://docs.laravelshopper.dev/v2/configuration#authentication)
Authentication
--------------------------------------------------------------------------------------
The `auth.php` config controls the authentication guard, two-factor authentication, and password reset flow for the admin panel:
config/shopper/auth.php
return [\
'guard' => 'web',\
'2fa_enabled' => false,\
'password_reset' => true,\
];
Set `2fa_enabled` to `true` to require two-factor authentication for admin users. See the [Two-Factor Authentication](https://docs.laravelshopper.dev/v2/two-factor)
page for setup details.
[](https://docs.laravelshopper.dev/v2/configuration#middleware)
Middleware
------------------------------------------------------------------------------
Shopper lets you add extra middleware to all authenticated admin routes. This is useful for logging, rate limiting, or custom access control:
config/shopper/routes.php
'middleware' => [],
[](https://docs.laravelshopper.dev/v2/configuration#custom-routes)
Custom Routes
------------------------------------------------------------------------------------
By default, your `web.php` routes are not loaded inside the admin panel. To add custom routes that share Shopper’s authentication middleware, point to a dedicated route file:
config/shopper/routes.php
'custom_file' => base_path('routes/shopper.php'),
Routes defined in this file are automatically loaded with the admin panel’s middleware stack.
[](https://docs.laravelshopper.dev/v2/configuration#components)
Components
------------------------------------------------------------------------------
Shopper’s admin UI is built from Livewire components that you can override individually. Each feature has a component configuration file listing its pages and components. To publish a feature’s component config, run the publish command with the feature name:
php artisan shopper:component:publish category
This creates `config/shopper/components/category.php` where you can point any component to your own class. Available features:
| Feature | Config file |
| --- | --- |
| `account` | `components/account.php` |
| `brand` | `components/brand.php` |
| `category` | `components/category.php` |
| `collection` | `components/collection.php` |
| `customer` | `components/customer.php` |
| `dashboard` | `components/dashboard.php` |
| `discount` | `components/discount.php` |
| `order` | `components/order.php` |
| `product` | `components/product.php` |
| `review` | `components/review.php` |
| `setting` | `components/setting.php` |
You can publish all component configs at once with `php artisan shopper:component:publish` (no argument).
[](https://docs.laravelshopper.dev/v2/configuration#settings)
Settings
--------------------------------------------------------------------------
Shopper uses a class-based approach for settings pages. Each setting is a class that implements the `Shopper\Contracts\SettingItem` interface. The `settings.php` config registers which settings are enabled:
config/shopper/settings.php
use Shopper\Settings\Items;
return [\
'items' => [\
Items\GeneralSetting::class => true,\
Items\StaffSetting::class => true,\
Items\LocationSetting::class => true,\
Items\PaymentSetting::class => true,\
Items\CarrierSetting::class => true,\
Items\LegalSetting::class => true,\
Items\ZoneSetting::class => true,\
Items\TaxSetting::class => true,\
Items\CurrencySetting::class => true,\
],\
];
To disable a setting page, set its value to `false`.
###
[](https://docs.laravelshopper.dev/v2/configuration#creating-a-custom-setting)
Creating a Custom Setting
To create your own setting page, extend the `Shopper\Settings\Setting` base class:
namespace App\Settings;
use Shopper\Settings\Setting;
final class MyCustomSetting extends Setting
{
public function name(): string
{
return 'My Custom Setting';
}
public function description(): string
{
return 'Manage your custom configuration.';
}
public function icon(): string
{
return 'heroicon-o-cog';
}
public function url(): string
{
return route('shopper.settings.custom');
}
public function order(): int
{
return 10;
}
public function permission(): ?string
{
return 'manage_custom_settings';
}
}
Then register it in the `settings.php` config file:
'items' => [\
App\Settings\MyCustomSetting::class => true,\
],
###
[](https://docs.laravelshopper.dev/v2/configuration#programmatic-registration)
Programmatic Registration
You can also register settings at runtime through the `SettingManager`:
use Shopper\Settings\SettingManager;
app(SettingManager::class)->add(App\Settings\MyCustomSetting::class);
Disabling setting items removes the corresponding interface from the admin panel. Make sure your team does not need access to those settings before disabling them.
[](https://docs.laravelshopper.dev/v2/configuration#order-number-format)
Order Number Format
------------------------------------------------------------------------------------------------
The `orders.php` config controls how order numbers are generated. You can customize the prefix, separator, date format, and sequence padding:
config/shopper/orders.php
'generator' => [\
'prefix' => 'ORD',\
'separator' => '-',\
'date_format' => 'Ymd',\
'start_sequence_from' => 1,\
'pad_length' => 6,\
'pad_string' => '0',\
],
Examples of generated numbers depending on configuration:
| Configuration | Result |
| --- | --- |
| Default | `ORD-20260328-000001` |
| `'prefix' => null` | `20260328-000001` |
| `'date_format' => null` | `ORD-000001` |
| `'prefix' => null, 'date_format' => null` | `000001` |
[Installation](https://docs.laravelshopper.dev/v2/installation)
[Dashboard](https://docs.laravelshopper.dev/v2/dashboard)
⌘I
---
# Channels - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v2/channels#content-area)
Channels represent different sales platforms where your products can be sold. Examples include your main website, mobile app, marketplace integrations, or physical stores.
[](https://docs.laravelshopper.dev/v2/channels#model)
Model
---------------------------------------------------------------
The model used is `Shopper\Core\Models\Channel`. It implements `Shopper\Core\Models\Contracts\Channel` and uses the `HasSlug` trait for automatic slug generation. The model is configurable via `config/shopper/models.php`.
###
[](https://docs.laravelshopper.dev/v2/channels#extending-the-model)
Extending the Model
To add custom behavior, extend the model and update your configuration:
namespace App\Models;
use Shopper\Core\Models\Channel as BaseChannel;
class Channel extends BaseChannel
{
}
Update `config/shopper/models.php`:
return [\
'channel' => \App\Models\Channel::class,\
];
[](https://docs.laravelshopper.dev/v2/channels#database-schema)
Database Schema
-----------------------------------------------------------------------------------
| Column | Type | Nullable | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | bigint | no | auto | Primary key |
| `name` | string | no | \- | Channel name |
| `slug` | string | yes | auto | URL-friendly identifier (unique) |
| `description` | text | yes | null | Channel description |
| `timezone` | string | yes | null | Channel timezone |
| `url` | string | yes | null | Channel URL |
| `is_default` | boolean | no | false | Default channel flag |
| `is_enabled` | boolean | no | false | Channel visibility |
| `metadata` | json | yes | null | Additional custom data |
| `created_at` | timestamp | yes | null | Creation timestamp |
| `updated_at` | timestamp | yes | null | Last update timestamp |
[](https://docs.laravelshopper.dev/v2/channels#relationships)
Relationships
-------------------------------------------------------------------------------
###
[](https://docs.laravelshopper.dev/v2/channels#products)
Products
Channels have a many-to-many polymorphic relationship with products:
// Get all products for a channel
$channel->products; // Collection of Product models
// Add products to channel
$channel->products()->attach([$productId1, $productId2]);
// Remove products from channel
$channel->products()->detach($productId);
// Sync products
$channel->products()->sync($productIds);
[](https://docs.laravelshopper.dev/v2/channels#query-scopes)
Query Scopes
-----------------------------------------------------------------------------
use Shopper\Core\Models\Channel;
// Get only the default channel
Channel::query()->default()->first();
// Get only enabled channels
Channel::query()->enabled()->get();
// Combine scopes
Channel::query()
->enabled()
->where('timezone', 'UTC')
->get();
[](https://docs.laravelshopper.dev/v2/channels#observer-behavior)
Observer Behavior
---------------------------------------------------------------------------------------
The `ChannelObserver` ensures only one channel can be default:
// When creating/updating a channel with is_default = true:
// 1. Any existing default channel is set to is_default = false
// 2. The new/updated channel becomes the default
$channel = Channel::query()->create([\
'name' => 'Mobile App',\
'is_default' => true, // Previous default is automatically unset\
]);
[](https://docs.laravelshopper.dev/v2/channels#default-channel)
Default Channel
-----------------------------------------------------------------------------------
You can retrieve the default channel using the `default` scope:
use Shopper\Core\Models\Channel;
// Get the default channel
$channel = Channel::query()->default()->first();
// Use in controllers
public function index()
{
$channel = Channel::query()->default()->first();
$products = Product::query()
->forChannel($channel->id)
->publish()
->get();
}
[](https://docs.laravelshopper.dev/v2/channels#creating-channels)
Creating Channels
---------------------------------------------------------------------------------------
###
[](https://docs.laravelshopper.dev/v2/channels#default-website-channel)
Default Website Channel
use Shopper\Core\Models\Channel;
$channel = Channel::query()->create([\
'name' => 'Website',\
'slug' => 'website',\
'description' => 'Main e-commerce website',\
'url' => 'https://example.com',\
'timezone' => 'UTC',\
'is_default' => true,\
'is_enabled' => true,\
]);
###
[](https://docs.laravelshopper.dev/v2/channels#additional-channels)
Additional Channels
// Mobile app channel
$mobileChannel = Channel::query()->create([\
'name' => 'Mobile App',\
'slug' => 'mobile-app',\
'description' => 'iOS and Android mobile application',\
'timezone' => 'UTC',\
'is_enabled' => true,\
]);
// Marketplace channel
$marketplaceChannel = Channel::query()->create([\
'name' => 'Amazon',\
'slug' => 'amazon',\
'description' => 'Amazon marketplace integration',\
'url' => 'https://amazon.com/store/your-store',\
'is_enabled' => true,\
'metadata' => [\
'marketplace_id' => 'ATVPDKIKX0DER',\
'seller_id' => 'A1234567890',\
],\
]);
[](https://docs.laravelshopper.dev/v2/channels#retrieving-channels)
Retrieving Channels
-------------------------------------------------------------------------------------------
use Shopper\Core\Models\Channel;
// Get all enabled channels
$channels = Channel::query()->enabled()->get();
// Get default channel
$default = Channel::query()->default()->first();
// Get channel by slug
$channel = Channel::query()
->where('slug', 'website')
->first();
// Get channel with products
$channel = Channel::query()
->with('products')
->where('slug', 'mobile-app')
->first();
// Get channels with product counts
$channels = Channel::query()
->enabled()
->withCount('products')
->get();
[](https://docs.laravelshopper.dev/v2/channels#assigning-products-to-channels)
Assigning Products to Channels
-----------------------------------------------------------------------------------------------------------------
use Shopper\Models\Product;
$product = Product::query()->find($id);
// Assign to channels (via product)
$product->channels()->attach([$channelId1, $channelId2]);
// Get products for a specific channel
$products = Product::query()
->forChannel($channelId)
->publish()
->get();
// Get products available on multiple channels
$products = Product::query()
->forChannel([$channelId1, $channelId2])
->publish()
->get();
[](https://docs.laravelshopper.dev/v2/channels#storefront-example)
Storefront Example
-----------------------------------------------------------------------------------------
namespace App\Http\Controllers;
use Shopper\Core\Models\Channel;
use Shopper\Models\Product;
class ProductController extends Controller
{
public function index()
{
// Get products for default channel
$channel = Channel::query()->default()->first();
$products = Product::query()
->forChannel($channel->id)
->publish()
->with(['brand', 'categories'])
->paginate(12);
return view('products.index', compact('products'));
}
}
###
[](https://docs.laravelshopper.dev/v2/channels#multi-channel-api)
Multi-Channel API
namespace App\Http\Controllers\Api;
use Shopper\Core\Models\Channel;
use Shopper\Models\Product;
class ProductController extends Controller
{
public function index(Request $request)
{
$channelSlug = $request->header('X-Channel', 'website');
$channel = Channel::query()
->where('slug', $channelSlug)
->enabled()
->firstOrFail();
$products = Product::query()
->forChannel($channel->id)
->publish()
->paginate(20);
return response()->json($products);
}
}
[](https://docs.laravelshopper.dev/v2/channels#use-cases)
Use Cases
-----------------------------------------------------------------------
| Channel | Example Use |
| --- | --- |
| Website | Main e-commerce storefront |
| Mobile App | iOS/Android application |
| Marketplace | Amazon, eBay, Etsy integration |
| POS | Physical store point of sale |
| Wholesale | B2B customer portal |
| Social | Facebook/Instagram shop |
[](https://docs.laravelshopper.dev/v2/channels#best-practices)
Best Practices
---------------------------------------------------------------------------------
1. **Default Channel**: Always have one default channel for fallback
2. **Product Assignment**: Assign products to relevant channels during creation
3. **Timezone**: Set appropriate timezone for each channel
4. **Metadata**: Use metadata for channel-specific configuration (API keys, etc.)
// Example: Channel-specific pricing
$channel = Channel::query()->find($id);
$apiKey = $channel->metadata['api_key'] ?? null;
$merchantId = $channel->metadata['merchant_id'] ?? null;
[Setup Store](https://docs.laravelshopper.dev/v2/setup-store)
[Zones](https://docs.laravelshopper.dev/v2/zones)
⌘I
---
# Collections - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v2/collections#content-area)
Collections are curated groups of products for marketing and merchandising. Unlike categories, collections can be manually curated or automatically populated based on rules.
[](https://docs.laravelshopper.dev/v2/collections#model)
Model
------------------------------------------------------------------
The model used is `Shopper\Models\Collection`, which extends `Shopper\Core\Models\Collection`. The core model provides the business logic, relationships, scopes, rule evaluation, and slug generation. The admin model adds media collections and conversions through Spatie MediaLibrary. The core model implements `Shopper\Core\Models\Contracts\Collection` and uses the `HasSlug` trait for automatic slug generation with collision handling.
###
[](https://docs.laravelshopper.dev/v2/collections#extending-the-model)
Extending the Model
To add custom behavior, extend the admin model and update your configuration:
namespace App\Models;
use Shopper\Models\Collection as ShopperCollection;
class Collection extends ShopperCollection
{
}
Update `config/shopper/models.php`:
return [\
'collection' => \App\Models\Collection::class,\
];
[](https://docs.laravelshopper.dev/v2/collections#database-schema)
Database Schema
--------------------------------------------------------------------------------------
###
[](https://docs.laravelshopper.dev/v2/collections#collection-table)
Collection Table
| Column | Type | Nullable | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | bigint | no | auto | Primary key |
| `name` | string | no | \- | Collection name |
| `slug` | string | no | auto | URL-friendly identifier (unique) |
| `description` | longtext | yes | null | Collection description |
| `type` | string | no | \- | Collection type (manual/auto) |
| `sort` | string | yes | null | Product sorting method |
| `match_conditions` | string | yes | null | Rule matching logic (all/any) |
| `published_at` | datetime | yes | null | Publication date |
| `seo_title` | string(60) | yes | null | SEO meta title |
| `seo_description` | string(160) | yes | null | SEO meta description |
| `metadata` | json | yes | null | Additional custom data |
###
[](https://docs.laravelshopper.dev/v2/collections#collectionrule-table)
CollectionRule Table
| Column | Type | Nullable | Description |
| --- | --- | --- | --- |
| `id` | bigint | no | Primary key |
| `rule` | string | no | Rule type identifier |
| `operator` | string | no | Comparison operator |
| `value` | string | no | Value to compare against |
| `collection_id` | bigint | no | Foreign key to collection |
[](https://docs.laravelshopper.dev/v2/collections#collection-types)
Collection Types
----------------------------------------------------------------------------------------
use Shopper\Core\Enum\CollectionType;
CollectionType::Manual // Products are manually selected
CollectionType::Auto // Products are added based on rules
###
[](https://docs.laravelshopper.dev/v2/collections#type-checking)
Type Checking
$collection->isManual(); // true for manual collections
$collection->isAutomatic(); // true for automatic collections
[](https://docs.laravelshopper.dev/v2/collections#relationships)
Relationships
----------------------------------------------------------------------------------
###
[](https://docs.laravelshopper.dev/v2/collections#products)
Products
A collection groups products together for merchandising, such as “Summer Essentials”, “New Arrivals”, or “Black Friday Deals”. For manual collections, you explicitly attach and detach products. For automatic collections, products are matched by rules (see [Collection Rules](https://docs.laravelshopper.dev/v2/collections#collection-rules)
).
$collection->products;
For manual collections, manage products with the standard Eloquent relationship methods:
$collection->products()->attach([$productId1, $productId2]);
$collection->products()->detach($productId);
$collection->products()->sync($productIds);
###
[](https://docs.laravelshopper.dev/v2/collections#zones)
Zones
Collections can be scoped to specific geographic zones. This is useful when a promotion or product group only applies to certain markets.
$collection->zones;
$collection->zones()->attach([$zoneId1, $zoneId2]);
$collection->zones()->detach($zoneId);
$collection->zones()->sync($zoneIds);
From the zone side, you can retrieve all associated collections:
$zone = Zone::query()->find($id);
$zone->collections;
###
[](https://docs.laravelshopper.dev/v2/collections#rules-automatic-collections)
Rules (Automatic Collections)
Automatic collections use rules to determine which products belong to them. Each rule defines a condition that products must match.
$collection->rules;
Add a rule that matches products whose title contains “summer”:
use Shopper\Core\Enum\Operator;
use Shopper\Core\Enum\Rule;
$collection->rules()->create([\
'rule' => Rule::ProductTitle,\
'operator' => Operator::Contains,\
'value' => 'summer',\
]);
[](https://docs.laravelshopper.dev/v2/collections#slug-&-lookup)
Slug & Lookup
----------------------------------------------------------------------------------
The `HasSlug` trait generates unique slugs automatically and provides a `findBySlug()` static method:
use Shopper\Models\Collection;
$collection = Collection::findBySlug('summer-essentials');
[](https://docs.laravelshopper.dev/v2/collections#query-scopes)
Query Scopes
--------------------------------------------------------------------------------
Filter collections by type:
Collection::query()->manual()->get();
Collection::query()->automatic()->get();
The `published` scope filters collections that have a `published_at` date in the past or present:
Collection::query()->published()->get();
[](https://docs.laravelshopper.dev/v2/collections#collection-rules)
Collection Rules
----------------------------------------------------------------------------------------
###
[](https://docs.laravelshopper.dev/v2/collections#rule-types)
Rule Types
use Shopper\Core\Enum\Rule;
Rule::ProductTitle // Match product title
Rule::ProductPrice // Match product price
Rule::CompareAtPrice // Match compare at price
Rule::InventoryStock // Match stock level
Rule::ProductBrand // Match product brand
Rule::ProductCategory // Match product category
Rule::ProductCreatedAt // Match product creation date
Rule::ProductFeatured // Match featured status
Rule::ProductRating // Match average rating
Rule::ProductSalesCount // Match total units sold
| Rule | Database Value | Description |
| --- | --- | --- |
| Product Title | `product_title` | Match against product name |
| Product Price | `product_price` | Match against `amount` on prices table (stored in cents) |
| Compare Price | `compare_at_price` | Match against `compare_amount` on prices table (stored in cents) |
| Inventory Stock | `inventory_stock` | Match against stock level |
| Product Brand | `product_brand` | Match against brand name |
| Product Category | `product_category` | Match against category name |
| Product Created Date | `product_created_at` | Match against creation date |
| Product Featured | `product_featured` | Match featured status (1 or 0) |
| Product Rating | `product_rating` | Match average approved rating |
| Product Sales Count | `product_sales_count` | Match total units sold (paid/shipped/delivered/completed orders only) |
**Price rules** (`ProductPrice`, `CompareAtPrice`) store values in cents. Pass the value in cents directly (e.g., `'5000'` for $50.00). Price rules are evaluated against the shop’s default currency.**Sales count** (`ProductSalesCount`) only counts units from orders with a valid status: `paid`, `shipped`, `delivered`, or `completed`.
###
[](https://docs.laravelshopper.dev/v2/collections#operators)
Operators
use Shopper\Core\Enum\Operator;
Operator::EqualsTo // equals_to
Operator::NotEqualTo // not_equal_to
Operator::GreaterThan // greater_than
Operator::LessThan // less_than
Operator::StartsWith // starts_with
Operator::EndsWith // ends_with
Operator::Contains // contains
Operator::NotContains // not_contains
###
[](https://docs.laravelshopper.dev/v2/collections#match-conditions)
Match Conditions
When a collection has multiple rules, `match_conditions` determines how they combine. With `all`, every rule must match. With `any`, a single matching rule is enough.
$collection->match_conditions = 'all';
$collection->match_conditions = 'any';
[](https://docs.laravelshopper.dev/v2/collections#display-helpers)
Display Helpers
--------------------------------------------------------------------------------------
The `firstRule()` method returns a human-readable summary of the collection’s rules, like “Product title contains Summer + 2 other”:
$collection->firstRule();
[](https://docs.laravelshopper.dev/v2/collections#creating-collections)
Creating Collections
------------------------------------------------------------------------------------------------
###
[](https://docs.laravelshopper.dev/v2/collections#manual-collection)
Manual Collection
use Shopper\Models\Collection;
use Shopper\Core\Enum\CollectionType;
$collection = Collection::query()->create([\
'name' => 'Summer Essentials',\
'type' => CollectionType::Manual,\
'published_at' => now(),\
]);
$collection->products()->attach([$product1->id, $product2->id]);
###
[](https://docs.laravelshopper.dev/v2/collections#automatic-collection)
Automatic Collection
Automatic collections populate themselves based on rules. Here’s a “Sale Items” collection that matches products under $50 with “sale” in the title:
use Shopper\Core\Enum\CollectionType;
use Shopper\Core\Enum\Operator;
use Shopper\Core\Enum\Rule;
$collection = Collection::query()->create([\
'name' => 'Sale Items',\
'type' => CollectionType::Auto,\
'match_conditions' => 'all',\
'published_at' => now(),\
]);
$collection->rules()->createMany([\
[\
'rule' => Rule::ProductPrice,\
'operator' => Operator::LessThan,\
'value' => '5000',\
],\
[\
'rule' => Rule::ProductTitle,\
'operator' => Operator::Contains,\
'value' => 'sale',\
],\
]);
###
[](https://docs.laravelshopper.dev/v2/collections#best-sellers-collection)
Best Sellers Collection
A collection that automatically includes products with more than 10 units sold:
$collection = Collection::query()->create([\
'name' => 'Best Sellers',\
'type' => CollectionType::Auto,\
'match_conditions' => 'all',\
'published_at' => now(),\
]);
$collection->rules()->create([\
'rule' => Rule::ProductSalesCount,\
'operator' => Operator::GreaterThan,\
'value' => '10',\
]);
###
[](https://docs.laravelshopper.dev/v2/collections#top-rated-collection)
Top Rated Collection
$collection = Collection::query()->create([\
'name' => 'Top Rated',\
'type' => CollectionType::Auto,\
'match_conditions' => 'all',\
'published_at' => now(),\
]);
$collection->rules()->create([\
'rule' => Rule::ProductRating,\
'operator' => Operator::GreaterThan,\
'value' => '3', // Average rating > 3 (4-5 stars)\
]);
[](https://docs.laravelshopper.dev/v2/collections#retrieving-collections)
Retrieving Collections
----------------------------------------------------------------------------------------------------
All published collections:
$collections = Collection::query()->published()->get();
A collection with its published products:
$collection = Collection::findBySlug('summer-essentials');
$products = $collection->productsQuery()->publish()->get();
Filter by type:
$manualCollections = Collection::query()->manual()->get();
$autoCollections = Collection::query()
->automatic()
->with('rules')
->get();
[](https://docs.laravelshopper.dev/v2/collections#retrieving-products)
Retrieving Products
----------------------------------------------------------------------------------------------
Shopper provides built-in methods to retrieve products from collections, handling both manual and automatic collections transparently.
###
[](https://docs.laravelshopper.dev/v2/collections#basic-usage)
Basic Usage
The `getProducts()` method works for both collection types. For manual collections it returns attached products. For automatic collections it evaluates the rules and returns matching products.
$collection = Collection::query()->find($id);
$products = $collection->getProducts();
For pagination or additional filtering, use `productsQuery()` which returns an Eloquent builder:
$products = $collection->productsQuery()->paginate(12);
$products = $collection->productsQuery()
->where('featured', true)
->orderBy('name')
->get();
###
[](https://docs.laravelshopper.dev/v2/collections#how-it-works)
How It Works
For **manual collections**, `getProducts()` returns the attached products via the `products()` relationship. For **automatic collections**, `getProducts()` evaluates all defined rules and returns matching products:
* **Match All**: All rules must be satisfied (AND logic)
* **Match Any**: At least one rule must be satisfied (OR logic)
$collection = Collection::query()
->where('slug', 'sale-items')
->with('rules')
->first();
$products = $collection->getProducts();
###
[](https://docs.laravelshopper.dev/v2/collections#rule-evaluation)
Rule Evaluation
The `CollectionProductsQuery` class handles rule evaluation for all supported rules:
| Rule | Column/Relation | Supported Operators |
| --- | --- | --- |
| `ProductTitle` | `name` | All string operators |
| `ProductPrice` | `amount` (prices table) | Numeric operators |
| `CompareAtPrice` | `compare_amount` (prices table) | Numeric operators |
| `InventoryStock` | `inventoryHistories` | Numeric operators |
| `ProductBrand` | `brand` relation | All string operators |
| `ProductCategory` | `categories` relation | All string operators |
| `ProductCreatedAt` | `created_at` | `equals_to`, `less_than`, `greater_than` |
| `ProductFeatured` | `featured` | `equals_to` |
| `ProductRating` | `ratings` relation (AVG) | Numeric operators |
| `ProductSalesCount` | `order_items` (SUM quantity) | Numeric operators |
use Shopper\Core\Queries\CollectionProductsQuery;
$query = new CollectionProductsQuery();
$products = $query->get($collection);
For further customization, use the query builder:
$builder = $query->query($collection);
$products = $builder->with('brand')->paginate(10);
[](https://docs.laravelshopper.dev/v2/collections#automatic-synchronization)
Automatic Synchronization
----------------------------------------------------------------------------------------------------------
For automatic collections, Shopper keeps the product associations in sync with the collection rules. Products are stored in the pivot table for optimal query performance.
###
[](https://docs.laravelshopper.dev/v2/collections#how-sync-works)
How Sync Works
Synchronization happens automatically via observers:
| Event | Action |
| --- | --- |
| Product created/updated | Product is added/removed from matching collections |
| Collection saved | All matching products are synced |
| Collection rule added/updated/deleted | Collection products are re-synced |
###
[](https://docs.laravelshopper.dev/v2/collections#manual-sync-command)
Manual Sync Command
You can manually sync automatic collections using the artisan command:
# Sync all automatic collections
php artisan shopper:collections:sync
# Sync a specific collection
php artisan shopper:collections:sync --collection=1
###
[](https://docs.laravelshopper.dev/v2/collections#sync-action)
Sync Action
For programmatic sync, use the `SyncCollectionProductsAction`:
use Shopper\Core\Actions\SyncCollectionProductsAction;
use Shopper\Models\Collection;
$collection = Collection::query()->find($id);
$action = new SyncCollectionProductsAction();
$syncedCount = $action->execute($collection);
###
[](https://docs.laravelshopper.dev/v2/collections#background-jobs)
Background Jobs
Sync operations run in queued jobs to avoid blocking requests:
* `SyncCollectionProductsJob` - Syncs a single collection
* `SyncProductWithCollectionsJob` - Syncs a product with all automatic collections
Configure your queue worker to process these jobs:
php artisan queue:work
[](https://docs.laravelshopper.dev/v2/collections#media)
Media
------------------------------------------------------------------
Collections support two media collections through [Spatie MediaLibrary](https://spatie.be/docs/laravel-medialibrary)
, using the same config-driven collection names as [products](https://docs.laravelshopper.dev/v2/products#media)
.
| Collection | Config key | Behavior | Description |
| --- | --- | --- | --- |
| Default gallery | `shopper.media.storage.collection_name` | Multiple files | Collection images |
| Thumbnail | `shopper.media.storage.thumbnail_collection` | Single file | Collection cover image |
To add a collection cover image:
$mediaCollection = config('shopper.media.storage.thumbnail_collection');
$collection->addMedia($file)->toMediaCollection($mediaCollection);
To retrieve the cover URL:
$mediaCollection = config('shopper.media.storage.thumbnail_collection');
$url = $collection->getFirstMediaUrl($mediaCollection, 'medium');
[](https://docs.laravelshopper.dev/v2/collections#configuration)
Configuration
----------------------------------------------------------------------------------
###
[](https://docs.laravelshopper.dev/v2/collections#disabling-collections)
Disabling Collections
// config/shopper/features.php
use Shopper\Enum\FeatureState;
return [\
'collection' => FeatureState::Disabled,\
];
###
[](https://docs.laravelshopper.dev/v2/collections#permissions)
Permissions
The admin panel generates five permissions for collection management:
| Permission | Description |
| --- | --- |
| `browse_collections` | View the collections list |
| `read_collections` | View a single collection |
| `add_collections` | Create new collections |
| `edit_collections` | Edit existing collections |
| `delete_collections` | Delete collections |
[](https://docs.laravelshopper.dev/v2/collections#components)
Components
----------------------------------------------------------------------------
To customize the admin UI for collection management:
php artisan shopper:component:publish collection
Creates `config/shopper/components/collection.php`:
use Shopper\Livewire;
return [\
'pages' => [\
'collection-index' => Livewire\Pages\Collection\Index::class,\
'collection-edit' => Livewire\Pages\Collection\Edit::class,\
],\
'components' => [\
'collections.products' => Livewire\Components\Collection\CollectionProducts::class,\
\
'slide-overs.collection-rules' => Livewire\SlideOvers\CollectionRules::class,\
'slide-overs.add-collection-form' => Livewire\SlideOvers\AddCollectionForm::class,\
'slide-overs.collection-products-list' => Livewire\SlideOvers\CollectionProductsList::class,\
],\
];
[](https://docs.laravelshopper.dev/v2/collections#storefront-example)
Storefront Example
--------------------------------------------------------------------------------------------
namespace App\Http\Controllers;
use Shopper\Models\Collection;
class CollectionController extends Controller
{
public function index()
{
$collections = Collection::query()
->published()
->withCount('products')
->get();
return view('collections.index', compact('collections'));
}
public function show(string $slug)
{
$collection = Collection::findBySlug($slug);
// Works for both manual and automatic collections
$products = $collection->productsQuery()
->with(['brand', 'media'])
->paginate(12);
return view('collections.show', compact('collection', 'products'));
}
}
[](https://docs.laravelshopper.dev/v2/collections#use-cases)
Use Cases
--------------------------------------------------------------------------
| Type | Example | Description |
| --- | --- | --- |
| Manual | Gift Guides | Curated selection of gift ideas |
| Manual | Editor’s Picks | Hand-picked featured products |
| Auto | New Arrivals | `ProductCreatedAt` greater than 30 days ago |
| Auto | Sale Items | `CompareAtPrice` greater than 0 |
| Auto | Low Stock | `InventoryStock` less than 5 |
| Auto | Featured | `ProductFeatured` equals 1 |
| Auto | Best Sellers | `ProductSalesCount` greater than 10 |
| Auto | Top Rated | `ProductRating` greater than 3 |
[Categories](https://docs.laravelshopper.dev/v2/categories)
[Attributes](https://docs.laravelshopper.dev/v2/attributes)
⌘I
---
# Card - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v2/extending/components/card#content-area)
The Card component is the primary container used throughout Shopper to group related content. It provides a consistent visual treatment with a subtle border and background.
[](https://docs.laravelshopper.dev/v2/extending/components/card#preview)
Preview
------------------------------------------------------------------------------------
Card TitleThis is a description that explains what this card contains.
Your content goes here. This could be forms, tables, or any other content.
[](https://docs.laravelshopper.dev/v2/extending/components/card#usage)
Usage
--------------------------------------------------------------------------------
@if ($icon)
@if ($title)
{{ $title }}
@endif{{ $message }}
Your content goes here
A simple card without title or description.
Display product details in an organized manner.
Custom Title
Card content with custom header.
twMerge(['class' => 'sh-card p-1.5 bg-gray-50 dark:bg-gray-950 rounded-lg ring-1 ring-gray-200 dark:ring-white/10 overflow-hidden']) }}
>
@if ($title)
@if ($title instanceof \Illuminate\View\ComponentSlot)
{{ $title }}
@else
@endif
[Overview](https://docs.laravelshopper.dev/v2/extending/components/overview)
[Alert](https://docs.laravelshopper.dev/v2/extending/components/alert)
⌘I
---
# Demo Store - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v2/demo-store#content-area)
The official Shopper demo is a complete e-commerce application with a storefront and admin panel. It covers product browsing, variant selection, multi-step checkout, customer accounts, a blog, and multi-zone support with country-based currency switching. The full source code is [available on GitHub](https://github.com/shopperlabs/demo.laravelshopper.dev)
.
Visit the live demo
-------------------
Browse the storefront and explore the admin panel at demo.laravelshopper.dev
[](https://docs.laravelshopper.dev/v2/demo-store#what%E2%80%99s-included)
What’s Included
---------------------------------------------------------------------------------------------
The demo store covers the full e-commerce experience:
* **Product catalog** with categories, collections, attribute filtering, and search
* **Product pages** with variant selection, image gallery, multi-currency pricing, and reviews
* **Multi-step checkout** with address selection, shipping method, and payment (Stripe, NotchPay, Cash)
* **Customer accounts** with profile management, address book, and order history
* **Blog** with articles, categories, featured images, and rich content
* **Multi-zone support** with country-based currency switching and shipping options
* **Admin panel** at `/cpanel` powered by Shopper with Filament
[](https://docs.laravelshopper.dev/v2/demo-store#key-patterns)
Key Patterns
-------------------------------------------------------------------------------
The demo is designed as a reference implementation. Here are the main patterns you can study in the codebase. **Extending Shopper models** with custom logic. The demo’s `Product` model adds a `HasProductPricing` trait for multi-currency price formatting, and all catalog models (Category, Brand, Collection) are extended in `app/Models/` to show how model swapping works in practice. **Multi-step checkout** built with Livewire. The `CheckoutWizard` component orchestrates three steps (Shipping, Delivery, Payment), each as its own Livewire component under `app/Livewire/Checkout/`. Session state is managed through a dedicated `CheckoutSession` class. **Domain actions** for business logic. Instead of putting logic in controllers, the demo uses Action classes in `app/Actions/` for operations like `CreateOrder`, `AddToCart`, and `ResolveVariantAvailability`. Each action has a single responsibility and is easy to test. **Extending the admin sidebar.** The demo adds a Blog section to Shopper’s admin panel through `app/Sidebar/BlogSidebar.php`, with custom Livewire pages for managing posts and categories under `app/Livewire/Shopper/Blog/`. **Multi-currency pricing** via shipping zones. The `ZoneSessionManager` action and `ZoneSelector` slide-over component handle country-based currency switching. The `HasProductPricing` trait on the Product model formats prices based on the active zone’s currency. **Payment gateway integration** with multiple providers. The checkout supports Stripe (with webhooks via `StripeWebhookController`), NotchPay, and Cash on Delivery, configured through `config/shopper/payment.php`. **Feature toggling.** The demo disables the Suppliers feature in `config/shopper/features.php` to show that you can turn off any part of Shopper you don’t need.
[](https://docs.laravelshopper.dev/v2/demo-store#admin-panel-access)
Admin Panel Access
-------------------------------------------------------------------------------------------
You can log in to the admin panel at [`/cpanel`](https://demo.laravelshopper.dev/cpanel)
:
* **Email:** `admin@laravelshopper.dev`
* **Password:** `demo.Shopper@2026!`
The demo database is reset periodically. Please be respectful when editing data.
[](https://docs.laravelshopper.dev/v2/demo-store#source-code)
Source Code
-----------------------------------------------------------------------------
The full source code is available on GitHub. You can clone it and run it locally to explore the codebase, modify it, or use it as a starting point for your own store.
GitHub Repository
-----------------
Browse the source code on GitHub
To run the demo locally, clone the repository and run the setup command. This handles environment configuration, database migrations, and seeding with demo data.
git clone https://github.com/shopperlabs/demo.laravelshopper.dev.git shopper-demo && cd shopper-demo
composer install
npm install && npm run build
composer setup
Then access the storefront at the URL provided by your local server. The storefront is built with Livewire 3, Volt, and Flux UI, styled with Tailwind CSS 4. The production deployment uses Docker with FrankenPHP (Octane).
[Introduction](https://docs.laravelshopper.dev/v2/getting-started)
[Contribution Guide](https://docs.laravelshopper.dev/v2/contributing)
⌘I
---
# Customers - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v2/customers#content-area)
Customers are users who have the customer role and can place orders in your store. Shopper extends your Laravel User model with e-commerce specific fields and relationships.
[](https://docs.laravelshopper.dev/v2/customers#user-model-integration)
User Model Integration
--------------------------------------------------------------------------------------------------
Shopper doesn’t create a separate Customer model. Instead, it extends your existing `App\Models\User` model with the `InteractsWithShopper` trait and `ShopperUser` contract.
namespace App\Models;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Shopper\Models\Contracts\ShopperUser;
use Shopper\Traits\InteractsWithShopper;
class User extends Authenticatable implements ShopperUser
{
use InteractsWithShopper;
}
The `InteractsWithShopper` trait provides:
* `HasRoles` (Spatie Permission) for role-based access control
* `HasDiscounts` for customer-specific discount eligibility
* `HasProfilePhoto` for avatar management
[](https://docs.laravelshopper.dev/v2/customers#database-schema)
Database Schema
------------------------------------------------------------------------------------
###
[](https://docs.laravelshopper.dev/v2/customers#user-table-modifications)
User Table Modifications
Shopper modifies the standard Laravel `users` table:
| Column | Type | Nullable | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | bigint | no | auto | Primary key |
| `first_name` | string | yes | null | First name |
| `last_name` | string | no | \- | Last name |
| `email` | string | no | \- | Email address (unique) |
| `password` | string | yes | null | Password (nullable for social auth) |
| `email_verified_at` | timestamp | yes | null | Email verification date |
| `gender` | string | yes | null | Gender enum value |
| `phone_number` | string | yes | null | Phone number |
| `birth_date` | date | yes | null | Birth date |
| `avatar_type` | string | no | avatar\_ui | Avatar source type |
| `avatar_location` | string | yes | null | Avatar file path |
| `timezone` | string | yes | null | User timezone |
| `opt_in` | boolean | no | false | Marketing email consent |
| `last_login_at` | timestamp | yes | null | Last login timestamp |
| `last_login_ip` | string | yes | null | Last login IP address |
###
[](https://docs.laravelshopper.dev/v2/customers#address-table)
Address Table
| Column | Type | Nullable | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | bigint | no | auto | Primary key |
| `first_name` | string | no | \- | First name |
| `last_name` | string | no | \- | Last name |
| `company_name` | string | yes | null | Company name |
| `street_address` | string | no | \- | Street address |
| `street_address_plus` | string | yes | null | Additional address line |
| `postal_code` | string | no | \- | Postal/ZIP code |
| `city` | string | no | \- | City |
| `state` | string | yes | null | State/province/region |
| `phone_number` | string | yes | null | Phone number |
| `shipping_default` | boolean | no | false | Default shipping address |
| `billing_default` | boolean | no | false | Default billing address |
| `type` | string | yes | null | Address type enum |
| `country_id` | bigint | yes | null | FK to countries |
| `user_id` | bigint | no | \- | FK to users |
[](https://docs.laravelshopper.dev/v2/customers#gender-type)
Gender Type
----------------------------------------------------------------------------
The `GenderType` enum defines available gender options:
use Shopper\Core\Enum\GenderType;
GenderType::Male // male
GenderType::Female // female
[](https://docs.laravelshopper.dev/v2/customers#address-type)
Address Type
------------------------------------------------------------------------------
The `AddressType` enum defines address categories:
use Shopper\Core\Enum\AddressType;
AddressType::Billing // billing
AddressType::Shipping // shipping
[](https://docs.laravelshopper.dev/v2/customers#relationships)
Relationships
--------------------------------------------------------------------------------
###
[](https://docs.laravelshopper.dev/v2/customers#orders)
Orders
// Get all customer orders
$customer->orders; // Collection of Order models
// Get recent orders
$customer->orders()
->latest()
->take(5)
->get();
###
[](https://docs.laravelshopper.dev/v2/customers#addresses)
Addresses
// Get all customer addresses
$customer->addresses; // Collection of Address models
// Get default shipping address
$customer->addresses()
->where('shipping_default', true)
->first();
// Get default billing address
$customer->addresses()
->where('billing_default', true)
->first();
[](https://docs.laravelshopper.dev/v2/customers#query-scopes)
Query Scopes
------------------------------------------------------------------------------
use App\Models\User;
// Get only customers (users with 'user' role)
User::query()->customers()->get();
// Get administrators (admin or manager roles)
User::query()->administrators()->get();
[](https://docs.laravelshopper.dev/v2/customers#role-checking)
Role Checking
--------------------------------------------------------------------------------
// Check if user is an admin
$user->isAdmin();
// Check if user is a manager
$user->isManager();
// Check if email is verified
$user->isVerified();
[](https://docs.laravelshopper.dev/v2/customers#computed-attributes)
Computed Attributes
--------------------------------------------------------------------------------------------
// Get full name
$customer->full_name; // "John Doe"
// Get formatted birth date
$customer->birth_date_formatted; // "15, January 1990"
// Get roles as comma-separated string
$customer->roles_label; // "User, VIP"
// Get profile picture URL
$customer->picture; // Avatar URL (ui-avatars or uploaded)
[](https://docs.laravelshopper.dev/v2/customers#address-model)
Address Model
--------------------------------------------------------------------------------
The model used is `Shopper\Core\Models\Address`. It implements `Shopper\Core\Models\Contracts\Address` and is configurable via `config/shopper/models.php`.
###
[](https://docs.laravelshopper.dev/v2/customers#extending-the-address-model)
Extending the Address Model
namespace App\Models;
use Shopper\Core\Models\Address as BaseAddress;
class Address extends BaseAddress
{
// Add your customizations here
}
Update `config/shopper/models.php`:
return [\
'address' => \App\Models\Address::class,\
];
###
[](https://docs.laravelshopper.dev/v2/customers#address-relationships)
Address Relationships
Each address belongs to a user and optionally to a country:
$address->user; // The customer who owns this address
$address->country; // The Country model (nullable)
###
[](https://docs.laravelshopper.dev/v2/customers#address-methods)
Address Methods
The Address model provides helpers for checking default status:
$address->isShippingDefault(); // true if this is the default shipping address
$address->isBillingDefault(); // true if this is the default billing address
$address->full_name; // "John Doe" (computed from first_name + last_name)
[](https://docs.laravelshopper.dev/v2/customers#creating-customers)
Creating Customers
------------------------------------------------------------------------------------------
###
[](https://docs.laravelshopper.dev/v2/customers#basic-customer)
Basic Customer
use App\Models\User;
use Shopper\Core\Enum\GenderType;
use Illuminate\Support\Facades\Hash;
$customer = User::query()->create([\
'first_name' => 'John',\
'last_name' => 'Doe',\
'email' => 'john@example.com',\
'password' => Hash::make('password'),\
'gender' => GenderType::Male,\
'email_verified_at' => now(),\
]);
// Assign customer role
$customer->assignRole(config('shopper.admin.roles.user'));
###
[](https://docs.laravelshopper.dev/v2/customers#customer-with-address)
Customer with Address
use Shopper\Core\Models\Address;
use Shopper\Core\Enum\AddressType;
$customer = User::query()->create([\
'first_name' => 'Jane',\
'last_name' => 'Doe',\
'email' => 'jane@example.com',\
'gender' => GenderType::Female,\
'phone_number' => '+1234567890',\
'opt_in' => true,\
]);
$customer->assignRole(config('shopper.admin.roles.user'));
// Add shipping address
$customer->addresses()->create([\
'first_name' => 'Jane',\
'last_name' => 'Doe',\
'street_address' => '123 Main Street',\
'city' => 'New York',\
'postal_code' => '10001',\
'country_id' => $countryId,\
'type' => AddressType::Shipping,\
'shipping_default' => true,\
]);
[](https://docs.laravelshopper.dev/v2/customers#retrieving-customers)
Retrieving Customers
----------------------------------------------------------------------------------------------
use App\Models\User;
// Get all customers
$customers = User::query()
->customers()
->latest()
->get();
// Search customers
$customers = User::query()
->customers()
->where(function ($query) use ($search) {
$query->where('first_name', 'like', "%{$search}%")
->orWhere('last_name', 'like', "%{$search}%")
->orWhere('email', 'like', "%{$search}%");
})
->get();
// Get customer with addresses and orders
$customer = User::query()
->with(['addresses', 'orders'])
->findOrFail($id);
// Get customers who opted in for marketing
$marketingList = User::query()
->customers()
->where('opt_in', true)
->get();
// Get verified customers only
$verified = User::query()
->customers()
->whereNotNull('email_verified_at')
->get();
[](https://docs.laravelshopper.dev/v2/customers#managing-addresses)
Managing Addresses
------------------------------------------------------------------------------------------
use Shopper\Core\Models\Address;
// Create address for customer
$address = Address::query()->create([\
'user_id' => $customer->id,\
'first_name' => 'John',\
'last_name' => 'Doe',\
'street_address' => '456 Oak Avenue',\
'city' => 'Los Angeles',\
'postal_code' => '90001',\
'country_id' => $countryId,\
'type' => AddressType::Billing,\
'billing_default' => true,\
]);
// Update default address
Address::query()
->where('user_id', $customer->id)
->where('type', AddressType::Shipping)
->update(['shipping_default' => false]);
$newDefault = Address::query()->find($addressId);
$newDefault->update(['shipping_default' => true]);
[](https://docs.laravelshopper.dev/v2/customers#observer-behavior)
Observer Behavior
----------------------------------------------------------------------------------------
When a user is deleted, the `InteractsWithShopper` trait automatically:
* Detaches all roles
* Deletes all addresses
// When deleting a user:
$customer->delete();
// Roles are detached and addresses are deleted automatically
[](https://docs.laravelshopper.dev/v2/customers#role-configuration)
Role Configuration
------------------------------------------------------------------------------------------
Roles are defined in `config/shopper/admin.php`:
return [\
'roles' => [\
'admin' => 'administrator',\
'manager' => 'manager',\
'user' => 'user',\
],\
];
[](https://docs.laravelshopper.dev/v2/customers#permissions)
Permissions
----------------------------------------------------------------------------
The admin panel generates five permissions for customer management:
| Permission | Description |
| --- | --- |
| `browse_customers` | View the customers list |
| `read_customers` | View a single customer profile |
| `add_customers` | Create new customers |
| `edit_customers` | Edit customer profiles |
| `delete_customers` | Delete or anonymize customers |
[](https://docs.laravelshopper.dev/v2/customers#components)
Components
--------------------------------------------------------------------------
To customize the admin UI for customer management:
php artisan shopper:component:publish customer
Creates `config/shopper/components/customer.php`:
use Shopper\Livewire;
use Shopper\Livewire\Components;
return [\
'pages' => [\
'customer-index' => Livewire\Pages\Customers\Index::class,\
'customer-create' => Livewire\Pages\Customers\Create::class,\
'customer-show' => Livewire\Pages\Customers\Show::class,\
],\
'components' => [\
'customers.addresses' => Components\Customers\Addresses::class,\
'customers.orders' => Components\Customers\Orders::class,\
'customers.profile' => Components\Customers\Profile::class,\
],\
];
[](https://docs.laravelshopper.dev/v2/customers#storefront-example)
Storefront Example
------------------------------------------------------------------------------------------
namespace App\Http\Controllers;
use App\Models\User;
use Shopper\Core\Models\Address;
use Shopper\Core\Enum\GenderType;
use Shopper\Core\Enum\AddressType;
use Illuminate\Support\Facades\Hash;
class AccountController extends Controller
{
public function show()
{
$customer = auth()->user();
return view('account.show', [\
'customer' => $customer,\
'orders' => $customer->orders()->latest()->paginate(10),\
'addresses' => $customer->addresses,\
]);
}
public function updateProfile(Request $request)
{
$validated = $request->validate([\
'first_name' => 'required|string|max:255',\
'last_name' => 'required|string|max:255',\
'phone_number' => 'nullable|string|max:20',\
'birth_date' => 'nullable|date',\
'opt_in' => 'boolean',\
]);
auth()->user()->update($validated);
return back()->with('success', 'Profile updated successfully');
}
public function storeAddress(Request $request)
{
$validated = $request->validate([\
'first_name' => 'required|string',\
'last_name' => 'required|string',\
'street_address' => 'required|string',\
'city' => 'required|string',\
'postal_code' => 'required|string',\
'country_id' => 'required|exists:countries,id',\
'type' => 'required|in:billing,shipping',\
]);
auth()->user()->addresses()->create([\
...$validated,\
'type' => AddressType::from($validated['type']),\
]);
return back()->with('success', 'Address added successfully');
}
}
[](https://docs.laravelshopper.dev/v2/customers#use-cases)
Use Cases
------------------------------------------------------------------------
| Scope | Description |
| --- | --- |
| `customers()` | Users with ‘user’ role |
| `administrators()` | Users with ‘admin’ or ‘manager’ role |
| Method | Description |
| --- | --- |
| `isAdmin()` | Check if user has admin role |
| `isManager()` | Check if user has manager role |
| `isVerified()` | Check if email is verified |
[Reviews](https://docs.laravelshopper.dev/v2/reviews)
[Cart](https://docs.laravelshopper.dev/v2/cart)
⌘I
---
# Dashboard - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v2/dashboard#content-area)
The dashboard is the first screen after login. It shows store health at a glance: revenue trends, key metrics, recent orders, top products, and an onboarding guide that auto-dismisses once the store is configured.
[](https://docs.laravelshopper.dev/v2/dashboard#components)
Components
--------------------------------------------------------------------------
The dashboard is composed of five Livewire components, each with independent caching and a focused responsibility.
###
[](https://docs.laravelshopper.dev/v2/dashboard#revenuechart)
RevenueChart
Displays monthly revenue as a bar chart for the last 12 months. Data is grouped by month in a single aggregated query and cached with flexible TTL (fresh for 5 minutes, stale up to 30 minutes). The chart supports a currency filter. When you have multiple active currencies, a dropdown lets you switch between them. The Y-axis and tooltip are formatted using `Intl.NumberFormat` with the store’s locale and currency symbol. The revenue query supports MySQL, PostgreSQL, and SQLite with database-specific date expressions.
###
[](https://docs.laravelshopper.dev/v2/dashboard#statcards)
StatCards
Shows four summary cards comparing the current month to the previous month:
| Card | Metric | Scope |
| --- | --- | --- |
| Revenue | Sum of `price_amount` on paid orders | Current currency |
| Products | Total product count, monthly new products for trend | All types |
| Orders | Count of paid orders, monthly count for trend | All currencies |
| Customers | Count of users with the `customer` scope, monthly new customers for trend | All |
Each card shows the percentage change versus the previous month, with a green or red trend indicator. Cards link to their respective admin sections.
###
[](https://docs.laravelshopper.dev/v2/dashboard#recentorders)
RecentOrders
A table of the 7 most recent orders, excluding orders with Cancelled or Archived status. Each row shows the order number, first product with thumbnail, total amount, payment status badge, and links to the order detail page.
###
[](https://docs.laravelshopper.dev/v2/dashboard#topsellingproducts)
TopSellingProducts
Ranks the top 6 products by total quantity sold across paid orders. Variant sales are aggregated back to the parent product. Each row shows the product thumbnail, name, total units sold, and average review score.
###
[](https://docs.laravelshopper.dev/v2/dashboard#setupguide)
SetupGuide
An interactive checklist that guides new stores through the essential configuration steps. It appears on first login and auto-detects completion by querying the database:
| Step | Completed when | Permission |
| --- | --- | --- |
| Add a product | At least one product exists | `add_products` |
| Create a collection | At least one collection exists | `add_collections` |
| Set up shipping zones | At least one enabled shipping zone exists | `access_setting` |
| Set up payment methods | At least one enabled payment method exists | `access_setting` |
| Configure taxes | At least one tax zone exists | `access_setting` |
When all steps are marked complete, the guide saves a `setup_guide_done` setting and dispatches a `setup-guide-completed` event to hide itself. It does not reappear on subsequent visits. The guide can also be dismissed early with the dismiss button.
[](https://docs.laravelshopper.dev/v2/dashboard#caching)
Caching
--------------------------------------------------------------------
Each dashboard component caches its data independently. The cache keys and TTLs are:
| Component | Cache key | Fresh TTL | Stale TTL |
| --- | --- | --- | --- |
| RevenueChart | `dashboard:revenue:{currency}` | 5 min | 30 min |
| StatCards | `dashboard:stat-cards:{locale}` | 5 min | 30 min |
| RecentOrders | `dashboard:recent-orders` | 1 min | 5 min |
| TopSellingProducts | `dashboard:top-selling-products` | 5 min | 30 min |
To clear the dashboard cache manually (for example after a data import), flush the keys:
use Illuminate\Support\Facades\Cache;
Cache::forget('dashboard:revenue:USD');
Cache::forget('dashboard:stat-cards:en');
Cache::forget('dashboard:recent-orders');
Cache::forget('dashboard:top-selling-products');
[](https://docs.laravelshopper.dev/v2/dashboard#access-requirements)
Access Requirements
--------------------------------------------------------------------------------------------
The dashboard middleware checks two conditions before rendering the page. The user must be an admin or have the `access_dashboard` permission. The store must have the `email` and `street_address` settings configured (these are set during the initial store setup). If the settings are missing, the middleware redirects to the store initialization page. If the user lacks permission, a 403 response is returned.
[](https://docs.laravelshopper.dev/v2/dashboard#customizing-the-dashboard)
Customizing the Dashboard
--------------------------------------------------------------------------------------------------------
###
[](https://docs.laravelshopper.dev/v2/dashboard#replacing-the-entire-page)
Replacing the Entire Page
The dashboard page is registered in the components configuration. Publish the dashboard component config to swap it with your own implementation:
php artisan shopper:component:publish dashboard
This creates `config/shopper/components/dashboard.php`:
use Shopper\Livewire\Components;
use Shopper\Livewire\Pages;
return [\
'pages' => [\
'dashboard' => Pages\Dashboard::class,\
],\
'components' => [\
'locale-switcher' => Components\LocaleSwitcher::class,\
],\
];
Replace the page class with your own component:
'pages' => [\
'dashboard' => App\Livewire\Pages\Dashboard::class,\
],
Your component only needs to render a view with the app layout. The simplest override:
namespace App\Livewire\Pages;
use Illuminate\Contracts\View\View;
use Livewire\Component;
final class Dashboard extends Component
{
public function render(): View
{
return view('dashboard.index')
->layout('shopper::components.layouts.app', [\
'title' => 'Dashboard',\
]);
}
}
###
[](https://docs.laravelshopper.dev/v2/dashboard#overriding-individual-components)
Overriding Individual Components
If you want to replace a single widget (for example, swap the revenue chart for a custom report), publish the dashboard Blade view and edit it directly. First, publish Shopper’s views:
php artisan vendor:publish --tag=shopper-views
Then open `resources/views/vendor/shopper/livewire/pages/dashboard.blade.php`. The view renders each component via Livewire tags that you can replace:
{{ $slot }}
twMerge(['class' => 'flex flex-col items-center justify-center px-8 py-10 text-center']) }}
>
@if ($icon)
[Empty State](https://docs.laravelshopper.dev/v2/extending/components/empty-state)
[Stock Badge](https://docs.laravelshopper.dev/v2/extending/components/stock-badge)
⌘I
---
# Empty State - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v2/extending/components/empty-state#content-area)
The Empty State component is used to display a helpful message when there’s no data to show. It combines an illustration, title, description, and an optional call-to-action button.
[](https://docs.laravelshopper.dev/v2/extending/components/empty-state#preview)
Preview
-------------------------------------------------------------------------------------------
No products yetGet started by creating your first product. Products are the items you sell in your store.Create Product
[](https://docs.laravelshopper.dev/v2/extending/components/empty-state#usage)
Usage
---------------------------------------------------------------------------------------
@svg($icon, 'size-5', ['aria-hidden' => 'true'])
@endif
$icon])> {{ $heading }}
@if ($description){{ $description }}
@endif @if ($action)
{{ $action }}
@endif
 }}){kind=spacer}
 }}){kind=spacer}
 }}){kind=spacer}
 }}){kind=spacer}
 }}){kind=spacer}
twMerge(['class' => 'relative w-full lg:flex lg:items-center py-8 lg:py-12']) }}
>
{{ $button }}
@elseif ($panel)
{{ $button }}
@endif
@endcan
@endif
[Section Heading](https://docs.laravelshopper.dev/v2/extending/components/section-heading)
[Empty Card](https://docs.laravelshopper.dev/v2/extending/components/empty-card)
⌘I
---
# Heading - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v2/extending/components/heading#content-area)
The Heading component is used for main page titles. It displays a large, bold heading with an optional action slot for buttons or other controls.
[](https://docs.laravelshopper.dev/v2/extending/components/heading#preview)
Preview
---------------------------------------------------------------------------------------
Products
Add Product
[](https://docs.laravelshopper.dev/v2/extending/components/heading#usage)
Usage
-----------------------------------------------------------------------------------
{{ $slot }}
{{ $title }}
{{ $content }}
@if ($permission) @can($permission) @if ($url)
Product: iPhone 15
Published
twMerge(['class' => 'space-y-3 sm:flex sm:items-center sm:justify-between sm:space-x-4 sm:space-y-0']) }}
>
@if ($title instanceof \Illuminate\View\ComponentSlot)
{{ $title }}
@else
[Alert](https://docs.laravelshopper.dev/v2/extending/components/alert)
[Section Heading](https://docs.laravelshopper.dev/v2/extending/components/section-heading)
⌘I
---
# Empty State - TALL Stack E-commerce Framework
> Documentation Index
> -------------------
>
> Fetch the complete documentation index at: [/llms.txt](https://docs.laravelshopper.dev/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](https://docs.laravelshopper.dev/v2/extending/empty-state#content-area)
[](https://docs.laravelshopper.dev/v2/extending/empty-state#empty-state)
Empty State
========================================================================================
⌘I
---