Configuration
Configure the admin panel, models, features, and settings in your Shopper installation.
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.
Configuration Files
The following files are published by php artisan shopper:install:
| File | Package | Purpose |
|---|---|---|
addons.php | admin | Disables an installed add-on by its ID |
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 |
The installer also publishes cart.php, payment.php and shipping.php, because shopper/cart, shopper/payment and shopper/shipping are installed with the admin panel. The Stripe driver publishes its own file on demand with php artisan vendor:publish --tag=shopper-stripe-config.
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:
'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:
'domain' => env('SHOPPER_DOMAIN'),You can also customize the admin panel branding (logo, favicon, and Filament primary color):
'brand' => null,
'favicon' => null,
'primary_color' => \Filament\Support\Colors\Color::Blue,brand and favicon take a path from your public directory, such as '/images/logo.svg'. When brand is null, the Shopper logo is shown. To render the logo from your own HTML or Blade view instead, see Branding Logo.
The primary_color key accepts any Filament color constant. Shopper's styles, including a custom theme built from its theme.css, read their primary colors from this value, so you change it here and nowhere else.
The roles key in the same file names the admin, manager and user roles. It is covered on the ACL page.
Avatar Colors
Default colors for auto-generated user avatars (UI Avatars). Values are hexadecimal without the # prefix:
'avatar' => [
'color' => '1d4ed8',
'bg_color' => 'dbeafe',
],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:
'locales' => [
'en' => ['label' => 'English', 'flag' => 'gb'],
'fr' => ['label' => 'Français', 'flag' => 'fr'],
],Custom Pages
The php artisan make:shopper-page command creates a Livewire page for the admin panel: a class that extends Shopper\Livewire\Pages\AbstractPageComponent, which renders it inside the admin panel layout, and its Blade view. These keys set where it writes them:
'pages' => [
'namespace' => 'App\\Livewire\\Shopper',
'view_path' => resource_path('views/livewire/shopper'),
],The command does not register a route: add one in your custom route file.
Icon Picker Cache
The icon picker on the attribute form caches its list of icons. Turn the cache off with cache, or change how long it lasts with duration, which takes any interval Carbon understands:
'icon-picker' => [
'cache' => true,
'duration' => '7 days',
],Database Table Prefix
All Shopper tables are prefixed with sh_ by default so they do not conflict with your application's existing tables.
'table_prefix' => 'sh_',The prefix applies to the tables Shopper creates. The columns Shopper adds to your users table and the roles and permissions tables of spatie/laravel-permission, named in config/permission.php, keep their own names.
Set the table prefix before the Shopper migrations run. Changing it afterwards requires a custom migration that renames every Shopper table.
The file only exists once the installer has published it, so change the prefix in this order:
- Run
php artisan shopper:installand answer no when it asks to run the migrations and seeders. - Change
table_prefixinconfig/shopper/core.php. - Run the migrations and the two seeders the installer would have run:
php artisan migrate
php artisan db:seed --class="Shopper\Core\Database\Seeders\ShopperSeeder"
php artisan db:seed --class="Shopper\Database\Seeders\AuthTableSeeder"Feature Flags
The features.php config controls which sections of the admin panel are active. Set a feature to FeatureState::Disabled to remove its pages and sidebar link from the admin panel, along with its field on the product form for brands, categories, collections, suppliers and tags. Suppliers are disabled by default:
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 and its sidebar link disappear from the admin panel.
To check a flag in your own code, such as a storefront view, call Shopper\Feature::enabled() with the feature key:
@if (\Shopper\Feature::enabled('review'))
<x-product-reviews :product="$product" />
@endifModels
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.
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 page for more details on model swapping and extensibility.
Authentication
The auth.php config controls the authentication guard, two-factor authentication, and password reset flow for the admin panel:
return [
'guard' => 'web',
'2fa_enabled' => env('SHOPPER_ENABLED_TWO_FACTOR', false),
'password_reset' => true,
];guard is the name of a guard defined in your config/auth.php. The admin panel logs users in and checks them with this guard.
Set SHOPPER_ENABLED_TWO_FACTOR=true in your .env file to make two-factor authentication available to admin users. Your user model must also implement Shopper\Contracts\HasStoreAuthentication and Shopper\Contracts\HasStoreAuthenticationRecovery, with the traits listed in Interfaces and Traits. Each user then turns it on from their profile; it is not forced on anyone. See the Two-Factor Authentication page for setup details.
Middleware
Shopper lets you add extra middleware to the admin routes that require a logged-in user: the admin pages, the routes of your custom route file and the routes of add-ons. The login and password reset pages, /cpanel/initialize and /cpanel/forbidden do not get them. This is useful for logging, rate limiting, or custom access control:
'middleware' => [],The admin pages are Livewire components. On the requests a component sends after the page has loaded, Livewire only runs the middleware in its persistent list. If your middleware restricts access, also register it with Livewire::addPersistentMiddleware() in the boot() method of a service provider.
Custom Routes
By default, your web.php routes are not loaded inside the admin panel, and custom_file is null. To add custom routes that share Shopper's authentication middleware, point it to a dedicated route file:
'custom_file' => base_path('routes/shopper.php'),Shopper loads this file inside its own route group: each route gets the admin panel prefix and domain, the shopper. name prefix and the admin panel's middleware, including the middleware key above. The route below answers at /cpanel/settings/loyalty and its name is shopper.settings.loyalty:
use App\Livewire\Shopper\LoyaltySettings;
use Illuminate\Support\Facades\Route;
Route::get('settings/loyalty', LoyaltySettings::class)->name('settings.loyalty');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 categoryThis 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 |
To publish every component config at once, pass --all. Without an argument or --all, the command asks which feature to publish. Add --force to overwrite files you already published.
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:
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 hide a setting from the settings page and from the settings navigation, set its value to false.
Creating a Custom Setting
To add your own card to the settings page, extend the Shopper\Settings\Setting base class. name(), description() and icon() are required. url(), permission() and order() are optional and default to null, null and 0:
namespace App\Settings;
use Shopper\Settings\Setting;
final class LoyaltySetting extends Setting
{
public function name(): string
{
return 'Loyalty program';
}
public function description(): string
{
return 'Set how many points customers earn on each order.';
}
public function icon(): string
{
return 'heroicon-o-gift';
}
public function url(): string
{
return route('shopper.settings.loyalty');
}
public function order(): int
{
return 10;
}
public function permission(): ?string
{
return 'manage_loyalty';
}
}url() returns the address of your settings page, declared in your custom route file. A setting without a URL shows a "Soon" badge. order() sorts the cards; the built-in settings use 1 to 9. permission() shows the card only to users who have that permission, so create it first (see Creating Custom Permissions) and check it in your page component as well, for example with $this->authorize('manage_loyalty') in mount().
Then add it to the items array of config/shopper/settings.php, after the built-in settings:
'items' => [
App\Settings\LoyaltySetting::class => true,
],Programmatic Registration
You can also register settings at runtime through the SettingManager, for example in the boot() method of a service provider:
use Shopper\Settings\SettingManager;
app(SettingManager::class)->add(App\Settings\LoyaltySetting::class);add() takes an optional second argument, false to register the setting disabled. enable() and disable() switch a setting that is already registered, including the built-in ones:
use Shopper\Settings\Items\LegalSetting;
use Shopper\Settings\SettingManager;
app(SettingManager::class)->disable(LegalSetting::class);Disabling a setting item removes its card and its navigation tab, so your team can no longer open it from the admin panel. Make sure your team does not need access to those settings before disabling them.
Order Number Format
The orders.php config controls how order numbers are generated. You can customize the prefix, separator, date format, and sequence padding:
'generator' => [
'prefix' => 'ORD',
'separator' => '-',
'date_format' => 'Ymd',
'start_sequence_from' => 1,
'pad_length' => 6,
'pad_string' => '0',
],The sequence is start_sequence_from plus the ID of the last order, padded on the left with pad_string up to pad_length characters. The parts are joined with separator, and a part set to null is left out.
Shopper generates the number when it creates an order from a cart. If you create orders in your own code, call the generate_number() helper to fill the number column.
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 |
Last updated on
Edit on GitHub