Settings Laravel Package

Getting Started

v1.0.0 is the first stable tag, so treat it as a fresh baseline rather than an upgrade. The release notes contain only a changelog link, so verify behaviour against the README and the published config rather than assuming prior-version parity.

1. Install and publish:

   composer require javaabu/settings
   php artisan vendor:publish --provider="Javaabu\Settings\SettingsServiceProvider"
   php artisan migrate
   

2. Look first at config/settings.php. This is the source of truth — it defines the setting keys, defaults, types, validation rules and grouping used by the admin form and by the read helpers. Read it before reading any other source.
3. If you need internals, the Setting model, the settings service/repository and the settings() helper live under vendor/javaabu/settings/src.
4. Read a value anywhere:

   setting('site.name');            // with default from config
   setting('site.name', 'My App');  // explicit fallback
   settings()->all();               // collection/array of everything
   

First use case: replace hard-coded site identity and toggles (site name, support email, maintenance mode, feature flags) with a single admin-editable settings page, so non-developers can change them without a deploy.

Implementation Patterns

Config-driven definitions. Declare each setting once, with its type, default and validation, then let the package render and persist it:

// config/settings.php
return [
    'site.name' => [
        'type'    => 'text',
        'default' => config('app.name'),
        'rules'   => ['required', 'string', 'max:255'],
        'group'   => 'general',
    ],
    'site.maintenance' => [
        'type'    => 'boolean',
        'default' => false,
        'group'   => 'general',
    ],
];

The same array drives the admin form, the validation on save, and the default returned by setting() — keep it as the only place these values are declared.

Read path in application code. Call the helper or facade directly at the point of use rather than copying values into your own config; the package caches reads, so this is cheap:

if (setting('site.maintenance')) {
    // ...
}

For Blade, {{ setting('site.name') }} is fine. For values used in many requests, resolve once in a view composer or middleware rather than in every partial.

Write path. Prefer the package's own setter/form flow so validation and cache invalidation run:

settings()->set('site.name', $request->input('site_name'));

Build the admin screen by iterating the config groups and rendering an input per type (text, textarea, boolean, select, file). Posting to the package controller gives you validation for free; a hand-rolled controller means you must re-apply the rules yourself.

Boolean and select handling. HTML checkboxes post nothing when unchecked — normalise to false before saving, otherwise you will write null and the config default resurfaces.

Feature flags and progressive rollout. Settings are a lightweight alternative to env vars for runtime toggles; keying them as features.* with boolean type keeps them grouped and visible in the same admin screen.

Testing. Reset between tests, since the cached store persists across a test class:

protected function setUp(): void
{
    parent::setUp();
    // flush the package cache and re-seed any settings your test asserts on
}

Use the array cache driver in phpunit.xml so tests do not leak into your local Redis.

Seeding and deploy. Provide a seeder that writes defaults for keys your code assumes exist, so a fresh environment is not dependent on someone visiting the admin page. Run it in your deploy pipeline after migrate.

Gotchas and Tips

• Stale values after direct DB writes. Editing the settings table with SQL or a seeder bypasses the invalidation. Always go through the setter, or explicitly clear the cache afterwards. "I changed it but the app still shows the old value" is the number one symptom with this package.
• null vs default. A stored null and an absent key can behave differently depending on the lookup. Treat an empty string from a form as "reset to default" deliberately, or you will store empty values that shadow your config defaults.
• Validation only runs on the package's save path. Setting::create()/update() from a script or seeder skips the configured rules. If data integrity matters, validate in the seeder too.
• Precedence confusion. Decide early whether env/config or the database wins for a given key, and document it. Mixing both for the same key produces bugs that only appear in one environment.
• config:cache in production. Your config/settings.php is cached. After changing definitions, you must re-run php artisan config:cache (and clear the settings cache) as part of deploy — otherwise new keys silently never appear.
• Complex values. Arrays and objects should be JSON-encoded on write and cast on read. Cast explicitly rather than relying on the raw string, and remember that "false" is truthy in PHP.
• File and image types need php artisan storage:link plus a correctly configured disk; the DB stores the path, so changing disks later orphans existing values.
• Multi-tenant or per-user settings. The package is global by default. If you need scoping, key-prefix your settings (tenant.{id}.site.name) or bind a custom model/repository through the container rather than forking the package.
• Migration ordering. If your app has its own settings table, rename or namespace before installing — the published migration will collide.
• Extension points worth knowing: the config file (groups, types, rules), the container binding for the settings service (swap in your own cache strategy or repository), and the published views (restyle the admin form without touching vendor code). Keep overrides in app/ and re-publish on major upgrades.
• Debugging. php artisan tinker → setting('your.key') tells you what the app actually resolves; compare against DB::table('settings')->where('key', '...')->first() to see whether the problem is storage or cache.
• Because v1.0.0 is the first tagged release, pin it ("javaabu/settings": "^1.0") and re-read these notes on each minor bump; pre-1.0 users should diff their published config and views against the new stubs before upgrading, as no migration guide is provided in the release notes.