> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laravelshopper.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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                                                 |
| -------------- | ------- | ------------------------------------------------------- |
| `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`).

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

```php config/shopper/admin.php theme={null}
'prefix' => env('SHOPPER_PREFIX', 'cpanel'),
```

<Tip>
  If you change the prefix, run `php artisan shopper:link` to recreate the asset symlink with the new name.
</Tip>

To bind the admin panel to a specific domain, set the `SHOPPER_DOMAIN` environment variable. This uses Laravel's `Route::domain()` under the hood:

```php config/shopper/admin.php theme={null}
'domain' => env('SHOPPER_DOMAIN'),
```

You can also customize the admin panel branding (logo, favicon, and Filament primary color):

```php config/shopper/admin.php theme={null}
'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.

### Avatar Colors

Default colors for auto-generated user avatars (UI Avatars). Values are hexadecimal without the `#` prefix:

```php config/shopper/admin.php theme={null}
'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:

```php config/shopper/admin.php theme={null}
'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:

```php config/shopper/admin.php theme={null}
'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.

```php config/shopper/core.php theme={null}
'table_prefix' => 'sh_',
```

<Warning>
  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.
</Warning>

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

```php config/shopper/features.php theme={null}
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.

```php config/shopper/models.php theme={null}
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](/v2/getting-started) 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:

```php config/shopper/auth.php theme={null}
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](/v2/two-factor) 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:

```php config/shopper/routes.php theme={null}
'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:

```php config/shopper/routes.php theme={null}
'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:

```bash theme={null}
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).

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

```php config/shopper/settings.php theme={null}
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:

```php theme={null}
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:

```php theme={null}
'items' => [
    App\Settings\MyCustomSetting::class => true,
],
```

### Programmatic Registration

You can also register settings at runtime through the `SettingManager`:

```php theme={null}
use Shopper\Settings\SettingManager;

app(SettingManager::class)->add(App\Settings\MyCustomSetting::class);
```

<Warning>
  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.
</Warning>

## Order Number Format

The `orders.php` config controls how order numbers are generated. You can customize the prefix, separator, date format, and sequence padding:

```php config/shopper/orders.php theme={null}
'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`              |