Nova Settings Tool Laravel Package

Getting Started

1. Install the package in a Laravel app that already runs Nova (this is a Nova tool, not a standalone package):

   composer require weslal/nova-settings-tool
   

2. Publish and migrate. The tool stores key/value settings in the database, so publish its config and migration, then migrate:

   php artisan vendor:publish --provider="Weslal\NovaSettingsTool\ToolServiceProvider"
   php artisan migrate
   

3. Register the tool in app/Providers/NovaServiceProvider.php inside tools():

   public function tools()
   {
       return [
           new \Weslal\NovaSettingsTool\NovaSettingsTool,
       ];
   }
   

4. Define your settings in code first. The whole point of this package is that settings are declared in code (as groups and fields) and then edited through Nova. Look first at the published config file / the tool's schema definition — that is where you register groups and their fields. A typical definition looks like:

   // config/nova-settings-tool.php
   return [
       'groups' => [
           'general' => [
               'label'    => 'General',
               'settings' => [
                   'site_name'     => ['label' => 'Site Name', 'type' => 'text'],
                   'support_email' => ['label' => 'Support Email', 'type' => 'email'],
               ],
           ],
       ],
   ];
   

   Confirm the exact key names against the package README before committing to a schema — the field-type vocabulary is the part most likely to have shifted across versions.

5. First use case: declare a General group with site_name and support_email, save values in the Nova sidebar, then read them at runtime (see below) to replace a hard-coded config('app.name') or hard-coded support address. That single loop — declare → edit in Nova → read in code — is the core workflow you should validate on day one.

6. Verify runtime access. Find the helper/facade the tool exposes for reads (often something like setting('general.site_name') or a Settings facade). Run it from php artisan tinker before wiring it into controllers or views.

Implementation Patterns

Declare once, edit forever. Treat the code-defined schema as the source of truth and the database as the values store. Group settings by domain (general, mail, social, billing) so the Nova sidebar stays navigable as the app grows.

Centralise reads behind a small wrapper. Even if the package ships a helper, wrap it so you can swap the backend, add caching, and type-cast in one place:

// app/Support/Settings.php
class Settings
{
    public static function get(string $key, $default = null)
    {
        return cache()->rememberForever("setting.{$key}", function () use ($key, $default) {
            return setting($key) ?? $default;
        });
    }
}

Call Settings::get('general.support_email') from controllers, jobs, and mailables instead of reaching into the package directly. This is also the seam for mocking in tests.

Override config at boot. A common pattern is to override framework config from settings in a service provider, so mail or app values become admin-editable:

// AppServiceProvider::boot()
config([
    'mail.from.address' => Settings::get('mail.from_address', config('mail.from.address')),
]);

Guard this carefully in config:cache workflows (see Gotchas).

Group-level access for forms. When rendering a settings page in Blade, pull a whole group in one go and array_merge over defaults to avoid a forest of null checks:

$general = array_merge(config('settings.defaults.general', []), Settings::group('general'));

Authorisation. Settings are global by design, so scope write access explicitly. Either gate the tool with a Nova policy / canSee / canRun on a role, or register the tool only for admins in NovaServiceProvider. Do not assume the tool is admin-only out of the box.

Seeding defaults. Keep a config/settings.defaults.php file and seed the database from it in a seeder or a settings:sync artisan command so fresh environments and CI have deterministic values. Never rely on the Nova UI to bootstrap a new environment.

Testing. In tests, point your wrapper at an in-memory array or override the cache key to avoid hitting the DB. Assert that a setting change updates runtime config where you wired the override.

Environment separation. Because values live in the DB, they don't travel with code. Document which settings are environment-specific (API keys, mail hosts) and which are safe to share between staging and production, and treat environment-specific ones as deploy-time secrets rather than Nova-editable.

Gotchas and Tips

It is effectively unmaintained. The last release is December 2018 (v1.0.3). That predates Nova 4/5 and modern Laravel by years, so assume incompatibility until you prove otherwise. Before adopting: check the package's composer.json constraints, test against your Nova and Laravel versions in a branch, and consider forking to dev-main from the repository if you need a patch. For new projects, weigh this against a maintained alternative or a small bespoke Nova tool.

Pin the version and lock it. If you proceed, pin to at least ^1.0.3 — the release notes mention a fixed middleware bug, and running an earlier patch means shipping a known defect. Commit composer.lock and avoid * constraints.

Migrations vs. your schema. Publishing migrations means the table name and columns become part of your app. Avoid a collision with any existing settings table, and never edit the published migration after it has run in production without a follow-up migration.

Config caching traps. If you override framework config from settings in a provider, remember that php artisan config:cache bakes config before your DB read logic behaves as expected, and reads inside cached config can be stale. Prefer reading settings at request/job time, or document that setting changes require a config rebuild.

Cache invalidation. If you add a cache layer (recommended), clear it when a setting is saved. The package may or may not fire an event you can hook — if it doesn't, add a small model observer or wrap writes in your own service so you control invalidation. A stale setting.general.support_email cache key is the most likely "why didn't my change take effect?" bug you will hit.

Schema changes are deploys, not UI actions. Because fields are declared in code, adding a setting requires a code change and deploy — not just clicking "add field" in Nova, even if older versions exposed an editable field/group UI. Treat the code schema as authoritative and keep the DB as values only; mixing both will cause drift.

Defaults and types. Decide early on null vs empty string vs typed defaults, and enforce casting in your wrapper. An empty support_email is not the same as an unset one, and form fields that submit "" will happily overwrite a sensible default.

Namespacing keys. Prefix keys (general.site_name, mail.from_address) from the start. Flat, unprefixed keys collide as the app grows and make the array_merge-over-defaults pattern impossible.

Debugging reads. When a value "isn't saving," check in order: the DB row (query the table directly), the published config schema (is the field actually declared?), the cache layer, and Nova's canSee/authorisation. Log the query in a local environment if the tool's middleware is involved — the v1.0.3 middleware fix is relevant here.

Extension points. Custom field types and view overrides are where this package earns its keep for admin teams: extend the field-type map for selects, toggles, or file uploads, and publish/override the tool's Vue components if you need richer controls. But every override is a fork commitment on an unmaintained base — keep them minimal and isolated.

Document the runtime API. New team members will not know the helper/facade name or the grouping convention. Put a short section in your README (declare → edit → read) and point to your Settings wrapper as the only sanctioned read path.