Laravel Settings Laravel Package

Getting Started

This release is a low-risk compatibility update: Laravel 13 is now supported alongside Laravel 12, the settings API is unchanged, and CI covers both framework versions. If you are already using the package, no code changes should be required. If you are evaluating it, start with the following:

1. Confirm your support matrix. Check composer.json constraints for laravel/framework (^12.0|^13.0), your PHP version, and any transitive dependencies that may not yet support Laravel 13.
2. Install and publish package assets. Run composer require for the package, then publish its config and migrations. Review published migrations before running them in production.
3. Run migrations. Settings are typically persisted in a database table. Ensure your deployment pipeline runs migrations before code that reads settings is exercised.
4. Define your first settings class. Start with one small, app-wide group such as GeneralSettings or MailSettings. Use typed properties and sensible defaults so the app works before any values are saved.
5. Resolve settings through the package’s repository/container binding. Avoid reading the settings table directly; use the package API so caching, casting, and encryption behaviour remain consistent.
6. Verify the round trip. In a local environment, load the settings object, change a value, save it, and reload it. Confirm the value persists and that the cached value is refreshed.

First useful use case: replace hard-coded application options—site name, support email, feature flags, notification preferences—with a database-backed settings group that can be changed without redeploying.

Implementation Patterns

Group settings by domain, not by page. Create one settings class per cohesive area: GeneralSettings, BillingSettings, NotificationSettings. This keeps migrations and cache invalidation predictable and avoids a single monolithic settings object.

Use the repository as the only read/write path. Resolve settings from the container or inject the repository. Day-to-day code should look like:

$settings = app(GeneralSettings::class);
$settings->site_name = 'Acme';
$settings->save();

Avoid DB::table('settings') reads and writes. Direct database access bypasses casting, encryption, and cache invalidation.

Treat settings as runtime overrides, not config replacements. Configuration files are loaded during framework bootstrap and are affected by config:cache. Settings are usually resolved later. Use settings for values that operations teams should change without a deployment; keep infrastructure and secret configuration in .env/config.

Cache aggressively and invalidate through the package. Settings are read frequently but written rarely. Enable the package cache if available, and always save through the package API so the cache is cleared. If you introduce a custom write path, clear the package cache explicitly.

Seed defaults through migrations or a seeder. New environments should boot with usable values. Prefer nullable columns plus typed defaults in the settings class, or a seeder that creates the initial row. This prevents null-related type errors on first boot.

Scope tenant-specific settings deliberately. If the package supports scoping or multiple repositories, key settings by tenant or team ID and resolve the correct repository per request. Do not store tenant-specific values in a global settings row.

Wire settings into service providers carefully. If a service provider needs a setting, resolve it lazily inside a closure or a booted callback. Reading settings in register() can run before migrations or before the database is available, especially during package discovery or config caching.

Test with the package’s fakes or an in-memory repository where possible. For integration tests, use RefreshDatabase and seed the settings row. For unit tests, bind a fake repository so tests do not depend on the settings table. Assert both the saved value and the cache-refresh behaviour.

Use the Laravel 12/13 CI matrix as your own compatibility check. If your application has custom settings repositories, casters, or service-provider bindings, run your test suite against both Laravel versions during the upgrade window.

Gotchas and Tips

• No breaking changes in v1.2.0. The settings API is explicitly maintained. The main upgrade risk is dependency resolution, not package code. Run composer update --with-all-dependencies in a branch and inspect the lock file.
• Laravel 13 compatibility does not guarantee your whole dependency tree is ready. Check packages that decorate or extend the settings repository, and any package that pins laravel/framework below 13.
• Do not read settings inside config/*.php. Config files are evaluated during config:cache, often before the database is available. If you need a setting in config, resolve it in a service provider and merge it at runtime.
• Watch for stale settings under Octane and long-running workers. Cached settings can persist across requests in resident workers. After a settings save, ensure the package cache is cleared; if you cache settings in your own singleton, reset it on each request or listen for the package’s save event.
• Beware type coercion. Database values often come back as strings. Typed properties and casters help, but booleans, nullable values, and JSON arrays need explicit handling. Test false, 0, empty strings, and null rather than assuming defaults.
• Encrypt sensitive settings. If the package supports encrypted casts, use them for API keys, SMTP passwords, and tokens. Do not rely on database permissions alone.
• Publish and review migrations. Package migrations may create tables or columns that conflict with an existing settings table. In an established application, compare the published migration with your schema before running it.
• Clear cache after direct database changes. If an incident requires a manual UPDATE, follow it with the package’s cache-clear command or API call. Otherwise the application may continue serving the old value.
• Check boot order when using settings in gates, policies, or middleware. These can run before the request is fully booted. Resolve settings inside the method rather than in a constructor.
• Extension points to inspect: custom repositories for multi-tenant scoping, custom casters for value objects, encryption for secrets, and cache drivers for distributed deployments. Validate these against Laravel 13 in a staging environment before production rollout.