Skip to main content
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:
FilePackagePurpose
admin.phpadminAdmin panel prefix, domain, roles, branding, locales
auth.phpadminAuthentication guard, 2FA toggle, password reset
core.phpcoreDatabase table prefix, barcode type
features.phpadminFeature flags for each admin module
media.phpadminMedia storage, MIME types, max sizes, image conversions
models.phpadminModel class resolution for every Shopper entity
orders.phpcoreOrder number generator format
routes.phpadminAdditional middleware and custom route files
settings.phpadminSettings 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).

​
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 constant. After changing your primary color in your Tailwind config, update this value to keep Filament elements consistent.

​
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',
],

​
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'],
],

​
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'),
],

​
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.

​
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.

​
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 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:
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 page for setup details.

​
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' => [],

​
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.

​
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:
FeatureConfig file
accountcomponents/account.php
brandcomponents/brand.php
categorycomponents/category.php
collectioncomponents/collection.php
customercomponents/customer.php
dashboardcomponents/dashboard.php
discountcomponents/discount.php
ordercomponents/order.php
productcomponents/product.php
reviewcomponents/review.php
settingcomponents/setting.php
You can publish all component configs at once with php artisan shopper:component:publish (no argument).

​
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.

​
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,
],

​
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.

​
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:
ConfigurationResult
DefaultORD-20260328-000001
'prefix' => null20260328-000001
'date_format' => nullORD-000001
'prefix' => null, 'date_format' => null000001