PHPackages                             oi-lab/oi-laravel-settings - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. oi-lab/oi-laravel-settings

ActiveLibrary[Utility & Helpers](/categories/utility)

oi-lab/oi-laravel-settings
==========================

Configuration settings management for Laravel with scoped values, typed casts and spatie/laravel-data value objects.

v1.0.4(1mo ago)0453↓42.9%2MITPHPPHP ^8.2CI failing

Since Jul 2Pushed 1mo agoCompare

[ Source](https://github.com/oi-lab/oi-laravel-settings)[ Packagist](https://packagist.org/packages/oi-lab/oi-laravel-settings)[ RSS](/packages/oi-lab-oi-laravel-settings/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (36)Versions (6)Used By (2)

[![OI Laravel Settings](./assets/github-preview.png)](./assets/github-preview.png)

OI Laravel Settings
===================

[](#oi-laravel-settings)

[![Latest Version on Packagist](https://camo.githubusercontent.com/e3ec843ae962a2d23806aec2982becb33e83e5300f4b9304157b642b73c24af7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f692d6c61622f6f692d6c61726176656c2d73657474696e67732e737667)](https://packagist.org/packages/oi-lab/oi-laravel-settings)[![Total Downloads](https://camo.githubusercontent.com/779e0e7e8b9c928df2df53bfa92d469f7435c9c4b58630cf3791beec04857eee/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f692d6c61622f6f692d6c61726176656c2d73657474696e67732e737667)](https://packagist.org/packages/oi-lab/oi-laravel-settings)[![Tests](https://camo.githubusercontent.com/e3bfc8ba7ad2c44c12b8b2e534b446280f16773072c894e6cf51a97745fbeaca/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6f692d6c61622f6f692d6c61726176656c2d73657474696e67732f74657374732e796d6c3f6c6162656c3d7465737473)](https://github.com/oi-lab/oi-laravel-settings/actions)[![License](https://camo.githubusercontent.com/a8ad610dc7ad29d9b8dcc05d0b3f6a74570b76028fd37425a4d437ca18bb57f6/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6f692d6c61622f6f692d6c61726176656c2d73657474696e6773)](LICENSE)

Scoped, typed application settings for Laravel. Key/value pairs live in a `settings` table, are cached per scope, and are cast to real PHP types — including [spatie/laravel-data](https://spatie.be/docs/laravel-data) value objects — through a configurable type registry.

Features
--------

[](#features)

- Key/value settings persisted in a `settings` table, unique per `[scope, key]`.
- Per-scope resolution with global fallback: `current scope → global → default`, driven by a configurable scope resolver or a runtime override.
- Type registry casting the stored value from a sibling `type` column — primitives (`string`, `integer`, `float`, `boolean`, `json`) and any `spatie/laravel-data` `Data` value object stored as JSON.
- Per-scope caching, busted automatically on every write.
- `Settings` facade, a `setting()` helper, and an injectable `SettingsManager`.
- Definition-driven `SettingsSeeder` base class and a `SettingFactory`.
- Swappable model resolved through `OiLaravelSettings`, never hardcoded.

How It Works
------------

[](#how-it-works)

A setting is a row keyed by `[scope, key]`. `scope` is any `string|int`identifier (a shop id, a team id, a locale…) or `null` for the global layer. Reads resolve in order — the current scope, then global, then the caller's default — so a single global default can be overridden per scope.

The `value` column is stored as a string and cast to its runtime type from the `type` column via the type registry, so booleans come back as `bool`, JSON as arrays, and registered `Data` classes as fully-typed value objects.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11, 12, or 13
- `spatie/laravel-data` ^4.0

Installation
------------

[](#installation)

```
composer require oi-lab/oi-laravel-settings
```

### Publish & Migrate

[](#publish--migrate)

```
php artisan migrate
```

Publish the configuration or migration if you need to customise them:

```
php artisan vendor:publish --tag=oi-laravel-settings-config
php artisan vendor:publish --tag=oi-laravel-settings-migrations
```

Configuration
-------------

[](#configuration)

`config/oi-laravel-settings.php` controls the table, model, scope resolver, cache and the type registry:

```
'table' => 'settings',

'models' => [
    'setting' => \OiLab\OiLaravelSettings\Models\Setting::class,
],

'scope_resolver' => null,   // null | Closure | invokable class-string
'default_scope' => null,

'cache' => [
    'enabled' => true,
    'store' => null,        // null = default store
    'prefix' => 'oi-settings',
    'ttl' => null,          // null = forever, seconds otherwise
],

'default_type' => 'string',

'types' => [
    'string' => 'string',
    'integer' => 'integer',
    'float' => 'float',
    'boolean' => 'boolean',
    'json' => 'json',
    'mail' => \OiLab\OiLaravelSettings\Data\MailContent::class,
],
```

See the [configuration reference](docs/configuration/configuration.md).

Usage
-----

[](#usage)

### Reading & writing

[](#reading--writing)

```
use OiLab\OiLaravelSettings\Facades\Settings;

Settings::set('SITE_ONLINE', true, type: 'boolean', label: 'Site online');
Settings::get('SITE_ONLINE');            // true
Settings::has('SITE_ONLINE');            // true
Settings::all();                         // merged global + current scope
Settings::delete('SITE_ONLINE');

// Helper
setting('SITE_ONLINE', false);
setting(['THEME' => 'dark']);
```

### Scopes

[](#scopes)

Every setting belongs to an optional `scope` (`null` = global). Reads resolve `current scope → global → default`.

```
Settings::set('THEME', 'dark', scope: null);      // global default
Settings::set('THEME', 'light', scope: 'shop-2'); // override
Settings::get('THEME', scope: 'shop-9');          // 'dark' (fallback)

// Resolve the current scope (e.g. from the active shop/tenant):
Settings::resolveScopeUsing(fn () => app('current_shop_id'));
```

### Typed value objects

[](#typed-value-objects)

Register a `Spatie\LaravelData\Data` class under a type key and it is cast automatically to/from JSON:

```
// config/oi-laravel-settings.php
'types' => [
    'mail' => \OiLab\OiLaravelSettings\Data\MailContent::class,
    'address' => \App\Data\AddressData::class,
],

use OiLab\OiLaravelSettings\Data\MailContent;

Settings::set('WELCOME_MAIL', new MailContent(subject: 'Hi'), type: 'mail');
Settings::get('WELCOME_MAIL'); // MailContent instance
```

### Seeding

[](#seeding)

```
use OiLab\OiLaravelSettings\Seeders\SettingsSeeder;

class AppSettingsSeeder extends SettingsSeeder
{
    protected function definitions(): array
    {
        return [
            ['key' => 'SITE_ONLINE', 'value' => true, 'type' => 'boolean'],
            ['key' => 'THEME', 'value' => 'light', 'scope' => 'shop-2'],
        ];
    }
}
```

Customizing the Model
---------------------

[](#customizing-the-model)

The model is resolved through `OiLaravelSettings::settingModel()`, so you can point `config('oi-laravel-settings.models.setting')` at a subclass to add relations or behaviour. See [Custom model](docs/advanced/custom-model.md).

AI Assistant Skills
-------------------

[](#ai-assistant-skills)

The package ships an `oilab-laravel-settings` skill. Install it into a host app:

```
php artisan oi:install-ai-skill
```

Testing
-------

[](#testing)

```
composer test
```

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

When contributing:

1. Write tests for new features
2. Ensure all tests pass: `vendor/bin/pest`
3. Follow existing code style
4. Update documentation as needed

License
-------

[](#license)

The MIT License (MIT). Please see the [License File](LICENSE) for more information.

Credits
-------

[](#credits)

**[Olivier Lacombe](https://www.olacombe.com)** - Creator and maintainer

Olivier is a Product & Technology Director based in Montpellier, France, with over 20 years of experience innovating in UX/UI and emerging technologies. He specializes in guiding enterprises toward cutting-edge digital solutions, combining user-centered design with continuous optimization and artificial intelligence integration.

**Projects & Resources:**

- [OI Dev Docs](https://dev.olacombe.com) - Documentation for all Open Source OI Lab packages
- [OnAI](https://onai.olacombe.com) - Training courses and masterclasses on generative AI for businesses
- [Promptr](https://promptr.olacombe.com) - Prompt engineering Management Platform

Support
-------

[](#support)

For support, please open an issue on the [GitHub repository](https://github.com/oi-lab/oi-laravel-settings/issues).

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance92

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

5

Last Release

33d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/369876?v=4)[Olivier Lacombe](/maintainers/olacombe)[@olacombe](https://github.com/olacombe)

---

Top Contributors

[![olacombe](https://avatars.githubusercontent.com/u/369876?v=4)](https://github.com/olacombe "olacombe (4 commits)")

---

Tags

laravelconfigurationSettingsspatie-laravel-data

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/oi-lab-oi-laravel-settings/health.svg)

```
[![Health](https://phpackages.com/badges/oi-lab-oi-laravel-settings/health.svg)](https://phpackages.com/packages/oi-lab-oi-laravel-settings)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.4M354](/packages/psalm-plugin-laravel)[laravel/ai

The official AI SDK for Laravel.

1.1k4.6M327](/packages/laravel-ai)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

265.2k](/packages/aedart-athenaeum)[propaganistas/laravel-disposable-email

Disposable email validator

6023.2M7](/packages/propaganistas-laravel-disposable-email)[api-platform/laravel

API Platform support for Laravel

58190.1k21](/packages/api-platform-laravel)[harris21/laravel-fuse

Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures.

46273.9k](/packages/harris21-laravel-fuse)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)