Add Settings Screens to the Admin

Every screen under Settings is described in PHP and rendered by one generic view. You add a screen (or a tab on an existing one) by describing sections, pages and fields — no controller, route or view needed.

The model: section → page → field

SettingsManager::add([...])                       -> one SECTION  = one URL  /admin/settings/{id}
   'pages' => [ [ 'id','name','title','fields'=>[...] ] ]   -> PAGES = tabs of that screen
        'fields' => [ ['type'=>'text', 'name'=>..., ...] ]  -> FIELDS = inputs (storage decided by 'group')
Saved by Admin\SettingsController::update():  validate all rules of the section, then write each field
to the backend chosen by its group, then flush the response cache.

Registering a section

Modules/Testimonials/app/Helpers/TestimonialsSettings.php (excerpt)

SettingsManager::add([
    'id' => 'testimonials',                                  // URL: /admin/settings/testimonials
    'title' => __('testimonials::testimonials.settings.title'),
    'link' => [                                              // sidebar entry
        'id' => 'settings',                                  // parent group (the "Settings" entry)
        'sub_menu' => [
            'id' => 'testimonials-settings',
            'label' => __('testimonials::testimonials.settings.title'),
            'type' => 'testimonials',                        // = the section id
            'priority' => 40,
        ],
    ],
    'pages' => fn (): array => [self::page()],              // a closure = built lazily
]);

Page keys

Fields

Keys common to every field

The 18 field types

Labels are translation keys — or full sentences

Where values go (the group key)

Conditional fields

['type' => 'select', 'id' => 'pg_mode', 'name' => 'pg_mode', 'selected' => setting('pg_mode', 'a'),
 'options' => ['a' => 'Alpha', 'b' => 'Beta'], 'label' => __('pg::s.mode'), 'validation' => ['required', 'in:a,b']],

['type' => 'text', 'id' => 'pg_beta_note', 'name' => 'pg_beta_note', 'label' => __('pg::s.note'),
 'value' => setting('pg_beta_note'),
 'condition' => 'pg_mode',            // the NAME of another field on the same screen
 'conditionValue' => 'b',              // string, list ('smtp,failover' style or array) or true
 'validation' => ['nullable', 'string']],

The wrapper renders data-conditional-name/data-conditional-value (or data-conditional-all for conditions) and admin/assets/js/conditional.js shows or hides the row live as the controlling field changes. Conditions are display-only: validation still applies, so use nullable or required_if:pg_mode,b (the Mail settings do exactly that).

Reading and using settings

setting('testimonials_default_limit', 6);         // helper; second argument is the default
\Akaunting\Setting\Facade::get('key', 'default'); // same thing through the facade

// Writing from your own code
Setting::set('testimonials_default_limit', 12);
Setting::save();
ResponseCacheInvalidator::flush();                // if public pages depend on it

• Settings are loaded from the database once per request (cached in the repository); reading is cheap.
• On a fresh install (before the settings table exists) setting() can throw. Core code guards with config('dotartisan.installed').
• Defaults belong at the call site (setting('key', $default)) and in your config file, so the plugin works before an administrator ever opens the screen.

Recipes

Add a tab to an existing screen

php — inside an AdminBooting listener

SettingsManager::add([
    'id' => 'general',                       // re-use the core section id: pages are appended
    'pages' => fn (): array => [[
        'id' => 'tab-pg-extra',
        'name' => __('pg::s.tab'),
        'title' => __('pg::s.tab_title'),
        'fields' => [[
            'type' => 'text', 'id' => 'pg_extra', 'name' => 'pg_extra',
            'label' => __('pg::s.extra'), 'value' => setting('pg_extra'),
            'validation' => ['nullable', 'string', 'max:20'],
        ]],
    ]],
]);

Let an admin pick a page, a menu or a role

use App\Models\Menu;
use App\Models\Role;

['type' => 'select', 'id' => 'pg_menu', 'name' => 'pg_menu', 'label' => __('pg::s.menu'),
 'selected' => setting('pg_menu'), 'options' => Menu::get(), 'optionKey' => 'id', 'optionValue' => 'name',
 'validation' => ['nullable', 'exists:menus,id']],

['type' => 'select', 'id' => 'pg_roles', 'name' => 'pg_roles', 'label' => __('pg::s.roles'), 'multiple' => true,
 'selected' => (array) setting('pg_roles', []),
 'options' => Role::select(['id', 'name'])->get(), 'optionKey' => 'id', 'optionValue' => 'name',
 'validation' => ['nullable', 'array'], 'itemValidation' => ['integer', 'exists:roles,id']],

For "which CMS page is my Shop page" do not hand-roll a select; use AppPages, which generates the select and keeps the setting key.

Secrets

Settings are stored in clear text in the database and .env. For API keys: use the password type (it only masks the input in the browser; the saved value is still rendered into the page source), restrict the screen with manage settings, never log values, and prefer environment variables set at the server level for production. The AI provider keys use an encrypting store (PageBuilderAiSecretStore); mimic it if you need encryption at rest.

Theme options are settings too

The Theme options screen is a settings section whose pages are generated from the active theme's theme.json (ThemeOptionsSchema::pages()), with every field in group theme. You never register it by hand; add options to theme.json instead — see Theme options and CSS pipeline.

Testing a settings screen

it('stores the testimonials settings', function (): void {
    $user = userWithPermissions(['manage settings']);

    $this->actingAs($user)
        ->get(route('admin.settings', ['type' => 'testimonials']))
        ->assertOk()
        ->assertSee('testimonials_default_limit');

    $this->actingAs($user)
        ->post(route('admin.settings.update', ['type' => 'testimonials']), ['testimonials_default_limit' => 2])
        ->assertRedirect();

    expect((int) setting('testimonials_default_limit'))->toBe(2);
});