Skip to content

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:

FilePackagePurpose
addons.phpadminDisables an installed add-on by its ID
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

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:

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,

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:

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

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:

config/shopper/admin.php
'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:

config/shopper/admin.php
'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.

config/shopper/core.php
'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:

  1. Run php artisan shopper:install and answer no when it asks to run the migrations and seeders.
  2. Change table_prefix in config/shopper/core.php.
  3. 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:

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 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" />
@endif

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' => 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:

config/shopper/routes.php
'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:

config/shopper/routes.php
'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:

routes/shopper.php
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 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

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:

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 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:

config/shopper/settings.php
'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:

config/shopper/orders.php
'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:

ConfigurationResult
DefaultORD-20260328-000001
'prefix' => null20260328-000001
'date_format' => nullORD-000001
'prefix' => null, 'date_format' => null000001

Last updated on

Edit on GitHub