README

A Laravel Nova 5 tool for managing application settings backed by Eloquent models. Each settings page is a Nova tool with its own fields, validation, and authorization rules.

Why This Package?

Laravel Nova ships with Resources for CRUD, but it does not provide a first-class way to build settings pages — screens where you edit configuration, profiles, or single-row application data without treating them as a full resource index.

If you needed that before, the usual workaround looked like this:

• Register a custom Tool with your own routes
• Build a Blade or Vue page from scratch inside Nova
• Write a plain controller for load/save logic
• Re-implement forms, validation, panels, and UI by hand

Nova field types (Text, Boolean, Select, Password, Repeater, and the rest) were not available on those custom pages. You either duplicated Nova’s UI or ended up with something that did not feel like the rest of the admin panel.

Nova Settings closes that gap. You define settings the same way you define a resource:

• Declare Nova fields in a fields() method
• Use validation rules, panels, and authorization (canSee, Gates)
• Get Nova’s standard form UI, loading states, and error handling
• Register as many settings pages as you need — payment gateway, admin panel, two-factor policy, user profile, and more

In short: settings pages behave like Resources, but for configuration and single-record forms instead of index/detail tables.

Screenshots

Profile

Per-user settings backed by the authenticated user's model — avatar, name, email, and password.

Payment Gateway

Application-wide settings stored in a single shared row — driver, credentials, and sandbox mode.

Two-Factor Authentication

Boolean toggles for enabling 2FA, enforcing it globally, and choosing allowed methods.

Admin Panel

Global admin options such as panel name, locale, timezone, and maintenance mode.

Requirements

• PHP 8.2+
• Laravel 11, 12, or 13
• Laravel Nova 5

Installation

composer require omiddev32/nova-settings

Publish configuration (optional):

php artisan vendor:publish --tag=nova-settings-config

Register your settings classes in app/Providers/NovaServiceProvider.php:

public function tools(): array
{
    return [
        new \App\Nova\Settings\Profile,
        new \App\Nova\Settings\PaymentGateway,
    ];
}

Route caching

This package registers its routes only when Laravel's route cache is not active. If your application uses php artisan route:cache in production, rebuild the cache after installing or updating the package so the settings routes are included:

php artisan route:cache

During local development, clear the route cache if settings pages return 404:

php artisan route:clear

How It Works

Each settings page:

1. Extends OmidDev32\NovaSettings\Settings
2. Points to an Eloquent model via $model
3. Defines Nova fields in fields()
4. Appears in the Nova sidebar and is available at /nova/settings/{uri-key}

Data is loaded and saved through:

• GET /nova-api/settings/{page} — load fields
• POST /nova-api/settings/{page} — save fields

Settings Types

Application settings (shared)

Use a single-row table (usually id = 1) for settings that apply to the whole application, such as payment gateways, admin panel options, or security policies.

<?php

namespace App\Nova\Settings;

use App\Models\PaymentGatewaySetting;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Gate;
use Laravel\Nova\Fields\Boolean;
use Laravel\Nova\Fields\Select;
use Laravel\Nova\Fields\Text;
use Laravel\Nova\Fields\URL;
use OmidDev32\NovaSettings\Settings;

class PaymentGateway extends Settings
{
    public $model = PaymentGatewaySetting::class;

    public $primaryValue = 1;

    public string $group = 'Application';

    public function label(): string
    {
        return __('Payment Gateway');
    }

    public function uriKey(string $uri = ''): string
    {
        return $uri ?: 'payment-gateway';
    }

    public function icon(string $icon = 'credit-card'): string
    {
        return $icon;
    }

    public function boot(): void
    {
        $this->canSee(fn ($request) => $request->user() !== null
            && Gate::check('manageApplicationSettings', $request->user()));
    }

    public function fields(Request $request): array
    {
        return [
            Select::make(__('Driver'), 'driver')
                ->options([
                    'stripe' => 'Stripe',
                    'paypal' => 'PayPal',
                    'braintree' => 'Braintree',
                    'square' => 'Square',
                    'adyen' => 'Adyen',
                    'mollie' => 'Mollie',
                ])
                ->displayUsingLabels()
                ->rules('required'),

            Text::make(__('Merchant ID'), 'merchant_id')
                ->rules('nullable', 'max:255'),

            URL::make(__('Callback URL'), 'callback_url')
                ->rules('nullable', 'url', 'max:255'),

            Boolean::make(__('Sandbox Mode'), 'sandbox'),
        ];
    }
}

Create the model and migration:

// app/Models/PaymentGatewaySetting.php
class PaymentGatewaySetting extends Model
{
    protected $fillable = ['driver', 'merchant_id', 'callback_url', 'sandbox'];

    protected function casts(): array
    {
        return ['sandbox' => 'boolean'];
    }
}

Seed one default row (id = 1) in your migration so the settings page always has a record to load.

User settings (per authenticated user)

Use an existing model such as User and resolve the row from the authenticated user. Each person only sees and updates their own data.

<?php

namespace App\Nova\Settings;

use Illuminate\Http\Request;
use Laravel\Nova\Auth\PasswordValidationRules;
use Laravel\Nova\Fields\Gravatar;
use Laravel\Nova\Fields\Password;
use Laravel\Nova\Fields\Text;
use OmidDev32\NovaSettings\Settings;

class Profile extends Settings
{
    use PasswordValidationRules;

    public $model = \App\Models\User::class;

    public string $group = 'Account';

    public function label(): string
    {
        return __('Profile');
    }

    public function uriKey(string $uri = ''): string
    {
        return $uri ?: 'profile';
    }

    public function icon(string $icon = 'user-circle'): string
    {
        return $icon;
    }

    public function boot(): void
    {
        $this->canSee(fn ($request) => $request->user() !== null);
    }

    public function primaryValue()
    {
        return auth()->id();
    }

    public function fields(Request $request): array
    {
        return [
            Gravatar::make()->maxWidth(50),

            Text::make('Name')
                ->rules('required', 'max:255'),

            Text::make('Email')
                ->rules('required', 'email', 'max:254')
                ->updateRules('unique:users,email,{{resourceId}}'),

            Password::make('Password')
                ->onlyOnForms()
                ->updateRules($this->optionalPasswordRules()),
        ];
    }
}

{{resourceId}} in validation rules is replaced automatically with the model primary key when saving.

Reusable base class for application settings

If you have several shared settings pages, extract the common logic:

<?php

namespace App\Nova\Settings;

use Illuminate\Support\Facades\Gate;
use OmidDev32\NovaSettings\Settings;

abstract class ApplicationSettings extends Settings
{
    public $primaryValue = 1;

    public string $group = 'Application';

    public function boot(): void
    {
        $this->canSee(fn ($request) => $request->user() !== null
            && Gate::check('manageApplicationSettings', $request->user()));
    }
}

Then extend it:

class AdminPanel extends ApplicationSettings
{
    public $model = AdminPanelSetting::class;

    // ...
}

Define the gate in NovaServiceProvider:

protected function gate(): void
{
    Gate::define('manageApplicationSettings', function (User $user) {
        return in_array($user->email, [
            'admin@example.com',
        ]);
    });
}

Generating a Settings Class

php artisan make:nova-settings GeneralSettings --model="App\\Models\\GeneralSetting"

Options:

Option	Default	Description
--namespace=	App\Nova\Settings	Namespace for the generated class
--path=	app/Nova/Settings	Output directory
--model=	—	Eloquent model class

Customization

URI key

By default, the URI key is the plural kebab-case class name (PaymentGateway → payment-gateways). Override it when you prefer a fixed path:

public function uriKey(string $uri = ''): string
{
    return $uri ?: 'payment-gateway';
}

Breadcrumb group

Set $group to organize breadcrumbs:

public string $group = 'Application';

Save hooks

use Laravel\Nova\Http\Requests\NovaRequest;
use Illuminate\Database\Eloquent\Model;

public static function beforeSave(NovaRequest $request, Model $model): void
{
    // ...
}

public static function afterSave(NovaRequest $request, Model $model): void
{
    // ...
}

Labels and messages

public function saveButtonLabel(): ?string
{
    return __('Save Payment Settings');
}

public function saveMessage(): ?string
{
    return __('Payment settings saved.');
}

Configuration

Key	Default	Description
path	app/Nova/Settings	Default output path for make:nova-settings
namespace	App\Nova\Settings	Default namespace for generated classes

Artisan Commands

Command	Description
make:nova-settings {name}	Create a new settings class

Publish stubs (optional):

php artisan vendor:publish --tag=nova-settings-stubs

Contact

Questions, feedback, or support:

Channel
Email	omid.dev32@gmail.com
Email	oeslami32@gmail.com
Telegram	@omid_es327

License

MIT