Laravel Eloquent Settings Laravel Package

Getting Started

Start by confirming you are on v0.2.0 or later if you are running Laravel 11 — this release is primarily a compatibility release, and earlier 0.1.x versions should be treated as Laravel 10-and-below only.

1. Install the package:

   composer require a1383n/laravel-eloquent-settings
   

2. Publish and run the package migration:

   php artisan vendor:publish --tag=eloquent-settings-migrations
   php artisan migrate
   

   If the package provides a config file, publish it too:

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

3. Look first at:
   • the package README for the exact facade/helper/trait names,
   • the published migration to see the settings table shape,
   • the package service provider for bindings and config keys,
   • the Settings model or trait namespace if you need to extend behavior.

The first practical use case is application-wide configuration that should live in the database rather than in .env: site name, support email, feature flags, maintenance-mode messages, or per-tenant defaults. A typical flow is to seed sensible defaults, read them through the package’s API, and update them from an admin panel. If the package exposes a model trait, the second use case is attaching settings directly to Eloquent models — for example, per-user notification preferences or per-team branding — without adding a wide column set to every table.

Implementation Patterns

Wrap package calls in your own settings service. Avoid scattering the package’s get/set calls across controllers and Blade templates. Create a small App\Services\SettingsService that centralizes keys, defaults, casting, and cache invalidation. This makes it much easier to swap storage later and keeps tests readable.

class SettingsService
{
    public function get(string $key, mixed $default = null): mixed
    {
        return Setting::get($key, $default);
    }

    public function set(string $key, mixed $value): void
    {
        Setting::set($key, $value);
        Cache::forget("settings.{$key}");
    }
}

Seed defaults explicitly. Treat the settings table as part of your application schema. A seeder that inserts default values makes local setup and CI deterministic, and it documents which keys are valid.

Setting::set('site.name', config('app.name'));
Setting::set('features.registration', true);

Use typed keys and casts. Settings tables usually store strings or JSON. Decide early whether booleans, arrays, and integers are JSON-encoded or stored as strings, and encode/decode consistently in your service layer. If the package supports casts, prefer them; otherwise add casts in your own wrapper.

Use it for runtime overrides, not bootstrap config. Database settings are convenient for values that change without a deploy. Do not use them for values needed before the database is available — service provider registration, queue connection selection, or anything read during config:cache. Read settings in middleware, controllers, jobs, or view composers instead.

Per-model settings pattern. If the package exposes a HasSettings trait, add it to models that need scoped settings and ensure the migration includes the polymorphic columns or foreign key the package expects. Keep the trait on models with a clear ownership boundary; avoid attaching settings to every model “just in case.”

class Team extends Model
{
    use HasSettings;
}

$team->setSetting('billing.currency', 'EUR');
$currency = $team->getSetting('billing.currency', 'USD');

Check the exact method names in the README — the package’s API may differ.

Feature flags and admin panels. A common workflow is to expose a small settings screen backed by a form request with validation rules per key, then update through your service. Pair this with an audit log or model events if settings affect billing or access control. If the package dispatches events on save, listen to them to clear caches or notify other systems.

Testing pattern. Use RefreshDatabase, seed the settings your test needs, and clear any package cache in setUp or between tests. Because settings are global state, tests can leak values into each other if you do not reset the table or cache.

protected function setUp(): void
{
    parent::setUp();
    Cache::flush();
    Setting::set('features.registration', false);
}

Integration tips.

• Inject your settings service rather than resolving the package directly in application code.
• Cache frequently read settings, but make invalidation explicit in the setter.
• Use php artisan tinker to inspect stored values and verify casts.
• If the package supports a custom model via config, extend it when you need extra columns such as description or updated_by.

Gotchas and Tips

Laravel 11 requires v0.2.0 or newer. This is the headline change in this release. The dependency and CI bumps are non-runtime changes, and the StyleCI fixes are cosmetic. Pin the package version in composer.json if you support multiple Laravel versions, and test the upgrade path from 0.1.x explicitly in CI.

No breaking API changes are announced in v0.2.0. The release notes do not mention removed methods, renamed config keys, or schema changes. Still, run your existing test suite after upgrading — Laravel 11 compatibility work sometimes touches service provider registration or discovery.

Cache invalidation is the most common production bug. If the package caches settings internally, or if you add your own cache layer, ensure every write path clears the relevant cache keys. A settings change that appears correct in tinker but not in the browser is usually a stale cache or a cached config.

Config caching can hide environment values. If the package config references env() directly, run php artisan config:cache in deployment and verify the resolved values. Laravel 11 tightened some bootstrap behavior; confirm the package service provider does not assume a deferred provider is loaded earlier than it is.

Migration publishing can create duplicates. Publish migrations once and commit them. If you publish again after upgrading, check for duplicate migration files or timestamp collisions. Also inspect indexes on the settings key column — lookups by key should be indexed, especially if you read settings on every request.

Mass assignment and model guards. If you extend the package’s settings model, check its $fillable and $guarded properties. Writing through the package API is safer than Setting::create([...]) unless you control the model.

Concurrency on writes. Settings are often updated from admin screens, and simultaneous writes can overwrite each other. Use updateOrCreate semantics if available, wrap multi-key updates in a transaction, and consider optimistic locking for critical settings.

Debugging checklist.

• Confirm the migration ran and the table exists: php artisan db:show.
• Inspect stored values with php artisan tinker.
• Clear caches after changes: php artisan cache:clear and php artisan config:clear.
• Enable query logging temporarily if a setting read is unexpectedly slow.
• Check the package’s issue tracker for Laravel 11-specific reports if the service provider fails to boot.

Extension points to look for. The most useful customization points are usually the published config file (custom table name, custom model, cache TTL), the settings model itself, and any events fired on save. Prefer configuring these over forking the package — the release cadence here is dependabot-driven, so keeping your changes in application code reduces upgrade friction.