Laravel Settings

https://github.com/spatie/laravel-settings
Admin
A package that allows you to store strongly typed application settings in a repository like the...
Tokens:79,883
Snippets:602
Trust Score:-
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example usage of make:settings-migration

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/ConsoleCommands.md

Example commands for creating a settings migration. The first uses the default path, the second specifies a custom path.

```bash
php artisan make:settings-migration CreateGeneralSettings
php artisan make:settings-migration CreateGeneralSettings database/settings/tenant
```

--------------------------------

### Installation commands for LaravelSettingsServiceProvider

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/LaravelSettingsServiceProvider.md

Installation steps: publish the migration stub, run migrations, then publish the config file. After this, `config('settings')` returns the package configuration and console commands are available.

```bash
php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="migrations"
php artisan migrate
php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="config"
```

--------------------------------

### Install spatie/laravel-settings via Composer

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Install the package via Composer.

```bash
composer require spatie/laravel-settings
```

--------------------------------

### make:setting usage examples

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/ConsoleCommands.md

Example invocations of the make:setting command. The first creates GeneralSettings in the default group, the second creates BlogSettings in the blog group and writes it to app/Settings/Admin.

```bash
php artisan make:setting GeneralSettings --group=general
php artisan make:setting BlogSettings --group=blog --path=app/Settings/Admin
```

--------------------------------

### Usage example for SettingsCacheFactory

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Support.md

Demonstrates how to resolve the factory from the container, build default and repository-specific caches, and clear all caches.

```php
$cacheFactory = app(SettingsCacheFactory::class);

$defaultCache = $cacheFactory->build();                 // config('settings.cache')
$databaseCache = $cacheFactory->build('database');      // config('settings.repositories.database.cache') if set

foreach ($cacheFactory->all() as $cache) {
    $cache->clear();
}
```

--------------------------------

### SettingsMigrator usage examples

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Migrations.md

Examples of using the SettingsMigrator directly for migration operations, including error handling and repository selection.

```APIDOC
## SettingsMigrator Usage

### Description
Examples of using the SettingsMigrator to perform migration operations on settings.

### Usage Example: Full Migration
```php
use Spatie\LaravelSettings\Migrations\SettingsMigration;

return new class extends SettingsMigration
{
    public function up(): void
    {
        $this->migrator->add('general.site_name', 'Spatie');
        $this->migrator->addEncrypted('general.api_key', 'secret');
        $this->migrator->update('general.site_name', fn (string $name) => return str_upper($name));
        $this->migrator->rename('general.site_name', 'company.site_name');
        $this->migrator->decrypt('general.api_key');

        if ($this->migrator->exists('company.site_name')) {
            $this->migrator->delete('company.site_name');
        }

        $this->migrator->inGroup('general', function (SettingsBlueprint $blueprint): void {
            $blueprint->add('timezone', 'Europe/Brussels');
            $blueprint->update('timezone', fn (string $tz) => return 'UTC');
            $blueprint->deleteIfExists('obsolete');
        });
    }
};
```

### Error Handling Example
```php
public function up(): void
{
    try {
        $this->migrator->add('general.site_name', 'Spatie');
    } catch (SettingAlreadyExists $exception) {
        // "Could not create setting general.site_name because it already exists"
    }

    try {
        $this->migrator->delete('general.nonexistent');
    } catch (SettingDoesNotExist $exception) {
        // "Could not delete setting general.nonexistent because it does not exist"
    }
}
```

### Repository Selection Example
```php
public function up(): void
{
    $this->migrator->repository('redis');
    $this->migrator->add('general.site_active', true);
}
```
```

--------------------------------

### Usage example for SettingsCastFactory::resolve

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Factories.md

Shows how to manually resolve a cast for a property using SettingsCastFactory. The example uses a DateSettings class with a birth_date property, then sets and gets a DateTime value through the resolved cast.

```php
$property = (new ReflectionClass(DateSettings::class))->getProperties(ReflectionProperty::IS_PUBLIC)['birth_date'];

$cast = SettingsCastFactory::resolve($property, DateSettings::casts());

$repositoryValue = $cast->set($dateTime);      // DateTimeInterfaceCast → 'YYYY-MM-DDTHH:MM:SS±HH:MM' (DATE_ATOM)
$dateTime = $cast->get($repositoryValue);      // back to DateTime
```

--------------------------------

### Register DatabaseSettingsRepository in config/settings.php

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsRepositories.md

Example configuration for registering the repository with a custom table, model, and connection.

```php
'repositories' => [
    'landlord' => [
        'type' => Spatie\LaravelSettings\SettingsRepositories\DatabaseSettingsRepository::class,
        'model' => null,
        'table' => 'landlord_settings',
        'connection' => 'landlord',
    ],
],
```

--------------------------------

### Configure a database repository with caching in settings.php

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Example configuration for a database repository with an optional cache block. The cache settings include enabled, store, prefix, and ttl, and can be added to any repository config within the settings.php file.

```php
'repositories' => [
    'landlord' => [
        'type' => Spatie\LaravelSettings\SettingsRepositories\DatabaseSettingsRepository::class,
        'model' => null,
        'table' => null,
        'connection' => 'landlord',
        'cache' => [
            'enabled' => env('SETTINGS_CACHE_ENABLED', false),
            'store' => null,
            'prefix' => 'landlord',
            'ttl' => null,
        ],
    ],
    
    ...
],
```

--------------------------------

### get

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsCache.md

Returns the cached `Settings` instance, or `null` when the cache store has no entry. On a hit, marks the restored instance via `settingsConfig()->markLoadedFromCache(true)`.

```APIDOC
## get

### Description
Returns the cached `Settings` instance, or `null` when the cache store has no entry. On a hit, marks the restored instance via `settingsConfig()->markLoadedFromCache(true)`.

### Method
`public function get(string $settingsClass): ?Settings`

### Parameters
- **settingsClass** (`string`) - Required - Class-string of the settings class to restore.

### Throws
- `SettingsCacheDisabled` when `enabled === false`.
- `CouldNotUnserializeSettings` when the deserialized value is not a `Settings` instance (`! $settings instanceof Settings`). The container's `registerBindings()` catches this exception and falls back to constructing a fresh instance.

### Source
`src/SettingsCache.php:48`
```

--------------------------------

### Get all locked properties with getLockedProperties()

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Retrieve an array of all currently locked settings. The comment shows an example return value.

```php
$dateSettings->getLockedProperties(); // ['birth_date']
```

--------------------------------

### Update and save settings

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Update settings by assigning new values to the properties and calling save(). The example uses a form request for validation and redirects back after saving.

```php
class GeneralSettingsController
{
    public function update(
        GeneralSettingsRequest $request,
        GeneralSettings $settings
    ){
        $settings->site_name = $request->input('site_name');
        $settings->site_active = $request->input('site_active');
        
        $settings->save();
        
        return redirect()->back();
    }
}
```

--------------------------------

### Usage example of ShouldBeEncrypted attribute

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Support.md

Usage example of the `ShouldBeEncrypted` attribute. `$settings->api_key` is then encrypted in the repository and inside the settings cache, and migration operations use `addEncrypted`/`updateEncrypted`.

```php
use Spatie\LaravelSettings\Attributes\ShouldBeEncrypted;

class GeneralSettings extends Settings
{
    #[ShouldBeEncrypted()]
    public string $api_key;

    public static function group(): string
    {
        return 'general';
    }
}

```

--------------------------------

### Full migration with built-in operations

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Migrations.md

A complete migration example using the built-in operations: add, addEncrypted, update, rename, decrypt, exists, delete, and inGroup with a SettingsBlueprint. Shows how to use the migrator directly and within a group context.

```php
use Spatie\LaravelSettings\Migrations\SettingsMigration;

return new class extends SettingsMigration
{
    public function up(): void
    {
        $this->migrator->add('general.site_name', 'Spatie');
        $this->migrator->addEncrypted('general.api_key', 'secret');
        $this->migrator->update('general.site_name', fn (string $name) => return str_upper($name));
        $this->migrator->rename('general.site_name', 'company.site_name');
        $this->migrator->decrypt('general.api_key');

        if ($this->migrator->exists('company.site_name')) {
            $this->migrator->delete('company.site_name');
        }

        $this->migrator->inGroup('general', function (SettingsBlueprint $blueprint): void {
            $blueprint->add('timezone', 'Europe/Brussels');
            $blueprint->update('timezone', fn (string $tz) => return 'UTC');
            $blueprint->deleteIfExists('obsolete');
        });
    }
};
```

--------------------------------

### Run tests with composer test

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Runs the test suite for the Laravel settings package. Use this command in the project root after installing dependencies.

```bash
composer test
```

--------------------------------

### SettingsCast interface

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Defines the contract for custom casters. Implement get() to convert repository payloads into settings values and set() to convert settings values back into repository payloads.

```php
interface SettingsCast
{
    /**
     * Will be used to when retrieving a value from the repository, and
     * inserting it into the settings class.
     */
    public function get($payload);

    /**
     * Will be used to when retrieving a value from the settings class, and
     * inserting it into the repository.
     */
    public function set($payload);
}
```

--------------------------------

### resolvePrefixUsing

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsCache.md

Registers a global resolver used when resolving cache keys (introduced for multi-tenant setups where tenants share the same settings classes and cache).

```APIDOC
## resolvePrefixUsing

### Description
Registers a global resolver used when resolving cache keys (introduced for multi-tenant setups where tenants share the same settings classes and cache).

### Method
`public static function resolvePrefixUsing(?callable $resolver): void`

### Parameters
- **resolver** (`?callable`) - Required - Callback returning a dynamic prefix string appended after the static config prefix. Pass `null` to remove the resolver.

### Source
`src/SettingsCache.php:31`
```

--------------------------------

### Creating repositories with SettingsRepositoryFactory

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Factories.md

Shows how to create a repository using the default repository or a named repository, then retrieve properties in a group.

```php
$repository = SettingsRepositoryFactory::create();                 // default_repository
$repository = SettingsRepositoryFactory::create('redis');          // named repository
$groupProperties = $repository->getPropertiesInGroup('general');
```

--------------------------------

### Publish and run migrations

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Publish and run the package migrations.

```bash
php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="migrations"
php artisan migrate
```

--------------------------------

### make:settings-migration command signature

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/ConsoleCommands.md

Shows the command signature and description for make:settings-migration. The name argument is required, while path? is optional and defaults to the first entry of settings.migrations_paths (or [settings.migrations_path] when set).

```text
signature : make:settings-migration {name : The name of the migration} {path? : Path to write migration file to}
description: Create a new settings migration file
```

--------------------------------

### ArrayDataCast class signature

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsCasts.md

Casts arrays of Spatie\LaravelData\Data objects by delegating to an inner DataCast. set() maps $cast->set($data) (Data → array); get() maps $cast->get($data) (array → Data). Source: src/SettingsCasts/ArrayDataCast.php:7.

```php
class ArrayDataCast implements SettingsCast
{
    public function __construct(?string $type, bool|string $validate = false)
    public function get($payload): array       // @param array<array> payload  →  Data[]
    public function set($payload): array       // @param array<array|Data> payload  →  array<array>
}
```

--------------------------------

### Migration against a custom repository

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Migrations.md

Demonstrates running migration operations against a different repository by calling repository('redis') before adding a setting. Use this to target a non-default repository for the migration.

```php
public function up(): void
{
    $this->migrator->repository('redis');
    $this->migrator->add('general.site_active', true);
}
```

--------------------------------

### EnumCast class skeleton

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsCasts.md

Cast for Spatie Laravel Settings that converts between an enum and its backing value or name. For BackedEnum, get uses from() and set uses value; for UnitEnum, get matches by name and set uses name. Throws Exception('Invalid enum') for unsupported types.

```php
class EnumCast implements SettingsCast
{
    public function __construct(string $enum)
    public function get($payload): ?UnitEnum
    public function set($payload): string|int|null
}
```

--------------------------------

### Run migrations to add settings properties

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Runs the database migrations to add the settings properties to the database.

```bash
php artisan migrate
```

--------------------------------

### Handling unknown repository name exception

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Factories.md

Demonstrates the exception thrown when creating a repository with an unknown name. The error message is "Tried to create unknown settings repository: unknown_repo".

```php
try {
    SettingsRepositoryFactory::create('unknown_repo');
} catch (Exception $exception) {
    echo $exception->getMessage(); // "Tried to create unknown settings repository: unknown_repo"
}
```

--------------------------------

### Run settings:discover command

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/ConsoleCommands.md

Run the settings:discover Artisan command to cache all auto-discovered settings classes.

```bash
php artisan settings:discover
```

--------------------------------

### Observe settings loading with LoadingSettings and SettingsLoaded events

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Events.md

Listen to LoadingSettings and SettingsLoaded events to observe settings lifecycle. Logs the settings class and properties when loading, and logs the loaded settings with cache status.

```php
use Spatie\LaravelSettings\Events\LoadingSettings;
use Spatie\LaravelSettings\Events\SettingsLoaded;

Event::listen(LoadingSettings::class, fn (LoadingSettings $event) => {
    logging()->info("Loading { $event->settingsClass } with properties: ", $event->properties->keys());
});

Event::listen(SettingsLoaded::class, fn (SettingsLoaded $event) => {
    logging()->info("Settings loaded (from cache: { $event->loadedFromCache }): ", $event->settings->toArray());
});
```

--------------------------------

### Publish configuration file

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/configuration.md

Publishes the package configuration file to the application's config directory. Run this command to customize the settings configuration.

```bash
php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider" --tag="config"
```

--------------------------------

### Configure custom encoder and decoder

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Define custom encoders and decoders in the package configuration to replace the built-in json_encode and json_decode. The example uses str_rot13 for obfuscation.

```php
...
'encoder' => fn($value): string => str_rot13(json_encode($value)),
'decoder' => fn(string $payload, bool $associative) => json_decode(str_rot13($payload), $associative),
...
```

--------------------------------

### SettingsCache::__construct

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsCache.md

Documentation for the SettingsCache constructor, which configures the cache-backed settings store.

```APIDOC
## SettingsCache Constructor

### Description
Creates a new `SettingsCache` instance that wraps an Illuminate cache store to cache serialized `Settings` instances. The constructor accepts configuration for enabling caching, the cache store name, a key prefix, a TTL, and optional memoization.

### Method
Constructor

### Signature
```php
public function __construct(
    private bool $enabled,
    private ?string $store,
    private ?string $prefix,
    private DateTimeInterface|DateInterval|int|null $ttl = null,
    private bool $memo = false,
)
```

### Parameters
- **enabled** (bool) - Required - Whether caching is active.
- **store** (?string) - Required - Cache store name (a store defined in the `cache.php` config); `null` uses the default store.
- **prefix** (?string) - Required - Static string prepended to every cache key.
- **ttl** (DateTimeInterface|DateInterval|int|null) - Optional - Default: `null` - Cache lifetime passed to the store's `put()`.
- **memo** (bool) - Optional - Default: `false` - When true, uses Illuminate's memoized cache driver (`Cache::memo()`), keeping resolved values in memory during a single request (Laravel 12.9+; silently ignored on older versions).
```

--------------------------------

### SettingsProperty Eloquent model

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsRepositories.md

Default Eloquent model for settings. Uses the 'settings' table, no guarded attributes, casts 'locked' to boolean, and provides a static get method.

```php
class SettingsProperty extends Model
{
    protected $table = 'settings';
    protected $guarded = [];
    protected $casts = ['locked' => 'boolean'];

    public static function get(string $property)
}
```

--------------------------------

### Tenant-scoped cache keys with resolvePrefixUsing

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsCache.md

Registers a prefix resolver to include the tenant domain in cache keys. The resolver is later removed by passing null. Cache keys become '{prefix}.{tenant}...settings.GeneralSettings'.

```php
SettingsCache::resolvePrefixUsing(fn () => app(Tenant::class)->getDomain());

// Later — cache keys become "{prefix}.{tenant}...settings.GeneralSettings"

// Remove the resolver again:
SettingsCache::resolvePrefixUsing(null);
```

--------------------------------

### __debugInfo()

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Settings.md

Returns the settings as an array once values are loaded; on failure returns an array with a message.

```APIDOC
## __debugInfo()

### Description
Returns `toArray()` once values are loaded; on failure (any `Exception` during load) returns `['Could not load values']`.

### Method
__debugInfo

### Parameters
None

### Returns
- array - The settings array or error message.

### Source
`src/Settings.php:116`
```

--------------------------------

### make:setting command signature

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/ConsoleCommands.md

Shows the signature, name, and description of the make:setting artisan command. The signature defines the required name argument and the --group and --path options.

```text
signature : make:setting {name : The name of the setting class} {--group=default : The group name} {--path= : Path to write the setting class file to}
name      : make:setting
description: Create a new Settings Class
```

--------------------------------

### SettingsCast interface

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsCasts.md

The SettingsCast interface defines two methods, get and set, that are called when values are retrieved from the repository into the settings class and vice versa. Custom casts must implement this interface.

```APIDOC
## SettingsCast interface

### Description
Defines the contract for casts that transform values between the settings class and the repository.

### Methods

#### get($payload)
- **Direction:** repository → settings class
- **Description:** Called when a value is retrieved from the repository and inserted into the settings class.

#### set($payload)
- **Direction:** settings class → repository
- **Description:** Called when a value is retrieved from the settings class and inserted into the repository.

### Interface Definition
```php
interface SettingsCast
{
    public function get($payload);
    public function set($payload);
}
```

### Notes
- Import path: `Spatie\LaravelSettings\SettingsCasts\SettingsCast`
- Source: `src/SettingsCasts/SettingsCast.php:5`
- When the package resolves a cast, the property's type class-string is injected as the first constructor argument where it can be deduced; otherwise `null` is passed.
```

--------------------------------

### Custom SettingsCast implementation

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsCasts.md

A custom cast implementing the SettingsCast interface. The constructor accepts an optional type string, and the get method uses it to create a Data object from the payload, while set converts the payload to an array.

```php
use Spatie\LaravelSettings\SettingsCasts\SettingsCast;

class DtoCast implements SettingsCast
{
    private string $type;

    public function __construct(?string $type)
    {
        $this->type = $type;
    }

    public function get($payload): Data
    {
        return $this->type::from($payload);
    }

    public function set($payload): array
    {
        return $payload->toArray();
    }
}

```

--------------------------------

### Update and save settings with locking and error handling

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Settings.md

Demonstrates updating a settings instance, locking a property to prevent changes, saving, and catching MissingSettings exceptions to return validation errors.

```php
class GeneralSettingsController
{
    public function update(GeneralSettingsRequest $request, GeneralSettings $settings)
    {
        $settings->lock('site_name');          // cannot be changed in this save
        $settings->site_active = $request->boolean('site_active');

        try {
            $settings->save();
        } catch (MissingSettings $exception) {
            // Tried saving settings '...', and the following properties were missing: ...
            return back()->withErrors(['settings' => $exception->getMessage()]);
        }

        return redirect()->back();
    }
}
```

--------------------------------

### SettingsCast interface definition

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/types.md

Defines the contract for custom settings casts. Implement get($payload) to transform a stored payload into the settings-class value, and set($payload) to transform a settings-class value into the stored payload. Import from Spatie\LaravelSettings\SettingsCasts\SettingsCast.

```php
interface SettingsCast
{
    public function get($payload);
    public function set($payload);
}
```

--------------------------------

### DatabaseSettingsRepository constructor

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsRepositories.md

Constructor that accepts the repository configuration array.

```php
public function __construct(array $config)
```

--------------------------------

### Create a settings class extending Settings

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Defines a settings class with public properties and a static group method. The group method must return a string, and each property needs a default value set in a migration.

```php
use Spatie\LaravelSettings\Settings;

class GeneralSettings extends Settings
{
    public string $site_name;
    
    public bool $site_active;
    
    public static function group(): string
    {
        return 'general';
    }
}
```

--------------------------------

### DtoCast with injected type

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Simplified DtoCast for spatie/laravel-data. The constructor receives the property type (e.g., SongData::class) or null when it cannot be deduced. get() builds a Data object from repository payload; set() converts a Data object to an array for storage.

```php
class DtoCast implements SettingsCast
{
    private string $type;

    public function __construct(?string $type)
    {
        $this->type = $type;
    }

    public function get($payload): Data
    {
        return $this->type::from($payload);
    }

    public function set($payload): array
    {
        return $payload->toArray();
    }
}
```

--------------------------------

### DateTimeInterfaceCast class skeleton

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsCasts.md

Use this cast for properties typed with any DateTimeInterface implementation (DateTime, DateTimeImmutable, Carbon, CarbonImmutable, Illuminate\Support\Carbon). The constructor accepts an optional type string that defaults to DateTime::class. get() maps the concrete class-string to a constructor: Carbon\Carbon::class to new Carbon($payload), Carbon\CarbonImmutable::class to new CarbonImmutable($payload), Illuminate\Support\Carbon::class to new IlluminateCarbon($payload), DateTimeImmutable::class to new DateTimeImmutable($payload), DateTime::class (or null) to new DateTime($payload), and anything else throws an Exception with message "Could not cast DateTime type `{$this->type}`". set() returns $payload->format(DATE_ATOM); get() and set() pass through null.

```php
class DateTimeInterfaceCast implements SettingsCast
{
    public function __construct(?string $type)              // defaults to DateTime::class
    public function get($payload): ?DateTimeInterface
    public function set($payload): ?string                 // DATE_ATOM format
}
```

--------------------------------

### Settings::__construct(array $values = [])

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Settings.md

Constructor for the abstract Settings class. Initializes the settings instance with optional initial property values, or defers loading until first property access.

```APIDOC
## Settings::__construct(array $values = [])

### Description
Initializes a new settings instance. If `$values` is provided, they are immediately applied to the instance; otherwise, values are loaded lazily on first property access. The constructor also unsets all reflected public properties to avoid accidental inheritance.

### Method
Constructor

### Signature
```php
final public function __construct(array $values = [])
```

### Parameters
- **$values** (array) - Optional - Initial property values. Defaults to `[]`.

### Behavior
- Unsets every reflected public property (skipping read-only properties) before applying `$values`.
- If `$values` is non-empty, calls `loadValues()` to write them into the instance.
- If `$values` is empty, values are loaded lazily on first property access.

### Notes
- This class is abstract and cannot be instantiated directly.
- Subclasses must declare a static `group()` method and may override `repository()`, `casts()`, `encrypted()`, and `cacheKey()` hooks.
- Instances are registered in the Illuminate container via `SettingsContainer::registerBindings()` and can be injected into controllers and other classes.
```

--------------------------------

### Access settings property via app() helper

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Loads the settings class from the container and accesses the site_name property.

```php
function getName(): string{
    return app(GeneralSettings::class)->site_name;
}
```

--------------------------------

### Catch cache exceptions when getting settings

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/errors.md

Catches exceptions when retrieving settings from cache. SettingsCacheDisabled indicates cache is not enabled for the cache object, while CouldNotUnserializeSettings indicates a corrupted cache entry, prompting a clear and rebuild. Note that the container's registerBindings() already catches CouldNotUnserializeSettings internally.

```php
use Spatie\LaravelSettings\Exceptions\CouldNotUnserializeSettings;
use Spatie\LaravelSettings\Exceptions\SettingsCacheDisabled;

try {
    $settings = $cache->get(GeneralSettings::class);
} catch (SettingsCacheDisabled $exception) {
    // cache not enabled for this cache object
} catch (CouldNotUnserializeSettings $exception) {
    // corrupted cache entry — clear and rebuild
    $cache->clear();
}
```

--------------------------------

### DataCast class signature

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsCasts.md

Casts Spatie\LaravelData\Data objects. The constructor requires a class-string of a Data subclass; when validate is truthy (strings 'true'/'1' are treated as true), get() uses validateAndCreate() instead of from(). Throws built-in Exception in ensureDataTypeExists() when no data class is given, the class does not exist, or the class does not implement Spatie\LaravelData\Contracts\BaseData. Source: src/SettingsCasts/DataCast.php:9.

```php
class DataCast implements SettingsCast
{
    public function __construct(?string $type, string|bool $validate = false)
    public function get($payload): Data   // validated: $type::validateAndCreate($payload), else $type::from($payload)
    public function set($payload): array  // $payload->toArray()
}
```

--------------------------------

### Set a custom repository for a settings class

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Explicitly sets the repository for a settings class by implementing the repository method. When not set, the default_repository from the config is used.

```php
class GeneralSettings extends Settings
{
    public string $site_name;
    
    public bool $site_active;
    
    public static function group(): string
    {
        return 'general';
    }
    
    public static function repository(): ?string
    {
        return 'global_settings';
    }
}
```

--------------------------------

### Define a settings subclass and lazy load via injection

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Settings.md

Shows a basic GeneralSettings subclass with a group() method and a controller that receives the settings instance via dependency injection, reading properties lazily.

```php
use Spatie\LaravelSettings\Settings;

class GeneralSettings extends Settings
{
    public string $site_name;

    public bool $site_active;

    public static function group(): string
    {
        return 'general';
    }
}

// In a controller — settings are injected from the container:
class GeneralSettingsController
{
    public function show(GeneralSettings $settings)
    {
        return view('settings.show', [
            'site_name'   => $settings->site_name,
            'site_active' => $settings->site_active,
        ]);
    }
}
```

--------------------------------

### Initialize, load, and save settings with SettingsMapper

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsMapper.md

Use this snippet to interact with the SettingsMapper through the application container. It initializes the mapper, loads settings values, and saves a new value. The mapper is not called directly in normal application code; the entry point is the Settings subclass.

```php
$mapper = app(SettingsMapper::class);

$config = $mapper->initialize(GeneralSettings::class);

$values = $mapper->load(GeneralSettings::class);
echo $values['site_name'];

$saved = $mapper->save(GeneralSettings::class, collect([
    'site_name' => 'Spatie',
]));
```

--------------------------------

### toCollection()

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Settings.md

Returns the settings as a Collection keyed by property name.

```APIDOC
## toCollection()

### Description
Returns a `\Illuminate\Support\Collection` keyed by reflected property name → current value.

### Method
toCollection

### Parameters
None

### Returns
- \Illuminate\Support\Collection - The settings collection.

### Source
`src/Settings.php:228`
```

--------------------------------

### getRepository(): SettingsRepository

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsConfig.md

Returns the resolved repository instance.

```APIDOC
## getRepository(): SettingsRepository

### Description
Returns the resolved repository.

### Method
getRepository

### Signature
`public function getRepository(): SettingsRepository`

### Returns
- **SettingsRepository** - The resolved repository instance.

```

--------------------------------

### SettingsRepositoryFactory::create

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Factories.md

Static factory method to create a settings repository instance. It resolves the repository name from the provided argument or the default configuration, validates it against the configured repositories, and instantiates the repository class with its configuration.

```APIDOC
## SettingsRepositoryFactory::create

### Description
Creates a settings repository instance based on the provided name or the default repository from configuration.

### Method
`public static function create(?string $name = null): SettingsRepository`

### Parameters
- **name** (`?string`) - Optional - Repository name. When omitted, `config('settings.default_repository')` is used.

### Returns
- `SettingsRepository` - The created repository instance.

### Exceptions
- `Exception` - Thrown when the repository name is not found in `config('settings.repositories')`.

### Usage Example
```php
$repository = SettingsRepositoryFactory::create();                 // default_repository
$repository = SettingsRepositoryFactory::create('redis');          // named repository
$groupProperties = $repository->getPropertiesInGroup('general');
```

### Error Example
```php
try {
    SettingsRepositoryFactory::create('unknown_repo');
} catch (Exception $exception) {
    echo $exception->getMessage(); // "Tried to create unknown settings repository: unknown_repo"
}
```
```

--------------------------------

### toJson($options = 0)

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Settings.md

Returns the settings as a JSON string.

```APIDOC
## toJson($options = 0)

### Description
Returns `json_encode($this->toArray(), $options)`.

### Method
toJson

### Parameters
- `options` (int) - Optional - Default `0` - `json_encode` flags.

### Returns
- string - The JSON representation.

### Source
`src/Settings.php:242`
```

--------------------------------

### Run make:setting command and see error

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/ConsoleCommands.md

Run the make:setting command with the --group option. If the target already exists, the command throws an InvalidArgumentException with the message 'GeneralSettings already exists!'.

```bash
php artisan make:setting GeneralSettings --group=general
# InvalidArgumentException: GeneralSettings already exists!
```

--------------------------------

### Error handling with SettingAlreadyExists and SettingDoesNotExist

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Migrations.md

Shows error handling during a migration run. Catches SettingAlreadyExists when adding a setting that already exists and SettingDoesNotExist when deleting a non-existent setting, with the corresponding exception messages.

```php
public function up(): void
{
    try {
        $this->migrator->add('general.site_name', 'Spatie');
    } catch (SettingAlreadyExists $exception) {
        // "Could not create setting general.site_name because it already exists"
    }

    try {
        $this->migrator->delete('general.nonexistent');
    } catch (SettingDoesNotExist $exception) {
        // "Could not delete setting general.nonexistent because it does not exist"
    }
}
```

--------------------------------

### settingsConfig(): SettingsConfig

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Settings.md

Constructs and returns the SettingsConfig for the settings class. This is the entry point that wires the mapper, reflected properties, casts, encrypted set, and repository.

```APIDOC
## `public function settingsConfig(): SettingsConfig`

### Description
Constructs (once) and returns the `SettingsConfig` for this settings class. This is the entry point that wires the mapper, reflected properties, casts, encrypted set, and repository.

### Method
GET

### Endpoint
`/settingsConfig`

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **SettingsConfig** (object) - The constructed SettingsConfig instance.

#### Response Example
```json
{
  "mapper": "...",
  "properties": "...",
  "casts": "...",
  "encrypted": "...",
  "repository": "..."
}
```
```

--------------------------------

### SettingsRepositoryFactory::create method signature

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Factories.md

Defines the static factory method that creates a settings repository instance. The optional $name parameter defaults to config('settings.default_repository') when omitted.

```php
class SettingsRepositoryFactory
{
    public static function create(?string $name = null): SettingsRepository
}
```

--------------------------------

### Run settings:clear-cache command

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/ConsoleCommands.md

Run the settings:clear-cache Artisan command to clear all cached settings.

```bash
php artisan settings:clear-cache
```

--------------------------------

### Retrieve and inspect settings configuration with settingsConfig()

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsConfig.md

Retrieve the settings configuration object and demonstrate locking, group retrieval, encryption check, and cast class lookup. The `lock` method prevents modification of the specified keys. The `getGroup` method returns the group name, `isEncrypted` checks if a key is encrypted, and `getCast` returns the cast class for a key, using null-safe operator.

```php
$config = $settings->settingsConfig();

$config->lock('site_name', 'api_key');
echo $config->getGroup();          // 'general'
echo $config->isEncrypted('api_key'); // true
echo $config->getCast('birth_date')?->getClass(); // Spatie\LaravelSettings\SettingsCasts\DateTimeInterfaceCast
```

--------------------------------

### SettingsMigrator

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Migrations.md

Complete reference for the SettingsMigrator class, including constructor, all public methods, and property naming rules.

```APIDOC
## SettingsMigrator

### Description
Provides migration operations for settings properties, allowing you to add, rename, delete, update, encrypt, and decrypt settings within a repository.

### Constructor

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `connection` | `SettingsRepository` | required (injected) | — | The repository migration operations act on. |

### Methods

#### `repository(string $name): self`
Switches the migrator to the named repository via `SettingsRepositoryFactory::create($name)`; returns `$this`.

#### `rename(string $from, string $to): void`
Moves a property (including to another group). Throws `SettingDoesNotExist::whenRenaming` when `$from` does not exist; `SettingAlreadyExists::whenRenaming` when `$to` already exists. Preserves the locked state.

#### `add(string $property, $value = null, bool $encrypted = false): void`
Creates a property. Throws `SettingAlreadyExists::whenAdding` when it already exists. When `$encrypted` is true, the value is encrypted first.

#### `delete(string $property): void`
Deletes a property. Throws `SettingDoesNotExist::whenDeleting` when it does not exist.

#### `deleteIfExists(string $property): void`
Deletes a property only when it exists (no-op otherwise).

#### `update(string $property, Closure $closure, bool $encrypted = false): void`
Applies `$closure($originalPayload)` and stores the result. Throws `SettingDoesNotExist::whenEditing` when it does not exist. When `$encrypted`, the original payload is decrypted before the closure and the result encrypted after.

#### `addEncrypted(string $property, $value = null): void`
`add($property, $value, true)`.

#### `updateEncrypted(string $property, Closure $closure): void`
`update($property, $closure, true)`.

#### `encrypt(string $property): void`
`update($property, fn ($payload) => Crypto::encrypt($payload))` — makes a stored value encrypted.

#### `decrypt(string $property): void`
`update($property, fn ($payload) => Crypto::decrypt($payload))` — makes a stored value plain.

#### `exists(string $property): bool`
Whether the property exists in the repository.

#### `inGroup(string $group, Closure $closure): void`
Invokes `$closure(new SettingsBlueprint($group, $this))` so operations can be written without repeating the group prefix.

### Property-name format and casts

- Every `$property` must be formatted `group.name`; otherwise `InvalidSettingName::create($property)` is thrown (protected `getPropertyParts`, source line 129).
- Object payloads written through `add`/`update...` are passed through the property's cast `set()` (resolved via `SettingsConfig::getCast()` for the group/property), and raw payloads read back are passed through the cast `get()` — so DateTime/Data/… properties behave the same in migrations as at runtime.
```

--------------------------------

### Published config file (config/settings.php)

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Default configuration file for the package. It defines settings registration, repository configuration, caching, and global casts.

```php
return [

    /*
     * Each settings class used in your application must be registered, you can
     * put them (manually) here.
     */
    'settings' => [

    ],

    /*
     * The path where the settings classes will be created.
     */
    'setting_class_path' => app_path('Settings'),

    /*
     * In these directories settings migrations will be stored and ran when migrating. A settings
     * migration created via the make:settings-migration command will be stored in the first path or
     * a custom defined path when running the command.
     */
    'migrations_paths' => [
        database_path('settings'),
    ],

    /*
     * When no repository was set for a settings class the following repository
     * will be used for loading and saving settings.
     */
    'default_repository' => 'database',

    /*
     * Settings will be stored and loaded from these repositories.
     */
    'repositories' => [
        'database' => [
            'type' => Spatie\LaravelSettings\SettingsRepositories\DatabaseSettingsRepository::class,
            'model' => null,
            'table' => null,
            'connection' => null,
        ],
        'redis' => [
            'type' => Spatie\LaravelSettings\SettingsRepositories\RedisSettingsRepository::class,
            'connection' => null,
            'prefix' => null,
        ],
    ],

    /*
     * The encoder and decoder will determine how settings are stored and
     * retrieved in the database. By default, `json_encode` and `json_decode`
     * are used.
     */
    'encoder' => null,
    'decoder' => null,

    /*
     * The contents of settings classes can be cached through your application,
     * settings will be stored within a provided Laravel store and can have an
     * additional prefix.
     */
    'cache' => [
        'enabled' => env('SETTINGS_CACHE_ENABLED', false),
        'store' => null,
        'prefix' => null,
        'ttl' => null,
    ],

    /*
     * These global casts will be automatically used whenever a property within
     * your settings class isn't a default PHP type.
     */
    'global_casts' => [
        DateTimeInterface::class => Spatie\LaravelSettings\SettingsCasts\DateTimeInterfaceCast::class,
        DateTimeZone::class => Spatie\LaravelSettings\SettingsCasts\DateTimeZoneCast::class,
     // Spatie\DataTransferObject\DataTransferObject::class => Spatie\LaravelSettings\SettingsCasts\DtoCast::class,
        Spatie\LaravelData\Data::class => Spatie\LaravelSettings\SettingsCasts\DataCast::class,
    ],

    /*
     * The package will look for settings in these paths and automatically
     * register them.
     */
    'auto_discover_settings' => [
        app_path('Settings'),
    ],

    /*
     * Automatically discovered settings classes can be cached, so they don't
     * need to be searched each time the application boots up.
     */
    'discovered_settings_cache_path' => base_path('bootstrap/cache'),
];
```

--------------------------------

### Define a settings class with group()

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Define a settings class by extending the Settings base class and declaring public properties for each setting. The group() method returns the storage group name, here 'general'.

```php
class GeneralSettings extends Settings
{
    public string $site_name;
    
    public bool $site_active;
    
    public static function group(): string
    {
        return 'general';
    }
}
```

--------------------------------

### Create a settings migration with artisan make:settings-migration

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Creates a new migration file in database/settings where you can add properties and their default values.

```bash
php artisan make:settings-migration CreateGeneralSettings
```

--------------------------------

### Generate a settings class with artisan make:setting

Source: https://github.com/spatie/laravel-settings/blob/main/README.md

Generates a new settings class. Before running, check that the setting_class_path config is correctly set; a path option is optional.

```bash
php artisan make:setting SettingName --group=groupName
```

--------------------------------

### Settings constructor

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Settings.md

Final constructor accepting an optional array of initial values. When non-empty, values are loaded immediately; otherwise they are loaded lazily on first property access.

```php
final public function __construct(array $values = [])
```

--------------------------------

### Per-repository cache for tenant-aware database repository

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/configuration.md

Configure a per-repository cache for a tenant-aware database repository. The 'landlord' repository uses the DatabaseSettingsRepository with a dedicated connection and cache settings, including a prefix and TTL.

```php
'repositories' => [
    'landlord' => [
        'type' => Spatie\LaravelSettings\SettingsRepositories\DatabaseSettingsRepository::class,
        'model' => null,
        'table' => null,
        'connection' => 'landlord',
        'cache' => [
            'enabled' => env('SETTINGS_CACHE_ENABLED', false),
            'store' => null,
            'prefix' => 'landlord',
            'ttl' => null,
        ],
    ],
],
```

--------------------------------

### Constructor for SettingsContainer

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsContainer.md

Constructor that accepts an Illuminate Container instance, used for scoped bindings.

```php
public function __construct(Container $container)
```

--------------------------------

### Read/write through the cache using SettingsCacheFactory

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsCache.md

Builds a cache instance from the SettingsCacheFactory and retrieves or creates a settings object. If the cache returns null, a new GeneralSettings is created and put into the cache.

```php
$cache = app(SettingsCacheFactory::class)->build(GeneralSettings::class::repository());

$restored = $cache->get(GeneralSettings::class::cacheKey()); // ?Settings

if ($restored === null) {
    $settings = new GeneralSettings();
    $cache->put($settings);
} else {
    $settings = $restored;
}
```

--------------------------------

### getName(): string

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsConfig.md

Returns the settings class-string.

```APIDOC
## getName(): string

### Description
Returns the settings class-string.

### Method
getName

### Signature
`public function getName(): string`

### Returns
- **string** - The settings class-string.

```

--------------------------------

### Fake settings in tests with optional strict mode

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Settings.md

Shows how to fake a settings class in tests, with an optional second parameter to throw MissingSettings when not all properties are overwritten.

```php
DateSettings::fake([
    'birth_date' => new DateTime('16-05-1994'),
]);

// Throw MissingSettings when not every property is overwritten:
DateSettings::fake([
    'birth_date' => new DateTime('16-05-1994'),
], false);
```

--------------------------------

### toArray()

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/Settings.md

Returns the settings as an array.

```APIDOC
## toArray()

### Description
`toCollection()->toArray()`.

### Method
toArray

### Parameters
None

### Returns
- array - The settings array.

### Source
`src/Settings.php:237`
```

--------------------------------

### Inject a settings class in a controller

Source: https://github.com/spatie/laravel-settings/blob/main/_autodocs/api-reference/SettingsContainer.md

Shows how to resolve a settings class instance via the container, which injects a scoped GeneralSettings instance.

```php
// Inside a controller — container injects a scoped GeneralSettings:
$settings = resolve(GeneralSettings::class);
```
Tokens:
Raw