Laravel Settings Laravel Package

Getting Started

• Install with Composer and pin a compatible version, then publish the package config/migration and run php artisan migrate. Check the README for the exact provider/tag used by your version:

  composer require unisharp/laravel-settings
  php artisan vendor:publish
  php artisan migrate
  

• Look first at:
  • config/settings.php for table name, cache behavior, and any package options.
  • The published migration for the actual schema and column names.
  • The README for the exact helper/facade signatures for your pinned version.
  • The service provider binding if you need to inject or extend the settings repository.
• First day-to-day use case: store editable runtime values such as site title, support email, feature flags, or admin-configurable limits. Read them with a fallback and write them from an admin controller:

  $title = settings('site.title', config('app.name'));
  
  settings()->set('site.title', 'Acme');
  // Some versions also support: settings(['site.title' => 'Acme']);
  

• Use the helper in Blade/controllers for simple reads, but centralize key names and typing in your own small settings class as soon as you have more than a handful of keys.

Implementation Patterns

• Use dotted keys as namespaces: site.title, mail.from_address, billing.currency, features.checkout_v2. Keep a single source of truth for these keys, e.g. constants or a dedicated AppSettings class, so typos do not become silent fallback bugs.
• Always read with an explicit fallback:

  $currency = settings('billing.currency', 'USD');
  

  This keeps fresh installs, failed migrations, and partially populated databases from breaking pages.
• Write through a validated admin action, not ad hoc from random controllers:

  public function update(SiteSettingsRequest $request)
  {
      DB::transaction(function () use ($request) {
          foreach ($request->validated() as $key => $value) {
              settings()->set($key, $value);
          }
      });
  
      return back();
  }
  

  Wrap bulk updates in a transaction so a partial save does not leave mixed settings.
• Add typed accessors on top of the package. The package is a key-value store, not a typed configuration system:

  class AppSettings
  {
      public static function bool(string $key, bool $default = false): bool
      {
          $value = settings($key, $default);
  
          return filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? $default;
      }
  
      public static function array(string $key, array $default = []): array
      {
          $value = settings($key);
  
          return $value === null ? $default : (json_decode($value, true) ?: $default);
      }
  }
  

• Use the package for values that operations/admin users should change without a deploy. Keep infrastructure and secret values in .env/config; do not store API keys or passwords in a plain settings table unless you have encryption and access controls around it.
• For Blade, read once per request or via a view composer where practical:

  {{ settings('site.title', config('app.name')) }}
  

  Avoid calling settings repeatedly inside large loops; rely on the package cache but do not assume it is free.
• Use existence checks when null, false, 0, and empty strings are meaningful:

  if (settings()->has('features.checkout_v2')) {
      // explicitly configured
  }
  

• Seed sensible defaults in a seeder or deployment step rather than scattering fallbacks everywhere. If seeding directly into the settings table, clear the package cache afterward if your version caches aggressively.
• For multi-tenant applications, prefix keys with the tenant identifier or build a wrapper around the package. The package is a global key-value store; it does not scope settings per tenant by default:

  $key = "tenant:{$tenant->id}:site.title";
  

• In tests, use RefreshDatabase, flush the cache in setUp, and set only the keys the test needs. Do not depend on settings persisted in your local development database.

Gotchas and Tips

• The last release is from 2018, so compatibility is the first risk. Check PHP/Laravel constraints before adopting it in a modern app. If you are on a newer Laravel version, budget time for a fork or a small compatibility layer.
• Version 2.0.3 fixed a possible empty() bug. Pin at least that version, and still avoid relying on empty() semantics for settings. false, 0, and '' are valid values; use has()/strict null checks instead.
• Confirm how non-string values are stored. If the package stores strings only, JSON-encode arrays and explicitly cast booleans/ints in your wrapper. Do not assume an array written today will come back as an array tomorrow.
• Cache invalidation is the most common operational trap. Writes through the package API should invalidate the package cache, but direct database edits, imports, or raw SQL will not. After manual changes, clear the relevant cache or run php artisan cache:clear during debugging.
• Avoid calling settings() from config/*.php, package boot code, or anywhere that may run before the database is available. It will break config:cache, migrations, and early bootstrap paths. Prefer middleware, view composers, or service methods invoked after the app is fully booted.
• The package has no built-in schema, validation, or typing. Treat it as storage, not as your settings domain model. Define allowed keys, validation rules, defaults, and casts in application code.
• Dotted keys are convenient but can become ambiguous if you ever need literal dots inside a key segment. Keep key segments simple: lowercase, underscores, and clear namespaces.
• The settings table is global. If you add tenant support later, retrofitting it is harder than prefixing keys from day one or extending the repository with a tenant column.
• Secure the admin surface that writes settings. A settings screen is effectively a runtime configuration editor; authorize it, validate every value, and log changes if the settings affect billing, access, or external integrations.
• For debugging, use php artisan tinker:

  settings()->all();
  settings('site.title');
  settings()->has('site.title');
  

  Then inspect the settings table and the cache store. If a value “disappears,” check for null vs false/0, cache staleness, and whether the key was written under a different dotted namespace.
• Good extension points: a typed AppSettings service, a settings schema config file with defaults and validation rules, an admin controller with audit logging, and a custom repository/model if you need tenant scoping or encrypted values. Keep those extensions in your app rather than modifying the vendor package unless you are prepared to maintain a fork.