PHPackages                             gsebastiao/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. gsebastiao/laravel-settings

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

gsebastiao/laravel-settings
===========================

Pacote Laravel para gestão de settings com chave composta, hierarquia de contexto (global → tenant → user) e cast dinâmico.

v1.2.2(1mo ago)06MITPHPPHP ^8.2CI failing

Since Jul 11Pushed 1mo agoCompare

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

READMEChangelogDependencies (12)Versions (5)Used By (0)

Laravel Settings
================

[](#laravel-settings)

> Pacote Laravel para gestão de settings com chave composta, hierarquia de contexto (global → tenant → user) e cast dinâmico de valores.

[![PHP](https://camo.githubusercontent.com/187240af044d09d5b14a1d9d9ebdf3f7a993e4c7bc09bdb46b4ba661a891bf5b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d626c7565)](https://php.net)[![Laravel](https://camo.githubusercontent.com/94e9c8450999913235efa10e8b4593c4cc12190aee2829d4e12fef3a1b0cb2df/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302532463131253246313225324631332d726564)](https://laravel.com)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE)

---

Instalação
----------

[](#instalação)

```
composer require gsebastiao/laravel-settings
```

O pacote usa **auto-discovery** — o `SettingsServiceProvider` e o alias `Settings` são registados automaticamente.

Corre a migration:

```
php artisan migrate
```

---

Publicar recursos (opcional)
----------------------------

[](#publicar-recursos-opcional)

```
# Publicar tudo (config + migrations)
php artisan vendor:publish --tag=settings

# Só configuração
php artisan vendor:publish --tag=settings-config

# Só migrations (para personalizar)
php artisan vendor:publish --tag=settings-migrations
```

---

Configuração
------------

[](#configuração)

Após publicar, edita `config/settings.php`:

```
return [
    'cache' => [
        'ttl'    => env('SETTINGS_CACHE_TTL', 300),      // segundos
        'prefix' => env('SETTINGS_CACHE_PREFIX', 'settings:'),
        'driver' => env('SETTINGS_CACHE_DRIVER', null),  // null = driver padrão
    ],
    'table'        => env('SETTINGS_TABLE', 'settings'),
    'default_cast' => 'string',
    'contexts' => [
        'default' => 'global',
        'user'    => 'user',    // → 'user:42'
        'tenant'  => 'tenant',  // → 'tenant:5'
    ],
];
```

Ou via `.env`:

```
SETTINGS_CACHE_TTL=600
SETTINGS_TABLE=app_settings
SETTINGS_CACHE_DRIVER=redis
```

---

Uso
---

[](#uso)

### Helper global `setting()`

[](#helper-global-setting)

```
// Ler (com default)
$name = setting('general.name', 'Laravel App');

// Ler com contexto do utilizador autenticado
$theme = setting('ui.theme', 'light', context: SettingsService::userContext());

// Shortcut idêntico
$theme = userSetting('ui.theme', 'light');

// Aceder ao serviço (para escrita, lock, etc.)
setting()->set('ui.theme', 'dark', context: 'user:42');
```

### Facade `Settings::`

[](#facade-settings)

```
use Gsebastiao\Settings\Facades\Settings;
use Gsebastiao\Settings\Services\SettingsService;

// Leitura
Settings::get('ui.font_size', 14);
Settings::get('ui.language', 'pt', context: Settings::userContext());
Settings::all('ui', context: 'user:42');   // Collection ['theme' => 'dark', ...]
Settings::has('general.name');

// Escrita
Settings::set('general.name', 'Nova Empresa');
Settings::set('ui.theme', 'dark', context: 'user:42');
Settings::set('ui.language', 'pt', options: [
    'metadata' => ['input' => 'select', 'options' => ['pt', 'en', 'es', 'fr']],
]);

// Gestão
Settings::lock('general.version');         // bloqueia overrides por outros contextos
Settings::forget('ui.theme', context: 'user:42');
Settings::forgetContext('user:42');        // limpar ao apagar utilizador
```

### Injecção de dependência

[](#injecção-de-dependência)

```
use Gsebastiao\Settings\Services\SettingsService;

class ProfileController extends Controller
{
    public function __construct(private SettingsService $settings) {}

    public function update(Request $request): RedirectResponse
    {
        $ctx = SettingsService::userContext(); // 'user:42'

        $this->settings->set('ui.language',  $request->language,  $ctx);
        $this->settings->set('ui.font_size', $request->font_size, $ctx, cast: 'int');
        $this->settings->set('ui.theme',     $request->theme,     $ctx);

        return back()->with('success', 'Preferências guardadas.');
    }
}
```

---

Hierarquia de contexto
----------------------

[](#hierarquia-de-contexto)

```
setting('ui.language', 'pt', context: 'user:42')

  1. Existe 'ui.language' @ 'user:42'? ──→ SIM  → devolve 'en'
                                        └→ NÃO  → tenta 'global'
  2. Existe 'ui.language' @ 'global'?  ──→ SIM  → devolve 'pt'
                                        └→ NÃO  → devolve default ('pt')

```

Context helperResultado`SettingsService::globalContext()``'global'``SettingsService::userContext()``'user:42'` (autenticado)`SettingsService::userContext(99)``'user:99'``SettingsService::userContext($model)``'user:{$model->id}'``SettingsService::tenantContext(5)``'tenant:5'`---

Cast dinâmico
-------------

[](#cast-dinâmico)

O value é sempre guardado como texto. O campo `cast` controla a deserialização:

`cast`Tipo PHP retornado`string``string``int``int``float``float``bool``bool``json` / `array``array``date``Carbon`Se não especificares `cast`, é inferido automaticamente a partir do valor:

```
Settings::set('ui.font_size', 14);     // cast=int  (inferido)
Settings::set('ui.dark_mode', true);   // cast=bool (inferido)
Settings::set('ui.tags', ['a', 'b']);  // cast=json (inferido)
```

---

is\_locked — bloquear overrides
-------------------------------

[](#is_locked--bloquear-overrides)

```
// Impede que qualquer contexto mais específico sobrescreva esta setting
Settings::set('general.version', '1.0.0', options: ['is_locked' => true]);
// ou após criar:
Settings::lock('general.version');
```

---

metadata — dados para o frontend
--------------------------------

[](#metadata--dados-para-o-frontend)

```
Settings::set('ui.language', 'pt', options: [
    'metadata' => [
        'input'   => 'select',
        'options' => ['pt', 'en', 'es', 'fr'],
        'label'   => 'Idioma da interface',
    ]
]);

// No controller de admin — construir formulário dinamicamente
$settings  = Settings::all('ui');
$metadatas = \Gsebastiao\Settings\Models\Setting::forNamespace('ui')->pluck('metadata', 'key');
```

---

Herança de settings para novos utilizadores
-------------------------------------------

[](#herança-de-settings-para-novos-utilizadores)

Quando um utilizador é cadastrado, podes copiar as settings do contexto global (ou do tenant) para o contexto pessoal do utilizador. Depois disso, o utilizador pode personalizar as suas próprias settings livremente.

### Modo normal (sem multitenancy)

[](#modo-normal-sem-multitenancy)

Copia todas as settings de `global` → `user:42`:

```
use Gsebastiao\Settings\Services\SettingsInheritance;

class UserController extends Controller
{
    public function store(Request $request, SettingsInheritance $inheritance): RedirectResponse
    {
        $user = User::create($request->validated());

        // Copia todas as settings globais para o contexto do utilizador
        $report = $inheritance->forUser($user);
        // ['copied' => 6, 'skipped' => 0, 'namespaces' => ['ui', 'mail']]

        return redirect()->route('users.index');
    }
}
```

### Modo SaaS multitenant

[](#modo-saas-multitenant)

Copia de `tenant:5` → `global` → `user:42` (tenant sobrepõe global):

```
$report = $inheritance->forUser($user, tenantId: $user->tenant_id);
```

### Copiar só namespaces específicos

[](#copiar-só-namespaces-específicos)

```
// Só as settings de UI e mail
$report = $inheritance->forUser($user, namespaces: ['ui', 'mail']);

// Tenant + só UI
$report = $inheritance->forUser($user, tenantId: 5, namespaces: ['ui']);
```

### Pré-visualizar antes de copiar (dry run)

[](#pré-visualizar-antes-de-copiar-dry-run)

```
$preview = $inheritance->preview($user, tenantId: 5);

// Retorna Collection com o que seria copiado:
// [
//   'ui.theme'    => ['value' => 'dark', 'source' => 'tenant:5', 'action' => 'copy'],
//   'ui.language' => ['value' => 'pt',   'source' => 'global',   'action' => 'copy'],
//   'ui.logo'     => ['value' => '...',  'source' => 'user:42',  'action' => 'skip'],
// ]
```

### Repor settings de um utilizador (reset)

[](#repor-settings-de-um-utilizador-reset)

Apaga os registos `user:X` e volta a copiar das fontes:

```
// Reset total
$inheritance->resetUser($user);

// Reset só do namespace UI
$inheritance->resetUser($user, namespaces: ['ui']);

// Reset multitenant
$inheritance->resetUser($user, tenantId: $user->tenant_id);
```

### Relatório de cópia

[](#relatório-de-cópia)

O método `forUser()` e `resetUser()` retornam sempre um relatório:

```
[
    'copied'     => 6,              // settings copiadas
    'skipped'    => 1,              // settings ignoradas (já existiam)
    'namespaces' => ['ui', 'mail'], // namespaces afectados
]
```

---

Helpers disponíveis
-------------------

[](#helpers-disponíveis)

```
setting('general.name', 'default')                        // ler
setting('ui.theme', 'light', context: 'user:42')         // ler com contexto
setting()                                                 // retorna o serviço

userSetting('ui.font_size', 14)                          // contexto do user autenticado
userSetting('ui.font_size', 14, user: $user)             // contexto de user específico

tenantSetting('ui.logo', 'logo.png', tenantId: 5)       // contexto de tenant
```

---

Estrutura do pacote
-------------------

[](#estrutura-do-pacote)

```
gsebastiao/laravel-settings/
├── src/
│   ├── Casts/
│   │   └── SettingValueCast.php         ← cast dinâmico por coluna
│   ├── Contracts/
│   │   └── SettingsRepository.php       ← interface (para substituição)
│   ├── Facades/
│   │   └── Settings.php                 ← facade com docblock para IDE
│   ├── Models/
│   │   └── Setting.php                  ← Eloquent, PK composta, tabela configurável
│   ├── Services/
│   │   └── SettingsService.php          ← lógica principal
│   ├── SettingsServiceProvider.php      ← registo, publish, migrations
│   └── helpers.php                      ← setting() / userSetting() / tenantSetting()
├── config/
│   └── settings.php
├── database/
│   └── migrations/
│       └── ..._create_settings_table.php
├── tests/
│   └── Unit/
│       └── SettingsServiceTest.php
├── composer.json
└── phpunit.xml

```

---

Testes
------

[](#testes)

```
composer test
# ou
./vendor/bin/phpunit
```

---

Licença
-------

[](#licença)

MIT © [Gsebastiao](https://github.com/gsebastiao)

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance92

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

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 ~1 days

Total

4

Last Release

37d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/aab336e4460b96481b6b91cc9b0b101959b827f766ab3ac08b77496b9076b32f?d=identicon)[gsebastiao](/maintainers/gsebastiao)

---

Top Contributors

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

---

Tags

laravelconfigurationSettingsContextmulti-tenant

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

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

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

###  Alternatives

[mongodb/laravel-mongodb

A MongoDB based Eloquent model and Query builder for Laravel

7.1k8.9M110](/packages/mongodb-laravel-mongodb)[mike-bronner/laravel-model-caching

Automatic caching for Eloquent models.

2.4k161.4k2](/packages/mike-bronner-laravel-model-caching)[psalm/plugin-laravel

Psalm plugin for Laravel

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

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

265.2k](/packages/aedart-athenaeum)[api-platform/laravel

API Platform support for Laravel

58190.1k21](/packages/api-platform-laravel)[forjedio/inertia-table

Backend-driven dynamic tables for Laravel + Inertia.js

272.0k](/packages/forjedio-inertia-table)

PHPackages © 2026

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