README

A focused, database-backed key-value settings store for Laravel.

Requirements

• PHP 8.3 or newer
• Laravel 12.60 or newer, or Laravel 13.10 or newer

Installation

Install the package:

composer require satheez/laravel-settings

Publish and run the migration:

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

Publish the configuration when the defaults need to be changed:

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

Usage

Inject the settings contract into application services:

use Satheez\LaravelSettings\Contracts\Settings;

final readonly class UpdateCheckoutConfiguration
{
    public function __construct(private Settings $settings) {}

    public function handle(): void
    {
        $this->settings->set('checkout.enabled', true);
    }
}

The contract provides:

$settings->get('checkout.enabled', false);
$settings->set('checkout.enabled', true);
$settings->setMany([
    'checkout.enabled' => true,
    'checkout.countries' => ['LK', 'US'],
]);
$settings->has('checkout.enabled');
$settings->forget('checkout.enabled');
$settings->all();

all() returns an associative array sorted by key. forget() returns whether a row was deleted.

The facade is available when dependency injection is not practical:

use Satheez\LaravelSettings\Facades\Settings;

Settings::set('checkout.enabled', true);

$enabled = Settings::get('checkout.enabled', false);

Supported Values

Settings may contain JSON-safe values:

• null
• booleans
• integers and finite floats
• valid UTF-8 strings
• nested arrays containing supported values

Objects, resources, non-finite floats, and invalid UTF-8 strings are rejected with an UnsupportedSettingValue exception.

Stored null, false, 0, 0.0, empty strings, and empty arrays are real values. The default passed to get() is returned only when the key is absent.

Encryption

New values are encrypted by default with Laravel's application encrypter. Each stored payload records whether it is encrypted, so changing the global setting does not make existing version 2 rows unreadable.

LARAVEL_SETTINGS_ENCRYPTION_ENABLED=true

Keep APP_KEY stable. Data encrypted with a previous key cannot be recovered unless that key remains configured through Laravel's key rotation support.

Cache

Database payloads and missing-key lookups are cached by default:

LARAVEL_SETTINGS_CACHE_ENABLED=true
LARAVEL_SETTINGS_CACHE_STORE=
LARAVEL_SETTINGS_CACHE_PREFIX=laravel-settings
LARAVEL_SETTINGS_CACHE_TTL=3600

Writes refresh affected cache entries. Deletes and legacy migrations invalidate them. Cache backend failures are not swallowed.

Database Configuration

The default table is settings on the application's default connection:

LARAVEL_SETTINGS_DB_CONNECTION=
LARAVEL_SETTINGS_TABLE=settings

The configured table must contain the columns created by the package migration.

Upgrading From Version 1

Version 2 reads existing plain and encrypted version 1 rows without modifying them. Review UPGRADING.md, then validate the conversion:

php artisan laravel-settings:migrate --dry-run

Rewrite legacy rows after the dry run succeeds:

php artisan laravel-settings:migrate

Use --force for non-interactive production deployments and --chunk=500 to control read batch size. The command is transactional and idempotent.

The version 1 helpers and LaravelSettings facade remain available as deprecated compatibility wrappers. New code should use the contract or Settings facade.

Testing

composer check
composer test-coverage

Security

Review SECURITY.md before reporting a vulnerability.

License

The MIT License. See LICENSE.md.